想要一种更简单的方式来安装和配置 nullclaw 并带有 UI？试试 nullhub！（目前处于 beta 阶段）

nullhub 为 Null 生态系统提供了 UI 层：简化 nullclaw 的设置与配置、来自 nullboiler 的编排（orchestration）、来自 nullwatch 的可观测性（observability），以及来自 nulltickets 的任务追踪。

NullClaw

零开销。零妥协。100% Zig。100% 无依赖。
678 KB 二进制文件。约 1 MB 内存占用。启动时间 <2 毫秒。可在任何带 CPU 的设备上运行。

最小的完全自主 AI 助手基础设施 —— 一个静态 Zig 二进制文件，可放入任意 $5 开发板，毫秒级启动，仅需 libc 即可运行。

文档：English · 中文 · Contributing · Discord

678 KB 二进制文件 · <2 ms 启动时间 · 5,300+ 测试用例 · 50+ 提供商（providers）· 19 种通道（channels）· 所有组件均可插拔

特性

• 极致小巧：678 KB 静态二进制文件 —— 无运行时、无虚拟机、无框架开销。
• 近零内存占用：峰值 RSS 约 1 MB。可在最便宜的 ARM 单板计算机（SBC）和微控制器上舒适运行。
• 瞬时启动：Apple Silicon 上 <2 ms，0.8 GHz 边缘核心上 <8 ms。
• 真正可移植：单个自包含二进制文件，支持 ARM、x86 和 RISC-V。随处放置，即刻运行。
• 功能完整：50+ 提供商、19 种通道、35+ 工具、10 种记忆引擎、多层沙箱、隧道、硬件外设、MCP、子代理（subagents）、流式处理、语音 —— 全栈功能一应俱全。

为什么选择 nullclaw

• 默认精简：Zig 编译为极小的静态二进制文件。无分配器开销、无垃圾回收器、无运行时。
• 设计安全：配对机制、严格沙箱（landlock、firejail、bubblewrap、docker）、显式白名单、工作区作用域、加密密钥。
• 完全可替换：核心系统采用虚表接口（vtable interfaces）（提供商、通道、工具、记忆、隧道、外设、观察器、运行时）。
• 无厂商锁定：兼容 OpenAI 的提供商支持 + 可插拔的自定义端点。

基准快照

本地机器基准测试（macOS arm64，2026 年 2 月），已针对 0.8 GHz 边缘硬件进行归一化。

	OpenClaw	NanoBot	PicoClaw	ZeroClaw	🦞 NullClaw
语言	TypeScript	Python	Go	Rust	Zig
内存占用	> 1 GB	> 100 MB	< 10 MB	< 5 MB	~1 MB
启动时间 (0.8 GHz)	> 500 s	> 30 s	< 1 s	< 10 ms	< 8 ms
二进制大小	~28 MB (dist)	N/A (脚本)	~8 MB	~8.8 MB	678 KB
测试用例数	—	—	—	1,017	5,300+
源文件数量	~400+	—	—	~120	~230
成本	Mac Mini $599	Linux SBC ~$50	Linux 开发板 $10	任意 $10 硬件	任意 $5 硬件

使用 /usr/bin/time -l 在 ReleaseSmall 构建下测量。nullclaw 是一个静态二进制文件，无任何运行时依赖。

本地复现：

zig build -Doptimize=ReleaseSmall
ls -lh zig-out/bin/nullclaw

/usr/bin/time -l zig-out/bin/nullclaw --help
/usr/bin/time -l zig-out/bin/nullclaw status

文档

如果你想以最短路径安装、配置、操作或扩展 nullclaw，请从此处开始。

本地化文档位于 docs/en/ 和 docs/zh/ 目录下。使用下方链接可直接跳转至所需页面。

需求	English	中文
入门指南	docs/en/README.md	docs/zh/README.md
安装	docs/en/installation.md	docs/zh/installation.md
配置	docs/en/configuration.md	docs/zh/configuration.md
命令	docs/en/commands.md	docs/zh/commands.md
开发	docs/en/development.md	docs/zh/development.md
运维	docs/en/usage.md	docs/zh/usage.md
架构	docs/en/architecture.md	docs/zh/architecture.md
安全	docs/en/security.md	docs/zh/security.md
Gateway API	docs/en/gateway-api.md	docs/zh/gateway-api.md

• 专项指南：CONTRIBUTING.md、SECURITY.md、SIGNAL.md

选择你的路径

目标	首先打开	然后前往
英文首次运行	docs/en/README.md	docs/en/installation.md → docs/en/configuration.md → docs/en/usage.md
中文快速上手	docs/zh/README.md	docs/zh/installation.md → docs/zh/configuration.md → docs/zh/usage.md
查找合适的 CLI 命令	docs/en/commands.md / docs/zh/commands.md	nullclaw help → 特定任务的子命令页面
贡献代码或文档	CONTRIBUTING.md	docs/en/development.md / docs/zh/development.md → 相关架构页面
部署运维或安全保障	docs/en/usage.md / docs/zh/usage.md	docs/en/security.md / docs/zh/security.md → Gateway API

