zeroclaw

ZeroClaw — 完整参考技能

ZeroClaw 的全面操作知识：这套基于 Rust 构建的 AI 助手基础设施，快速、小巧且完全自主。 来源：https://github.com/zeroclaw-labs/zeroclaw | 版本：0.1.1 | 最后更新：2026-02-21

---

什么是 ZeroClaw

• **语言：**100% Rust，单个二进制文件（release 版本约 3.4-8.8MB）
• **内存：**运行时 RAM 占用 <5MB
• **启动：**冷启动 <10ms
• **平台：**ARM、x86、RISC-V — 可在 $10 的硬件上运行
• **架构：**由 Trait 驱动，所有组件均可替换（提供商、频道、工具、内存、隧道、安全）
• 配置：~/.zeroclaw/config.toml（TOML 格式）
• 工作区：~/.zeroclaw/workspace/（SOUL.md、AGENTS.md、IDENTITY.md、USER.md、MEMORY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md）
• **身份：**ZeroClaw 会自我介绍为 ZeroClaw，绝不会称自己为 ChatGPT/Claude 等。

---

安装

# Option A: Clone + build
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw && ./bootstrap.sh

# Option B: Remote one-liner
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash

# Fresh machine (install Rust + system deps)
./bootstrap.sh --install-system-deps --install-rust

# Quick onboard after install
zeroclaw onboard --api-key "your-api-key" --provider openrouter

更新 ZeroClaw

# Fastest: prebuilt binary (no compile)
git clone https://github.com/zeroclaw-labs/zeroclaw.git /tmp/zeroclaw-update
cd /tmp/zeroclaw-update && bash scripts/bootstrap.sh --prefer-prebuilt
rm -rf /tmp/zeroclaw-update

# With browser-native feature (requires compile)
git clone https://github.com/zeroclaw-labs/zeroclaw.git /tmp/zeroclaw-update
cd /tmp/zeroclaw-update && cargo install --path . --force --locked --features browser-native
rm -rf /tmp/zeroclaw-update

# Verify
zeroclaw --version

注意：没有内置的 zeroclaw update 命令。从全新克隆的仓库重新运行 bootstrap.sh --prefer-prebuilt 是最快的方式。预编译二进制文件不包含 browser-native — 如果需要 rust_native 浏览器后端，必须使用 --features browser-native 从源代码构建。

---

CLI 参考（所有命令）

顶层命令

命令	用途
zeroclaw onboard	初始化工作区/配置（快速设置）
zeroclaw onboard --interactive	完整的交互式向导
zeroclaw onboard --channels-only	仅重新配置频道
zeroclaw agent	交互式 AI 聊天
zeroclaw agent -m "Hello"	单条消息模式
zeroclaw agent --provider <ID> --model <MODEL>	覆盖提供商/模型
zeroclaw agent --peripheral <board:path>	连接硬件外围设备
zeroclaw gateway [--host H] [--port P]	启动 webhook/websocket 网关
zeroclaw daemon [--host H] [--port P]	完整的自主运行时（网关 + 频道 + 心跳 + 调度器）
zeroclaw status	显示完整系统状态
zeroclaw doctor	运行诊断
zeroclaw providers	列出支持的 30 个 AI 提供商

服务管理（launchd/systemd）

zeroclaw service install      # Install for auto-start
zeroclaw service start        # Start service
zeroclaw service stop         # Stop service
zeroclaw service status       # Check status
zeroclaw service uninstall    # Remove service

频道管理

zeroclaw channel list                      # List all channels + status
zeroclaw channel start                     # Start all configured channels
zeroclaw channel doctor                    # Health check channels
zeroclaw channel add <type> <json>         # Add channel (type + JSON config)
zeroclaw channel remove <name>             # Remove channel
zeroclaw channel bind-telegram <IDENTITY>  # Add Telegram user to allowlist

注意：channel add/remove 目前还不能完整修改配置 — 建议直接编辑 ~/.zeroclaw/config.toml 或使用 zeroclaw onboard。

Cron / 调度