阅读本 README 之后

• 新用户：跳转至 docs/en/README.md 或 docs/zh/README.md，并按照引导顺序阅读。
• 想快速查看命令：打开 docs/en/commands.md 或 docs/zh/commands.md。
• 想提交 PR（Pull Request）：先阅读 CONTRIBUTING.md，再阅读 docs/en/development.md 或 docs/zh/development.md。

快速开始

1) 推荐安装方式（Homebrew）

最简单的方式：安装一个开箱即用的二进制文件，无需额外运行时依赖。

brew install nullclaw
nullclaw --help

2) 从源码构建

前提条件：必须使用 Zig 0.15.2（精确版本）。
0.16.0-dev 及其他 Zig 版本目前不受支持，可能导致构建失败。
构建前请验证：zig version 应输出 0.15.2。

git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig build -Doptimize=ReleaseSmall
zig build test --summary all

将 nullclaw 添加到 PATH：

macOS/Linux (zsh/bash):

zig build -Doptimize=ReleaseSmall -p "$HOME/.local"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
# 或 ~/.bashrc

Windows (PowerShell):

zig build -Doptimize=ReleaseSmall -p "$HOME\.local"

$bin = "$HOME\.local\bin"
$user_path = [Environment]::GetEnvironmentVariable("Path", "User")
if (-not ($user_path -split ";" | Where-Object { $_ -eq $bin })) {
  [Environment]::SetEnvironmentVariable("Path", "$user_path;$bin", "User")
}
$env:Path = "$env:Path;$bin"

然后执行：

nullclaw --help

3) 常用命令

# 快速设置
nullclaw onboard --api-key sk-... --provider openrouter

# 或交互式向导
nullclaw onboard --interactive

# 聊天
nullclaw agent -m "Hello, nullclaw!"

# 交互模式
nullclaw agent

# 启动网关运行时（包含网关 + 所有已配置的通道/账户 + 心跳 + 调度器）
nullclaw gateway                # 默认：127.0.0.1:3000
nullclaw gateway --port 8080    # 自定义端口

# 检查状态
nullclaw status

# 运行系统诊断
nullclaw doctor

# 检查通道健康状况
nullclaw channel status

# 启动特定通道
nullclaw channel start telegram
nullclaw channel start discord
nullclaw channel start signal

# 管理后台服务
# Linux 支持 systemd 用户服务和 OpenRC
nullclaw service install
nullclaw service status

# 从 OpenClaw 迁移记忆数据
nullclaw migrate openclaw --dry-run
nullclaw migrate openclaw

Edge MVP（混合主机 + WASM 逻辑）

如果你想在边缘部署（Cloudflare Worker）中同时使用 Telegram 和 OpenAI，并将智能体策略保留在 WASM 中，请参阅：

examples/edge/cloudflare-worker/

该模式将网络通信和密钥保留在边缘主机中，只需替换一个小型 Zig WASM 模块即可更新或切换逻辑。

架构

每个子系统都是一个 vtable 接口 —— 只需修改配置即可更换实现，无需更改任何代码。

子系统	接口	内置支持	可扩展
AI 模型	Provider	50+ 提供商（OpenRouter、Anthropic、OpenAI、Azure OpenAI、Gemini、Vertex AI、Ollama、Venice、Groq、Mistral、xAI、DeepSeek、Together、Fireworks、Perplexity、Cohere、Bedrock 以及众多兼容 OpenAI 的端点）	custom:https://your-api.com —— 任意兼容 OpenAI 的 API
通道（Channels）	Channel	CLI、Telegram、Signal、Discord、Slack、iMessage、Matrix、WhatsApp、Webhook、IRC、Lark/飞书、OneBot、Line、钉钉、Email、Nostr、QQ、MaixCam、Mattermost	任意消息 API
记忆（Memory）	Memory	SQLite（带混合搜索：FTS5 + 向量余弦相似度）、Markdown、ClickHouse、PostgreSQL、Redis、LanceDB、Lucid、LRU、API	任意持久化后端
工具（Tools）	Tool	shell、file_read、file_write、file_edit、file_edit_hashed、file_read_hashed、file_append、memory_store、memory_recall、memory_forget、memory_list、browser_open、screenshot、composio、http_request、web_fetch、web_search、delegate、schedule、hardware_info、hardware_memory、pushover、message、spawn、git、image、i2c、spi 等	任意能力
可观测性（Observability）	Observer	Noop、Log、File、Multi	Prometheus、OTel
运行时（Runtime）	RuntimeAdapter	Native、Docker（沙箱）、WASM（wasmtime）	任意运行时
安全（Security）	Sandbox	Landlock、Firejail、Bubblewrap、Docker、自动检测	任意沙箱后端
身份（Identity）	IdentityConfig	OpenClaw（Markdown）、AIEOS v1.1（JSON）	任意身份格式
隧道（Tunnel）	Tunnel	None、Cloudflare、Tailscale、ngrok、Custom	任意隧道二进制
心跳（Heartbeat）	Engine	HEARTBEAT.md 中的周期性任务	—
技能（Skills）	Loader	TOML/JSON 清单或 SKILL.md 中的 YAML frontmatter	社区技能包
外设（Peripherals）	Peripheral	Serial、Arduino、树莓派 GPIO、STM32/Nucleo	任意硬件接口
定时任务（Cron）	Scheduler	Cron 表达式 + 单次定时器（带 JSON 持久化）	—