zeroclaw cron list                              # List tasks
zeroclaw cron add "<cron-expr>" "<command>"      # Add recurring task
zeroclaw cron add --tz America/New_York "..."    # With timezone
zeroclaw cron add-at <rfc3339> "<command>"       # One-shot at timestamp
zeroclaw cron add-every <ms> "<command>"         # Fixed interval
zeroclaw cron once <delay> "<command>"           # One-shot delayed (e.g. "30m", "2h")
zeroclaw cron remove <id>
zeroclaw cron pause <id>
zeroclaw cron resume <id>

模型和提供商

zeroclaw providers                          # List all 30 providers
zeroclaw models refresh                     # Refresh model catalogs
zeroclaw models refresh --provider <ID>     # Refresh specific provider
zeroclaw models refresh --force             # Force refresh

技能

zeroclaw skills list                        # List installed skills
zeroclaw skills install <source>            # Install from GitHub URL or local path
zeroclaw skills remove <name>               # Remove skill

集成

zeroclaw integrations info <name>           # Show integration details
# Examples: Telegram, Discord, Slack, iMessage, Matrix, Signal, WhatsApp, Email, DingTalk, Ollama

身份验证

zeroclaw auth login --provider <ID>         # OAuth login (e.g. openai-codex)
zeroclaw auth login --provider <ID> --device-code  # Device code flow
zeroclaw auth paste-token                   # Paste auth token (Anthropic)
zeroclaw auth setup-token                   # Alias for paste-token
zeroclaw auth refresh                       # Refresh OAuth token
zeroclaw auth logout                        # Remove auth profile
zeroclaw auth use --provider <ID>           # Set active profile
zeroclaw auth list                          # List profiles
zeroclaw auth status                        # Show token expiry info

硬件和外围设备

zeroclaw hardware discover                  # Enumerate USB devices (VID/PID)
zeroclaw hardware introspect <path>         # Introspect device
zeroclaw hardware info [--chip <name>]      # Chip info via probe-rs

zeroclaw peripheral list                    # List configured boards
zeroclaw peripheral add <board> <path>      # Add board (e.g. nucleo-f401re /dev/ttyACM0)
zeroclaw peripheral flash [--port <port>]   # Flash Arduino firmware
zeroclaw peripheral setup-uno-q             # Setup Arduino Uno Q Bridge
zeroclaw peripheral flash-nucleo            # Flash Nucleo-F401RE firmware

迁移

zeroclaw migrate openclaw [--source <path>] [--dry-run]  # Import from OpenClaw

---

支持的提供商（共 30 个）

ID	描述
openrouter	OpenRouter（默认）
anthropic	Anthropic
openai	OpenAI
openai-codex	OpenAI Codex（OAuth）
ollama	Ollama [本地]
gemini	Google Gemini
venice	Venice
vercel	Vercel AI Gateway
cloudflare	Cloudflare AI
moonshot	Moonshot / Kimi
opencode	OpenCode Zen
zai	Z.AI
glm	GLM（智谱）
minimax	MiniMax
bedrock	Amazon Bedrock
qianfan	千帆（百度）
qwen	Qwen（DashScope）
groq	Groq
mistral	Mistral
xai	xAI（Grok）
deepseek	DeepSeek
together	Together AI
fireworks	Fireworks AI
perplexity	Perplexity
cohere	Cohere
copilot	GitHub Copilot
lmstudio	LM Studio [本地]
nvidia	NVIDIA NIM
ovhcloud	OVHcloud AI Endpoints
custom:<URL>	任意兼容 OpenAI 的端点
anthropic-custom:<URL>	任意兼容 Anthropic 的端点

自定义提供商设置

# OpenAI-compatible
default_provider = "custom:https://your-api.com"
api_key = "your-api-key"
default_model = "your-model"

# Anthropic-compatible
default_provider = "anthropic-custom:https://your-api.com"
api_key = "your-api-key"
default_model = "your-model"

---

频道（支持 14 个）

Channel Matrix