记忆系统

核心路径完全自研，无外部依赖：

层级	实现
向量数据库	嵌入向量以 BLOB 形式存储于 SQLite，支持余弦相似度搜索
关键词搜索	使用 FTS5 虚拟表，基于 BM25 评分
混合融合	加权融合（可配置向量/关键词权重）
嵌入模型	EmbeddingProvider vtable —— OpenAI、自定义 URL 或 noop
数据清理	自动归档并清除过期记忆
快照	支持导出/导入完整记忆状态用于迁移
引擎	SQLite（默认）、Markdown、ClickHouse、PostgreSQL、Redis、LanceDB、Lucid、LRU、API、None

{
  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "embedding_provider": "openai",
    "vector_weight": 0.7,
    "keyword_weight": 0.3,
    "hygiene_enabled": true,
    "snapshot_enabled": false
  }
}

安全

nullclaw 在每一层都强制实施安全措施。

#	项目	状态	实现方式
1	网关默认不对外暴露	已完成	默认绑定 127.0.0.1。除非配置了隧道或显式启用 allow_public_bind，否则拒绝绑定 0.0.0.0。
2	配对认证必需	已完成	启动时生成 6 位一次性验证码。通过 POST /pair 交换获取 bearer token。
3	文件系统作用域限制	已完成	默认启用 workspace_only = true。阻止空字节注入，检测符号链接逃逸。
4	仅允许通过隧道访问	已完成	若无活跃隧道，网关拒绝公开绑定。支持 Tailscale、Cloudflare、ngrok 或自定义隧道。
5	沙箱隔离	已完成	自动检测最佳后端：Landlock、Firejail、Bubblewrap 或 Docker。
6	加密存储密钥	已完成	API 密钥使用本地密钥文件通过 ChaCha20-Poly1305 加密。
7	资源限制	已完成	可配置内存、CPU、磁盘及子进程限制。
8	审计日志	已完成	带签名的事件追踪，可配置保留策略。

频道白名单（Channel Allowlists）

• 空白名单 = 拒绝所有入站消息
• "*" = 允许全部（显式选择加入）
• 其他情况 = 精确匹配白名单

对于 Nostr 额外说明：无论 dm_allowed_pubkeys 如何设置，owner_pubkey 始终被允许。私钥在存储时通过 SecretStore 加密（带有 enc2: 前缀），仅在频道运行期间解密到内存中；频道停止时立即清零。

Nostr 频道设置

nullclaw 通过 NIP-17（加密包裹的私信）和 NIP-04（传统私信）原生支持 Nostr，使用 nak 实现。

前提条件： 安装 nak 并确保其位于 $PATH 中。

通过引导向导设置：

nullclaw onboard --interactive   # 第 7 步配置 Nostr

该向导将：

1. 为你的机器人生成新密钥对，或导入已有密钥并使用 ChaCha20-Poly1305 加密
2. 要求输入你的（所有者）公钥（npub 或十六进制格式）——始终可通过 DM 策略
3. 配置中继（relays）和 DM 中继（kind:10050 收件箱）
4. 显示机器人的公钥

或者在配置文件中手动配置。

工作原理： 启动时，nullclaw 会广播其 DM 收件箱中继（kind:10050），然后监听传入的 NIP-17 gift wraps 和 NIP-04 加密私信。出站消息将镜像发送方所用协议。多中继谣言去重机制可防止同一消息通过多个中继送达时产生重复响应。

配置

配置文件路径：~/.nullclaw/config.json（由 onboard 命令创建）

兼容 OpenClaw： nullclaw 使用与 OpenClaw 相同的配置结构（snake_case 风格）。模型提供者位于 models.providers 下，默认模型位于 agents.defaults.model.primary，频道使用 accounts 包装器。 不支持顶层的 default_provider / default_model 键。

Vertex AI 注意事项： models.providers.vertex.api_key 支持以下两种形式：

1. Bearer Token（如 ya29...），或
2. 完整的 Google 服务账号 JSON 对象（格式与 Apps Script 中的 GEMINI_KEY 相同，包含 project_id、client_email、private_key）。