渠道	配置部分	访问控制字段	设置
CLI	始终启用	不适用	内置
Telegram	[channels_config.telegram]	allowed_users	zeroclaw onboard
Discord	[channels_config.discord]	allowed_users	zeroclaw onboard
Slack	[channels_config.slack]	allowed_users	zeroclaw onboard
Mattermost	[channels_config.mattermost]	allowed_users	手动配置
Webhook	[channels_config.webhook]	secret（可选）	手动配置 / onboard
iMessage	[channels_config.imessage]	allowed_contacts	仅限 macOS
Matrix	[channels_config.matrix]	allowed_users	zeroclaw onboard
Signal	[channels_config.signal]	allowed_from	手动配置
WhatsApp	[channels_config.whatsapp]	allowed_numbers	zeroclaw onboard
Email	[channels_config.email]	allowed_senders	手动配置
IRC	[channels_config.irc]	allowed_users	zeroclaw onboard
Lark	[channels_config.lark]	allowed_users	手动配置
DingTalk	[channels_config.dingtalk]	allowed_users	zeroclaw onboard

默认拒绝的允许列表规则

• []（空）= 拒绝所有
• ["*"] = 允许所有（不建议用于生产环境）
• ["123456789", "username"] = 仅精确匹配

Telegram 设置

[channels_config.telegram]
bot_token = "your-bot-token"
allowed_users = []

# 1. Get bot token from @BotFather on Telegram
# 2. Add config above to ~/.zeroclaw/config.toml
# 3. Bind your user:
zeroclaw channel bind-telegram <USER_ID_OR_USERNAME>
# 4. Start:
zeroclaw daemon

**重要：**Telegram 使用长轮询，无需入站端口或公网 IP。每个 bot token 只允许运行一个轮询器（不要运行多个守护进程）。

Discord 设置

1. 前往 https://discord.com/developers/applications
2. 创建应用，启用 Bot，复制 token
3. 启用 MESSAGE CONTENT intent
4. 运行 zeroclaw onboard

Slack 设置

1. 前往 https://api.slack.com/apps
2. 创建应用，添加 Bot Token Scopes，然后安装
3. 运行 zeroclaw onboard

Mattermost 设置

[channels_config.mattermost]
url = "https://mm.your-domain.com"
bot_token = "your-bot-access-token"
channel_id = "your-channel-id"
allowed_users = ["user-id-1"]
thread_replies = true
mention_only = true

WhatsApp 设置

[channels_config.whatsapp]
access_token = "your-access-token"
phone_number_id = "your-phone-number-id"
verify_token = "your-verify-token"
allowed_numbers = ["+1234567890"]

WhatsApp 需要一个公网 URL（webhook），请使用隧道（Tailscale/ngrok/Cloudflare）。

Signal 设置

[channels_config.signal]
http_url = "http://127.0.0.1:8686"
account = "+1234567890"
allowed_from = ["+1987654321"]
ignore_attachments = true
ignore_stories = true

Lark 设置

[channels_config.lark]
app_id = "your-app-id"
app_secret = "your-app-secret"
allowed_users = ["your-user-id"]
receive_mode = "websocket"   # or "webhook"

聊天内命令（Telegram/Discord）

在渠道服务运行时，用户可以执行：

• /models — 显示可用的提供商
• /models <provider> — 切换提供商（按发送者区分）
• /model — 显示当前模型
• /model <model-id> — 切换模型（按发送者区分）

切换会清除该发送者的对话历史，避免不同模型之间的数据污染。

---

配置参考（~/.zeroclaw/config.toml）

核心

键	默认值	说明
default_provider	openrouter	提供商 ID 或别名
default_model	anthropic/claude-sonnet-4.5	通过提供商路由的模型
default_temperature	0.7	0.0-2.0

网关

键	默认值	用途
gateway.host	127.0.0.1	绑定地址
gateway.port	3000	监听端口
gateway.require_pairing	true	要求配对以进行身份验证
gateway.allow_public_bind	false	阻止意外暴露到公网

记忆