models.providers.vertex.base_url 可显式设置（例如 .../projects/<id>/locations/<loc>/publishers/google/models），若使用服务账号 JSON 则可省略（nullclaw 将从 project_id 推导出 URL，默认 VERTEX_LOCATION 为 global）。 使用服务账号模式时，需确保 $PATH 中有 openssl，用于 RS256 JWT 签名。

{
  "default_temperature": 0.7,

  "models": {
    "providers": {
      "openrouter": { "api_key": "sk-or-..." },
      "groq": { "api_key": "gsk_..." },
      "vertex": {
        "api_key": {
          "type": "service_account",
          "project_id": "your-project",
          "client_email": "svc@your-project.iam.gserviceaccount.com",
          "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
        },
        "base_url": "https://aiplatform.googleapis.com/v1/projects/your-project/locations/global/publishers/google/models"
      },
      "anthropic": { "api_key": "sk-ant-...", "base_url": "https://api.anthropic.com" }
    }
  },

  "agents": {
    "defaults": {
      "model": { "primary": "openrouter/anthropic/claude-sonnet-4" },
      "heartbeat": { "every": "30m" }
    },
    "list": [
      { "id": "researcher", "model": { "primary": "openrouter/anthropic/claude-opus-4" }, "system_prompt": "..." }
    ]
  },

  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123:ABC",
          "allow_from": ["user1"],
          "reply_in_private": true,
          "proxy": "socks5://..."
        }
      }
    },
    "discord": {
      "accounts": {
        "main": {
          "token": "disc-token",
          "guild_id": "12345",
          "allow_from": ["user1"],
          "allow_bots": false
        }
      }
    },
    "irc": {
      "accounts": {
        "main": {
          "host": "irc.libera.chat",
          "port": 6697,
          "nick": "nullclaw",
          "channel": "#nullclaw",
          "tls": true,
          "allow_from": ["user1"]
        },
        "meshrelay": {
          "host": "irc.meshrelay.xyz",
          "port": 6697,
          "nick": "nullclaw",
          "channels": ["#agents"],
          "tls": true,
          "nickserv_password": "YOUR_NICKSERV_PASSWORD",
          "allow_from": ["*"]
        }
      }
    },
    "slack": {
      "accounts": {
        "main": {
          "bot_token": "xoxb-...",
          "app_token": "xapp-...",
          "allow_from": ["user1"]
        }
      }
    },
    "nostr": {
      "private_key": "enc2:...",
      "owner_pubkey": "hex-pubkey-of-owner",
      "relays": ["wss://relay.damus.io", "wss://nos.lol", "wss://relay.nostr.band"],
      "dm_allowed_pubkeys": ["*"],
      "display_name": "NullClaw",
      "about": "AI assistant on Nostr",
      "nip05": "nullclaw@yourdomain.com",
      "lnurl": "lnurl1..."
    }
  },

  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "language": "ru",
        "models": [{ "provider": "groq", "model": "whisper-large-v3" }]
      }
    }
  },

  "mcp_servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    },
    "remote": {
      "transport": "http",
      "url": "https://mcp.example.com/rpc",
      "timeout_ms": 10000,
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  },

  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "embedding_provider": "openai",
    "vector_weight": 0.7,
    "keyword_weight": 0.3
  },

  "gateway": {
    "port": 3000,
    "require_pairing": true,
    "allow_public_bind": false
  },

  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 20
  },

  "runtime": {
    "kind": "native",
    "docker": {
      "image": "alpine:3.20",
      "network": "none",
      "memory_limit_mb": 512,
      "read_only_rootfs": true
    }
  },


  "tunnel": { "provider": "none" },
  "secrets": { "encrypt": true },
  "identity": { "format": "openclaw" },

  "security": {
    "sandbox": { "backend": "auto" },
    "resources": { "max_memory_mb": 512, "max_cpu_percent": 80 },
    "audit": { "enabled": true, "retention_days": 90 }
  }
}

Telegram 论坛主题：

• 话题（Topic）会话隔离是自动的。你不需要在 channels.telegram 下添加 topic_id 字段。
• 最简单的操作流程如下：
  1. 在 agents.list 下定义命名的代理（agent）配置文件
  2. 打开目标 Telegram 聊天或论坛话题（forum topic）
  3. 运行 /bind <agent>
• 要将特定的 Telegram 论坛话题绑定到特定代理，请在 bindings[].match.peer.id 中使用标准线程格式 "<chat_id>:thread:<topic_id>"。
• 要将整个 Telegram 群组作为所有其他话题的后备路由，请保留一个使用 "<chat_id>" 的普通群组绑定。
• /bind status 显示当前生效的路由和可用的代理 ID。
• /bind clear 仅移除当前账号/聊天/话题的精确绑定，并回退到更宽泛的路由。
• /bind 会为当前 Telegram 账号和对端（peer）持久化一个精确的 bindings[] 条目。
• /bind status 能区分精确的本地覆盖和继承自更宽泛规则的后备路由。
• 话题专属绑定通过路由优先级胜过群组后备；bindings[] 中的顺序无关紧要。
• /bind 命令在 Telegram 菜单中的可见性由 channels.telegram.accounts.<id>.binding_commands_enabled 控制。