键	默认值	用途
memory.backend	sqlite	sqlite、lucid、markdown、none
memory.auto_save	true	自动持久化
memory.embedding_provider	none	none、openai 或自定义
memory.vector_weight	0.7	混合搜索的向量权重
memory.keyword_weight	0.3	混合搜索的关键词权重

自主性 / 安全

键	默认值	用途
autonomy.level	supervised	readonly、supervised、full
autonomy.workspace_only	true	限制在工作区内
autonomy.allowed_commands	[git, npm, cargo, ls, cat, grep, find, echo, pwd, wc, head, tail]	允许的命令列表
autonomy.max_actions_per_hour	20	频率限制
autonomy.max_cost_per_day_cents	500	费用上限

Agent

键	默认值
agent.max_tool_iterations	10
agent.max_history_messages	50
agent.parallel_tools	false

浏览器控制

键	默认值	用途
browser.enabled	false	启用浏览器工具
browser.allowed_domains	[]	域名允许列表（["*"] 表示全部域名）
browser.session_name	(none)	可选的会话标识符，用于持久化
browser.backend	agent_browser	agent_browser、rust_native、computer_use、auto
browser.native_headless	true	rust_native 后端的无头模式
browser.native_webdriver_url	http://127.0.0.1:9515	rust_native 的 WebDriver 端点
browser.native_chrome_path	(auto)	可选的显式 Chrome 二进制文件路径
browser.computer_use.endpoint	http://127.0.0.1:8787/v1/actions	Computer-use 侧车端点
browser.computer_use.api_key	(none)	侧车身份验证的可选 bearer 令牌（已加密）
browser.computer_use.timeout_ms	15000	每项操作的超时时间
browser.computer_use.allow_remote_endpoint	false	仅允许本地主机侧车
browser.computer_use.window_allowlist	[]	限制可作为目标的操作系统窗口
browser.computer_use.max_coordinate_x	(none)	坐标验证的可选 X 边界
browser.computer_use.max_coordinate_y	(none)	坐标验证的可选 Y 边界

HTTP 请求

键	默认值	用途
http_request.enabled	false	启用 HTTP 请求工具
http_request.allowed_domains	[]	域名允许列表（["*"] 表示全部域名）
http_request.max_response_size	0	最大响应字节数（0 = 不限）
http_request.timeout_secs	0	请求超时时间（0 = 不限）

其他重要配置段

• [runtime] — 原生或 Docker 沙箱
• [reliability] — 提供商重试、退避、回退
• [scheduler] — 任务调度（最多 64 个任务，4 个并发任务）
• [heartbeat] — 定期检查（默认禁用）
• [cron] — Cron 调度
• [tunnel] — 提供商：none、tailscale、ngrok、cloudflare
• [composio] — Composio 集成（250 多种应用集成）
• [secrets] — 加密密钥
• [web_search] — 默认使用 DuckDuckGo
• [proxy] — HTTP 代理支持
• [cost] — 每日／每月限额、按模型计价
• [peripherals] — 硬件开发板

---

浏览器控制设置

浏览器后端

后端	工作机制	运行时要求	构建要求
agent_browser（默认）	以子进程方式调用 Vercel 的 agent-browser CLI	$PATH 中有 agent-browser	无（默认构建／预编译二进制文件）
rust_native	通过 fantoccini 在进程内使用 WebDriver	ChromeDriver 正在运行	cargo install --features browser-native（必须从源代码构建）
computer_use	向侧车发送 HTTP POST，以操作操作系统级鼠标／键盘／屏幕	Computer-use 侧车服务	无
auto	自动检测最合适的可用后端	取决于已安装的组件	无

auto 检测优先级： rust_native（已编译且 WebDriver 可访问）-> agent_browser（已安装 CLI）-> computer_use（侧车可访问）。如果没有可用后端，则提供有用的错误信息并回退。

预编译二进制文件说明： bootstrap.sh --prefer-prebuilt 提供的预编译二进制文件不包含 browser-native。如果你使用预编译二进制文件设置 backend = "rust_native"，Agent 会提示未启用此功能。你必须从源代码构建：cargo install --path . --force --locked --features browser-native。

浏览器操作（共 17 项）

标准操作（适用于所有后端）：

操作	用途	说明
open	跳转到 URL	所有后端
snapshot	获取包含 @ref 元素句柄的无障碍树	仅限 agent_browser — 在 rust_native 上返回 null
click	通过 CSS 选择器或 @ref 点击元素	@ref 仅适用于 agent_browser
fill	清空字段并填入值
type	在聚焦的元素中输入文本
get_text	提取元素文本
get_title	获取页面标题
get_url	获取当前 URL
screenshot	截取页面	选项：path、full_page
wait	等待元素、时间或文本
press	按下键盘按键
hover	将鼠标悬停在元素上
scroll	滚动页面	选项：direction、pixels
is_visible	检查元素是否可见	严格模式 — 选择器必须恰好匹配一个元素
close	关闭浏览器
find	通过语义定位器查找	选项：role、text、label、placeholder、testid

仅限计算机操作的操作（额外 6 项 — OS 级别，非 DOM）：

操作	用途
mouse_move	将鼠标移动到指定坐标
mouse_click	点击指定坐标
mouse_drag	从一个点拖动到另一个点
key_type	通过 sidecar 输入按键
key_press	按下单个按键
screen_capture	截取 OS 屏幕

在不支持计算机操作的后端上使用计算机操作，会返回特定于后端的错误。

后端对比（已测试）

能力	agent_browser	rust_native	computer_use
open / close	是	是	是
get_title / get_text / get_url	是	是	是
click / fill / type	是（CSS + @ref）	是（仅 CSS）	是（坐标）
hover / scroll / press	是	是	是
screenshot	是	是	是（screen_capture）
is_visible	是（严格模式）	是	不适用
snapshot（无障碍树）	是（完整 @ref 树）	否（返回 null）	不适用
find（语义定位器）	部分支持	否	不适用
元素 @refs	是	否	不适用
会话持久化	是（配置文件路径）	否	不适用
有头模式	config + executablePath	native_headless = false	不适用（OS 级别）
子进程开销	有（每次操作都会调用 shell）	无（进程内）	有（每次操作均通过 HTTP）
OS 级鼠标/键盘	否	否	是

**AI 驱动自动化的建议：**使用 agent_browser。带有 @ref 句柄的无障碍树快照至关重要——它能让 Agent“看到”页面结构，并定位特定元素（例如 @e12），而不是猜测 CSS 选择器。仅在无 Node 部署或已知选择器的简单抓取场景下使用 rust_native。需要超出浏览器 DOM 范围的 OS 级控制时，使用 computer_use。

推荐配置：使用带可见 Chrome 窗口的 agent_browser

这样会在桌面上弹出一个可见的 Chrome 窗口（类似 OpenClaw）——你可以观察 AI 浏览网页、登录网站，且配置文件会在各会话间保留 Cookie 和会话信息。

步骤 1：安装 agent-browser

npm install -g agent-browser
# Verify:
agent-browser --version

步骤 2：将 agent-browser 配置为有头模式

创建 ~/.agent-browser/config.json：