示例：

{
  "bindings": [
    {
      "agent_id": "coder",
      "match": {
        "channel": "telegram",
        "account_id": "main",
        "peer": { "kind": "group", "id": "-1001234567890:thread:42" }
      }
    },
    {
      "agent_id": "orchestrator",
      "match": {
        "channel": "telegram",
        "account_id": "main",
        "peer": { "kind": "group", "id": "-1001234567890" }
      }
    }
  ]
}

在此配置中，话题 42 路由到 coder，而论坛其余部分则回退到 orchestrator。

命名的代理配置文件与绑定是分开配置的。绑定仅决定哪个命名代理处理给定的聊天/话题。

如果某个命名代理应从其自己的工作区（workspace）运行，请设置 agents.list[].workspace_path。
相对路径会相对于包含 config.json 的目录进行解析，工作区会在首次使用时自动搭建，且该代理会获得一个持久化内存命名空间 agent:<agent-id>。
设置 workspace_path 不会禁用 system_prompt：当两者都配置时，命名配置文件的提示词仍会应用，并且工作区引导文件会从该专用工作区加载。
这适用于 nullclaw agent --agent <id>、/subagents spawn --agent <id> 以及通过 bindings 解析的路由会话。

最小端到端示例：

{
  "agents": {
    "list": [
      {
        "id": "orchestrator",
        "provider": "openrouter",
        "model": "anthropic/claude-sonnet-4"
      },
      {
        "id": "coder",
        "provider": "ollama",
        "model": "qwen2.5-coder:14b",
        "system_prompt": "You are the coding agent for this topic."
      }
    ]
  },
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123456:ABCDEF",
          "allow_from": ["YOUR_TELEGRAM_USER_ID"],
          "binding_commands_enabled": true,
          "topic_commands_enabled": true,
          "topic_map_command_enabled": true,
          "commands_menu_mode": "scoped"
        }
      }
    }
  },
  "bindings": [
    {
      "agent_id": "orchestrator",
      "match": {
        "channel": "telegram",
        "account_id": "main",
        "peer": { "kind": "group", "id": "-1001234567890" }
      }
    }
  ]
}

操作流程：

• 在目标论坛话题内发送 /bind coder。
• nullclaw 会为该话题和 Telegram 账号向 ~/.nullclaw/config.json 写入一个新的精确 bindings[] 条目。
• 该话题中的下一条消息将使用新的路由代理配置文件。
• nullclaw 必须对 ~/.nullclaw/config.json 具有写权限，才能使 /bind 持久化更改。

关于 account_id：

• account_id 标识已配置的 Telegram 账号条目，而非话题或代理。
• 在常规的 channels.telegram.accounts 形式中，对象键即为账号 ID。例如，accounts.main 表示 account_id = "main"，accounts.backup 表示 account_id = "backup"。
• 在 bindings 中，match.account_id 将该绑定限制为仅匹配一个特定的 Telegram 账号。
• 如果省略 match.account_id，则该绑定可匹配该频道下的任意 Telegram 账号。
• 仅当你在同一 nullclaw 实例中运行多个 Telegram 机器人账号/令牌时，才需要使用不同的账号 ID。

对消息投递的影响：

• 传入的 Telegram 更新由接收它们的账号处理。
• 路由使用相同的 account_id，因此 match.account_id = "main" 仅匹配由 channels.telegram.accounts.main 接收的消息。
• 回复会通过处理该消息的同一 Telegram 账号/运行时发出。
• 将一个绑定设为 account_id = "main"，另一个设为 account_id = "sub"，并不会自动将一个聊天拆分给两个代理；它只是将每个绑定限定到不同的已配置 Telegram 账号。

完整网页搜索 + Shell 访问

当你希望完全控制网页搜索提供者，并启用无限制的 Shell 命令白名单行为时，请使用以下配置：

{
  "http_request": {
    "enabled": true,
    "search_base_url": "https://searx.example.com",
    "search_provider": "auto",
    "search_fallback_providers": ["jina", "duckduckgo"]
  },
  "autonomy": {
    "level": "full",
    "allowed_commands": ["*"],
    "allowed_paths": ["*"],
    "require_approval_for_medium_risk": false,
    "block_high_risk_commands": false
  }
}