{
  "headed": true,
  "profile": "~/.agent-browser/profile",
  "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}

重要：有头（可见）模式必须设置 executablePath。 默认情况下，agent-browser 使用 Playwright 附带的 Chromium（~/Library/Caches/ms-playwright/chromium-*/），它会忽略 headed 标志，始终以无头模式运行。将路径指向实际安装的 Google Chrome 即可解决此问题。

常见的 Chrome 路径：

• macOS： /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
• Linux： /usr/bin/google-chrome 或 /usr/bin/chromium
• Windows： C:\Program Files\Google\Chrome\Application\chrome.exe

profile 路径可让 Cookie 和登录信息在各会话间持久保存。

步骤 3：配置 ZeroClaw

在 ~/.zeroclaw/config.toml 中：

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"

步骤 4：使用 headed 环境变量启动守护进程（双重保险）

AGENT_BROWSER_HEADED=true zeroclaw daemon

如果是安装为服务，则先在 shell 配置文件中导出该环境变量。

agent-browser CLI 参考

agent-browser open <url>              # Navigate to URL
agent-browser click <selector>        # Click element
agent-browser type <sel> <text>       # Type into element
agent-browser fill <sel> <text>       # Clear and fill
agent-browser screenshot [path]       # Take screenshot
agent-browser snapshot                # Accessibility tree with @refs (for AI)
agent-browser eval <js>               # Run JavaScript
agent-browser close                   # Close browser
agent-browser --headed open <url>     # Force visible window
agent-browser --session <name> ...    # Isolated session
agent-browser --profile <path> ...    # Persistent browser profile

agent-browser 环境变量

变量	用途
AGENT_BROWSER_HEADED	显示浏览器窗口（非无头模式）
AGENT_BROWSER_SESSION	会话名称
AGENT_BROWSER_SESSION_NAME	自动保存/恢复状态持久化数据
AGENT_BROWSER_PROFILE	持久化浏览器配置文件路径
AGENT_BROWSER_EXECUTABLE_PATH	自定义浏览器二进制文件
AGENT_BROWSER_PROXY	代理服务 URL
AGENT_BROWSER_CONFIG	配置文件路径
AGENT_BROWSER_AUTO_CONNECT	自动发现正在运行的 Chrome
AGENT_BROWSER_STREAM_PORT	WebSocket 流端口

浏览器安全模型

• 所有 URL 都会通过 validate_url()，该函数会强制执行 allowed_domains
• file:// 协议会被阻止（防止本地文件外泄）
• 私有/保留 IP 范围会被拒绝
• 对于 computer_use：会验证坐标；除非 allow_remote_endpoint = true，否则端点必须是 localhost

浏览器故障排除

问题	解决方案
浏览器打开了但不可见（无头模式）	在 ~/.agent-browser/config.json 中将 executablePath 设置为真正的 Chrome，而非 Playwright Chromium
“域名不在允许列表中”	在 ZeroClaw 配置中设置 browser.allowed_domains = ["*"] 并重启守护进程
找不到 agent-browser	npm install -g agent-browser
浏览器立即关闭	检查 agent-browser --version；确保已安装 Chrome
会话过期	执行 agent-browser close 后重试
rust_native“未启用功能”	预编译二进制文件缺少 browser-native — 重新构建：cargo install --path . --force --locked --features browser-native
rust_native 快照返回 null	这是预期行为 — rust_native 不支持无障碍树快照。切换到 agent_browser 以支持快照/@ref
ChromeDriver 版本不匹配	ChromeDriver 版本必须与 Chrome 版本匹配。在 macOS 上：执行 brew install --cask chromedriver，然后执行 xattr -d com.apple.quarantine /opt/homebrew/bin/chromedriver
agent_browser 上的 computer_use 操作失败	操作系统级操作（mouse_move、mouse_click 等）仅适用于 computer_use 后端
is_visible 严格模式错误	选择器匹配到了多个元素。请使用更具体的 CSS 选择器，或使用快照中的 @ref

---

全自主设置（最大功率模式）

解锁所有能力并移除所有限制：

配置（~/.zeroclaw/config.toml）

[autonomy]
level = "full"
workspace_only = false
allowed_commands = ["*"]
forbidden_paths = []
max_actions_per_hour = 200
max_cost_per_day_cents = 5000
require_approval_for_medium_risk = false
block_high_risk_commands = false
auto_approve = [
    "shell",
    "file_read",
    "file_write",
    "memory_store",
    "memory_recall",
    "memory_forget",
]
always_ask = []

[agent]
compact_context = false
max_tool_iterations = 50
max_history_messages = 200
parallel_tools = true
tool_dispatcher = "auto"

[scheduler]
enabled = true
max_tasks = 128
max_concurrent = 8

[heartbeat]
enabled = true
interval_minutes = 30

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"

[http_request]
enabled = true
allowed_domains = ["*"]
max_response_size = 10485760
timeout_secs = 30

[composio]
enabled = true
entity_id = "default"

[web_search]
enabled = true
provider = "duckduckgo"
max_results = 5
timeout_secs = 15

全功率模式的外部依赖

# Browser control (visible Chrome window)
npm install -g agent-browser

# agent-browser config (~/.agent-browser/config.json)
{
  "headed": true,
  "profile": "~/.agent-browser/profile",
  "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}

# Start daemon with headed browser
AGENT_BROWSER_HEADED=true zeroclaw daemon

各项设置的解锁功能

设置	功能
autonomy.level = "full"	执行任何操作都无需审批
autonomy.workspace_only = false	可访问系统上的任何文件
autonomy.allowed_commands = ["*"]	可运行任何 shell 命令
autonomy.forbidden_paths = []	不限制路径
block_high_risk_commands = false	允许执行破坏性命令
auto_approve = [all tools]	所有工具运行时均无需确认
agent.max_tool_iterations = 50	每项任务的工具调用次数增加 5 倍
agent.parallel_tools = true	同时运行多个工具
browser.enabled = true	启用浏览器自动化
browser.allowed_domains = ["*"]	可浏览任何网站
http_request.enabled = true	可向任何域名发起 HTTP 请求
composio.enabled = true	提供 250 多种应用集成（Gmail、Calendar、GitHub 等）
heartbeat.enabled = true	每 30 分钟主动执行后台检查
scheduler.max_concurrent = 8	并行运行 8 个计划任务

安全警告

完全自主模式会移除所有防护措施。Agent 可以：

• 在你的系统上运行任何命令
• 读取／写入任何文件
• 使用你的 Chrome 配置文件（Cookie、登录信息）浏览任何网站
• 向任何域名发送 HTTP 请求
• 无需批准即可执行 shell 命令

仅在可信的个人设备上使用此模式。对于共享或生产环境，请保持 supervised 模式并设置明确的允许列表。

---

运维手册

运行模式

模式	命令	适用场景
前台运行	zeroclaw daemon	本地调试
仅网关	zeroclaw gateway	Webhook 测试
用户服务	zeroclaw service install && start	持续运行

运维人员检查清单

zeroclaw status          # Check config
zeroclaw doctor          # Run diagnostics
zeroclaw channel doctor  # Check channel health
zeroclaw daemon          # Start runtime

安全的配置更改流程

1. 备份 ~/.zeroclaw/config.toml
2. 应用一项逻辑更改
3. 运行 zeroclaw doctor
4. 重启 daemon／服务
5. 使用 status + channel doctor 进行验证

日志

• macOS／Windows：~/.zeroclaw/logs/daemon.stdout.log、daemon.stderr.log
• Linux systemd：journalctl --user -u zeroclaw.service -f

---

网络部署

Telegram／Discord／Slack（无需端口）

这些平台使用长轮询，仅需出站连接。在 NAT 后方、RPi 和家庭实验室中均可运行。

zeroclaw daemon --host 127.0.0.1 --port 3000

Webhook 渠道（WhatsApp 等）

需要一个公共 URL。可选方案：

• [tunnel] provider = "tailscale" — Tailscale Funnel
• [tunnel] provider = "ngrok" — ngrok 隧道
• Cloudflare Tunnel

局域网访问

[gateway]
host = "0.0.0.0"
allow_public_bind = true

---

硬件外设

支持的开发板

开发板	传输方式	路径
nucleo-f401re	串口	/dev/ttyACM0
arduino-uno	串口	/dev/ttyACM0、/dev/cu.usbmodem*
arduino-uno-q	桥接	(IP)
rpi-gpio	原生	原生
esp32	串口	/dev/ttyUSB0

添加开发板

zeroclaw peripheral add nucleo-f401re /dev/ttyACM0

也可以在配置中设置：

[peripherals]
enabled = true
datasheet_dir = "docs/datasheets"

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200

两种运行模式

1. 边缘原生： ZeroClaw 直接运行在设备（ESP32、RPi）上，使用本地 GPIO/I2C/SPI
2. 主机中介： ZeroClaw 运行在主机（Mac/Linux）上，通过 USB/J-Link 连接设备进行开发／调试

---

故障排除速查

问题	解决方案
找不到 cargo	./bootstrap.sh --install-rust
找不到 zeroclaw	export PATH="$HOME/.cargo/bin:$PATH"
无法访问网关	检查配置中的 gateway.host／gateway.port
Telegram 报错 terminated by other getUpdates	停止多余的 daemon／渠道进程——每个令牌只能有一个轮询进程
渠道运行异常	运行 zeroclaw channel doctor，然后验证凭据和允许列表
服务未运行	zeroclaw service stop && zeroclaw service start
配置文件可被所有用户读取的警告	chmod 600 ~/.zeroclaw/config.toml
浏览器以无头模式（不可见）打开	在 ~/.agent-browser/config.json 中将 executablePath 设置为真实的 Chrome——Playwright 捆绑的 Chromium 会忽略 headed 标志
浏览器提示“域名不在允许列表中”	在配置中设置 browser.allowed_domains = ["*"]，然后重启 daemon
Agent 声称存在实际并不存在的域名限制	大模型产生了幻觉——告诉它“allowed_domains 是通配符，现在浏览该网站”
找不到 agent-browser	npm install -g agent-browser
二进制文件不包含 rust_native 浏览器功能	预编译二进制文件不包含此功能——从源代码使用 --features browser-native 构建
没有内置更新命令	克隆仓库并运行 bash scripts/bootstrap.sh --prefer-prebuilt，即可快速更新

诊断命令

zeroclaw --version
zeroclaw status
zeroclaw doctor
zeroclaw channel doctor
zeroclaw channel list

---

工作区文件

文件	用途
SOUL.md	Agent 个性、身份、沟通风格
AGENTS.md	会话协议、记忆系统、安全规则
IDENTITY.md	名称、生物类型、氛围、表情符号
USER.md	用户资料、偏好、工作背景
MEMORY.md	长期整理的记忆（自动注入主会话）
TOOLS.md	本地备注——SSH 主机、设备名称、环境详情
HEARTBEAT.md	定期任务（为空时跳过心跳）
BOOTSTRAP.md	首次运行引导（初始设置后删除）

记忆系统

• 每日笔记： memory/YYYY-MM-DD.md — 原始日志（按需通过工具访问）
• 长期记忆： MEMORY.md — 精选内容，每个会话都会自动注入
• 工具：memory_store、memory_recall、memory_forget

---

安全模型

• 默认拒绝的频道白名单
• 默认要求网关配对
• 默认禁用公开绑定
• 工作区范围内的文件系统访问
• 用于 Shell 执行的命令白名单
• 速率限制（每小时操作次数、每日成本）
• 加密的机密信息存储
• 可插拔的沙箱机制（Landlock、Firejail、Bubblewrap、Docker — 由功能标志控制）
• 审计日志（提案/路线图 — 由 HMAC 签名、防篡改的日志）

---

LangGraph / Python 集成

zeroclaw-tools Python 包提供基于 LangGraph 的工具调用，可确保与任何兼容 OpenAI 的提供商行为一致：

pip install zeroclaw-tools

from zeroclaw_tools import create_agent, shell, file_read, file_write
agent = create_agent(tools=[shell, file_read, file_write], model="glm-5", api_key="your-api-key", base_url="your-base-url")

---

Open Skills 集成

ZeroClaw 集成了 Open Skills (https://github.com/besoeasy/open-skills) — 预构建的执行手册，可减少 95-98% 的令牌用量。

技能会同步至 ~/.zeroclaw/workspace/skills/，并通过以下方式安装：

zeroclaw skills install <github-url-or-local-path>

---

核心设计原则

1. 零开销 — <5MB RAM、<10ms 启动时间、约 3.4MB 二进制文件
2. 毫不妥协 — 在不牺牲性能的前提下提供全面安全性
3. 100% Rust — 单个二进制文件，无运行时依赖
4. 100% 通用 — 可随时切换提供商、频道、工具、记忆和隧道
5. Trait 驱动 — 每个子系统都是一个 Trait，因此一切都可插拔
6. 默认安全 — 配对、范围限制、白名单、加密的机密信息