• http_request.search_base_url 可接受实例根地址（如 https://host）或显式端点（如 https://host/search）；本地/私有 SearXNG 实例也可使用纯 HTTP，例如 http://localhost:8888 或 http://192.168.1.10:8888/search。
• 无效的 http_request.search_base_url 现在会在启动时导致配置验证失败（不再对格式错误的 URL 自动回退）。
• http_request.search_provider 支持：auto、searxng、duckduckgo（ddg）、brave、firecrawl、tavily、perplexity、exa、jina。
• http_request.search_fallback_providers 是可选的，当主提供者失败时按顺序尝试。
• 提供者环境变量：BRAVE_API_KEY、FIRECRAWL_API_KEY、TAVILY_API_KEY、PERPLEXITY_API_KEY、EXA_API_KEY、JINA_API_KEY（或在支持的情况下使用共享的 WEB_SEARCH_API_KEY）。DuckDuckGo 和 SearXNG 不需要 API 密钥。
• allowed_commands 条目支持 "cmd"、"cmd *" 和 "*" 格式。
  • "cmd" 和 "cmd *" 都允许该命令族通过白名单阶段。
  • "*" 允许任何命令通过白名单阶段。
• allowed_paths: ["*"] 允许访问工作区以外的路径，但系统保护路径除外。

Web UI / 浏览器中继（Browser Relay）

使用 channels.web 处理浏览器 UI 事件（WebChannel v1）：

{
  "channels": {
    "web": {
      "accounts": {
        "default": {
          "transport": "local",
          "listen": "127.0.0.1",
          "port": 32123,
          "path": "/ws",
          "auth_token": "replace-with-long-random-token",
          "message_auth_mode": "pairing",
          "allowed_origins": ["http://localhost:5173", "chrome-extension://your-extension-id"]
        }
      }
    }
  }
}

• 本地模式：保持 "listen": "127.0.0.1"。
• message_auth_mode 控制入站 user_message 的认证方式：
  • "pairing"（默认）：先发送 pairing_request，接收 pairing_result，并在每个 user_message 中包含 UI 的 access_token。
  • "token"（仅限本地传输）：在每个 user_message 负载中包含 auth_token（为兼容性也接受 access_token）。
• auth_token 用于加固 WebSocket 升级过程；当绑定非回环地址（non-loopback）时，该字段变为必需。
• 未经认证的 WebSocket 升级仅允许在回环地址（loopback）上进行。配对优先的本地用户体验适用于 127.0.0.1，但若绑定公网或局域网地址，则必须在首次连接 /ws 时通过 ?token=<auth_token> 或 Authorization: Bearer <auth_token> 进行认证。
• /ws 是 WebSocket 端点。/pair 属于 HTTP 网关 API，不属于 Web Channel 握手流程。
• 远程/无头主机：若绑定 "listen": "0.0.0.0"，建议在 TLS/反向代理后使用稳定配置的 token 并设置 message_auth_mode: "token"；或者保持回环绑定，并通过 SSH 隧道/代理暴露服务。
• UI/扩展应存放在独立仓库中，并通过此 WebSocket 端点连接。
• 编排场景：建议使用本地 token 模式，并从配置或环境变量（NULLCLAW_WEB_TOKEN、NULLCLAW_GATEWAY_TOKEN、OPENCLAW_GATEWAY_TOKEN）中读取稳定 token。
• 中继传输（出站代理套接字）通过以下方式配置：

{
  "channels": {
    "web": {
      "accounts": {
        "default": {
          "transport": "relay",
          "relay_url": "wss://relay.nullclaw.io/ws/agent",
          "relay_agent_id": "default",
          "relay_token": "replace-with-relay-token",
          "relay_token_ttl_secs": 2592000,
          "relay_pairing_code_ttl_secs": 300,
          "relay_ui_token_ttl_secs": 86400,
          "relay_e2e_required": false
        }
      }
    }
  }
}

• 中继 token 生命周期（专用）：relay_token（配置） → NULLCLAW_RELAY_TOKEN（环境变量） → 持久化凭证 web-relay-<account_id> → 生成 token。
• 中继 UI 握手：发送带一次性 pairing_code 的 pairing_request，接收包含 UI access_token JWT（以及可选的 set_cookie 字符串，供中继 HTTP 层使用）的 pairing_result。
• 中继 user_message 必须在 access_token（顶层或 payload.access_token）中包含有效的 UI JWT。
• 若启用端到端加密（E2E，即 relay_e2e_required=true），UI 与代理将在配对过程中交换 X25519 密钥，并在 payload.e2e 中发送加密负载。
• WebChannel 事件封装格式定义见 spec/webchannel_v1.json。

网关 API（Gateway API）

端点（Endpoint）	方法（Method）	认证（Auth）	描述（Description）
/health	GET	无	健康检查（始终公开）
/pair	POST	X-Pairing-Code 请求头	使用一次性配对码换取 Bearer Token
/webhook	POST	Authorization: Bearer <token>	发送消息：{"message": "your prompt"}
/.well-known/agent-card.json	GET	无	A2A Agent Card 发现（公开）
/a2a	POST	Authorization: Bearer <token>	A2A JSON-RPC 端点（标准方法及旧版斜杠别名）
/whatsapp	GET	查询参数	Meta Webhook 验证
/whatsapp	POST	无（Meta 签名）	WhatsApp 入站消息 Webhook

A2A（Agent-to-Agent 协议 v0.3.0）

NullClaw 实现了 Google 的 A2A 协议 v0.3.0，允许任何兼容 A2A 的代理或客户端通过 JSON-RPC 2.0 发现、认证并与你的实例交互。

在 ~/.nullclaw/config.json 中启用：

{
  "a2a": {
    "enabled": true,
    "name": "nullclaw",
    "description": "通用 AI 助手",
    "url": "https://example.com",
    "version": "1.0.0"
  }
}

端点：

端点（Endpoint）	认证（Auth）	描述（Description）
GET /.well-known/agent-card.json	无	Agent Card 发现（公开）
POST /a2a	Bearer Token	JSON-RPC 2.0 分发

支持的方法： message/send、message/stream、tasks/get、tasks/cancel、tasks/list、tasks/resubscribe。

快速测试：

# 1. 获取 Bearer Token
TOKEN=$(curl -s -X POST -H "X-Pairing-Code: 123456" http://localhost:3000/pair | jq -r .token)

# 2. 发现代理
curl http://localhost:3000/.well-known/agent-card.json

# 3. 发送消息
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"messageId":"msg-1","role":"user","parts":[{"kind":"text","text":"Hello"}]}}}' \
  http://localhost:3000/a2a

完整 A2A 参考（包括流式传输、任务生命周期和配置细节）请参阅 Gateway API 文档。

命令（Commands）

命令（Command）	描述（Description）
onboard --api-key sk-... --provider openrouter	使用 API Key 和提供商快速设置
onboard --interactive	完整交互式向导
onboard --channels-only	仅重新配置通道/允许列表
agent -m "..."	单条消息模式
agent	交互式聊天模式
gateway	启动长期运行的运行时（默认：127.0.0.1:3000）
service install|start|stop|restart|status|uninstall	管理后台服务
doctor	诊断系统健康状况
status	显示完整系统状态
channel list|start|status|add|remove	管理通道
cron list|add|add-agent|once|once-agent|remove|pause|resume|run|update|runs	管理定时任务
skills list|install|remove|info	管理技能包（skill packs）
history list|show	查看会话对话历史
memory stats|count|reindex|search|get|list|drain-outbox|forget	检查和维护记忆（memory）
hardware scan|flash|monitor	硬件设备管理
models list|info|benchmark|refresh	模型目录
workspace edit|reset-md	维护工作区 Markdown/引导文件
capabilities [--json]	显示运行时能力清单
auth login|status|logout	管理 OAuth 认证
migrate openclaw [--dry-run] [--source PATH]	从 OpenClaw 导入记忆并迁移配置
update [--check] [--yes]	检查并安装更新

开发（Development）

构建和测试固定使用 Zig 0.15.2。

zig build                          # 开发构建
zig build -Doptimize=ReleaseSmall  # 发布构建（678 KB）
zig build test --summary all       # 5,300+ 项测试

Channel Flow Coverage（通道流程覆盖）

通道的客户旅程地图（CJM）覆盖范围（入口解析/过滤、会话密钥路由、账户传播、总线交接）由以下测试验证：

• src/channel_manager.zig（运行时通道注册/启动语义 + 监听器模式接线）
• src/config.zig（兼容 OpenClaw 的 channels.*.accounts 解析、多账户选择/排序、别名）
• src/gateway.zig（从 webhook 负载中提取 Telegram/WhatsApp/LINE/Lark 的路由会话密钥）
• src/daemon.zig（Discord/QQ/OneBot/Mattermost/MaixCam 的网关循环入站路由解析）
• src/channels/discord.zig, src/channels/mattermost.zig, src/channels/qq.zig, src/channels/onebot.zig, src/channels/signal.zig, src/channels/line.zig, src/channels/whatsapp.zig（各通道的入站/出站契约）

项目统计

语言：        Zig 0.15.2
源文件数：    ~250
代码行数：    ~249,000
测试用例：    5,300+
二进制大小：  678 KB（ReleaseSmall）
峰值内存占用：~1 MB
启动时间：    <2 ms（Apple Silicon）
依赖项：      0（除 libc 和可选的 SQLite 外）

源码结构

src/
  main.zig              CLI 入口点 + 参数解析
  root.zig              模块层级结构（公共 API）
  config.zig            JSON 配置加载器 + 30 个子配置结构体
  agent.zig             Agent 循环、自动压缩、工具分发
  daemon.zig            带指数退避机制的守护进程监督器
  gateway.zig           HTTP 网关（限流、幂等性、配对）
  channels/             19 种通道实现（telegram, signal, discord, slack, nostr, matrix, whatsapp, line, lark, onebot, mattermost, qq, ...）
  providers/            50+ AI 提供商集成
  memory/               SQLite 后端、嵌入（embeddings）、向量搜索、数据清理、快照
  tools/                35+ 工具实现
  security/             密钥管理（ChaCha20）、沙箱后端（landlock, firejail, ...）
  cron.zig              带 JSON 持久化的 Cron 调度器
  health.zig            组件健康状态注册表
  tunnel.zig            隧道虚函数表（cloudflare, ngrok, tailscale, 自定义）
  peripherals.zig       硬件外设虚函数表（串口、Arduino、树莓派、Nucleo）
  runtime.zig           运行时虚函数表（原生、Docker、WASM）
  skillforge.zig        技能发现（GitHub）、评估、集成
  ...

版本控制

nullclaw 使用 CalVer（YYYY.M.D）进行版本发布 —— 例如 v2026.2.20。

• 标签格式： vYYYY.M.D（每天最多一次发布；如需补丁则使用 vYYYY.M.D.N 后缀）
• 发布版二进制文件的内嵌版本来自 git 标签（v... → nullclaw --version）
• 非发布构建默认为 dev，除非你通过 zig build -Dversion=... 覆盖
• 尚无稳定性保证 —— 项目处于 1.0 之前阶段，配置和 CLI 可能在版本间变动
• nullclaw --version 打印当前版本

贡献指南

详见 CONTRIBUTING.md，了解开发环境搭建、工作流程、验证命令和 PR 检查清单。

实现一个虚函数表（vtable）接口并提交 PR：

• 新增 Provider → src/providers/
• 新增 Channel → src/channels/
• 新增 Tool → src/tools/
• 新增 Memory 后端 → src/memory/
• 新增 Tunnel → src/tunnel.zig
• 新增 Sandbox 后端 → src/security/
• 新增 Peripheral → src/peripherals.zig
• 新增 Skill → ~/.nullclaw/workspace/skills/<name>/

中文文档

• 中文文档总览
• 安装指南
• 配置指南
• 使用与运维
• 架构总览
• 安全机制
• Gateway API（中文）
• 命令参考
• 开发指南

英文文档

• English docs overview
• Installation
• Configuration
• Usage and operations
• Architecture
• Security
• Gateway API
• Commands
• Development

免责声明

nullclaw 是一个纯粹的开源软件项目。它不包含任何代币、加密货币、区块链组件或金融工具。本项目与任何代币或金融产品均无关联。

许可证

MIT — 详见 LICENSE

---

nullclaw — 零开销。零妥协。随处部署。任意替换。

Star 历史

nullclaw 中文快速上手指南

环境准备

• 系统要求：支持 ARM、x86、RISC-V 架构，可在任意带 CPU 的设备上运行（包括 $5 开发板）
• 内存要求：最低约 1 MB RAM
• 依赖项：
  • 若从源码构建，需 Zig 0.15.2（必须精确匹配，其他版本暂不支持）

    zig version  # 应输出 0.15.2
    

  • 若使用预编译二进制，则无任何运行时依赖，仅需 libc

💡 国内用户建议使用 Homebrew 安装（已自动处理依赖），或从 GitHub Release 下载静态二进制。

安装步骤

方式一：推荐安装（Homebrew）

brew install nullclaw
nullclaw --help

方式二：从源码构建（需 Zig 0.15.2）

git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig build -Doptimize=ReleaseSmall
zig build test --summary all

将二进制加入 PATH：

macOS / Linux (zsh/bash)：

zig build -Doptimize=ReleaseSmall -p "$HOME/.local"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc  # 或 ~/.bashrc
source ~/.zshrc

Windows (PowerShell)：

zig build -Doptimize=ReleaseSmall -p "$HOME\.local"

$bin = "$HOME\.local\bin"
$user_path = [Environment]::GetEnvironmentVariable("Path", "User")
if (-not ($user_path -split ";" | Where-Object { $_ -eq $bin })) {
  [Environment]::SetEnvironmentVariable("Path", "$user_path;$bin", "User")
}
$env:Path = "$env:Path;$bin"

验证安装：

nullclaw --help

基本使用

1. 快速配置（以 OpenRouter 为例）

nullclaw onboard --api-key sk-... --provider openrouter

或使用交互式向导：

nullclaw onboard --interactive

2. 发送一条消息

nullclaw agent -m "Hello, nullclaw!"

3. 进入交互聊天模式

nullclaw agent

4. 启动网关服务（默认端口 3000）

nullclaw gateway
# 或指定端口
nullclaw gateway --port 8080

5. 查看状态与诊断

nullclaw status
nullclaw doctor

更多命令请参考 docs/zh/commands.md 或运行 nullclaw help。