当前位置：首页 > news >正文

zeroclaw 使用教程

news 2026/6/16 20:28:29

ZeroClaw 使用教程

什么是 ZeroClaw

ZeroClaw 是一个 Rust 优先的自主 Agent 运行时，专注于性能、效率、稳定性、可扩展性和安全性。它由以下核心部分组成：

组件	说明
Agent	核心执行单元，每个 Agent 有自己的模型、安全策略、频道绑定
Provider	大模型接入抽象层，支持 30+ 家模型供应商
Channel	消息通道（Discord、Telegram、Slack、CLI、Webhook 等）
Risk Profile	安全与自主分级（readonly / supervised / full / yolo）
Runtime Profile	运行时调优参数（上下文长度、工具迭代次数等）
Memory	记忆后端（SQLite、Markdown、Postgres、Qdrant 等）
Tool	工具系统（Shell、文件、浏览器、MCP 等）

核心架构：一个二进制，多个 Agent 共存。从第一行配置开始，Agent 就是多实例的。

v0.7.x → v0.8.0 版本变化

v0.8.0 是 ZeroClaw 的一个重大版本，包含 439 次提交（自 v0.7.5 起），100+ 贡献者参与。以下是对比总结。

核心架构变化

维度	v0.7.x	v0.8.0
Agent 模型	单 Agent，单配置	多 Agent 原生支持：一个 daemon 运行多个命名 Agent，各有独立的工作区、记忆、模型、安全策略和频道
配置 Schema	V2	V3（自动迁移）：配置文件首次加载时自动完成迁移。Provider 条目支持每个供应商多个别名，单个格式错误的条目不再清除其邻居
终端 UI	无	zerocode：全新终端 TUI，包含 Chat、Code、Dashboard、Config、Quickstart、Logs 面板
日志系统	传统 trace-event 路径	统一结构化日志流水线：携带 agent、model、session 归因，通过日志面板和网关端点流式输出
频道构建	默认包含所有频道	精简默认频道包：预编译二进制只包含核心频道，社交频道移至 opt-in 构建特性

多 Agent 运行时（最大变化）

v0.8.0 最核心的变化：从单 Agent 变为多 Agent 架构。

v0.7.x 时代：

一个 daemon 只运行一个 bot
Agent 是隐式的，没有命名概念
配置中只有一个隐式 agent 块

v0.8.0 之后：

一个 daemon 运行任意数量的命名 Agent
每个 Agent 拥有独立隔离的资源：
- workspace/ 目录（磁盘隔离）
- 记忆后端（SQLite/Markdown/Postgres/Qdrant，按 agent UUID 隔离）
- 模型供应商绑定（model_provider）
- 安全策略（risk_profile）
- 频道绑定（channels = [...]）
- 技能包、人格文件、cron 定时任务
Agent 间可通过 peer group 在共享频道上互相 @提及
Agent 间可通过 delegation 委派任务（需授权）
Agent 可生成 SubAgent 执行子任务

具体配置参见本文档的多 Agents 配置章节。

新增功能

zerocode 终端 UI

本地连接：Unix domain socket / Windows named pipe，零配置
远程连接：TLS WebSocket，支持自签名证书 + Token 认证
Shell 环境透传：zerocode 将终端的完整环境变量转发给 daemon，PATH、SSH_AUTH_SOCK 等自动生效
主题系统：4 种内置键位预设 + 每动作自定义键位绑定
多面板：Chat（对话）、Code（ACP 编码工作区）、Dashboard（实时 Agent 状态）、Config（配置编辑器）、Quickstart（引导创建 Agent）、Logs（结构化日志流）
持久会话：关闭笔记本，一小时后从不同网络重新连接，会话仍在

大模型供应商

新供应商：Kilo AI Gateway、GitHub Models、Morph、Manifest、atomic-chat、llama.cpp 专用 provider 等 7+ 个 OpenAI 兼容供应商
新能力：Anthropic/Bedrock 原生 extended thinking、OpenRouter prompt caching、OpenAI Codex Responses 协议、Provider 自动降级（fallback）
Schema V3 迁移：Provider 条目支持多个别名，单个条目格式错误不再影响其他条目

频道

新频道：Twitch、WeCom AI Bot、AMQP（mutual TLS）、多租户 Linq
新能力：按接收者回复限速（9 个频道）、可配置的在途消息预算、Webhook 指数退避重试、回复意图预检

工具与插件

新工具：远程文件下载到工作区、HTTP 文件上传、Agent 循环内直接发消息到频道、读写二进制文件、认证 HTTP 请求
WASM 插件接口：正式定义了 Tool/Channel/Memory 的 WIT 接口，已有 Office 文档提取、LanguageTool 语法检查、Stable Diffusion 图片生成等插件

记忆系统

可插拔的记忆策略：Agent-turn、gateway、channel 合并走同一条路径
时间窗口 recall 在 Markdown 后端正确工作
Postgres 后端初始化问题修复

安全强化

Dashboard Canvas iframe 令牌窃取修复（GHSA-f385-f6h2-3gqj）
Bearer token 吊销：轮换或删除已配对设备时实际使其失效
秘钥处理：遮盖覆盖所有凭证形状的配置表面，频道编排器不再回退到其他 provider 的凭证
出站请求防护：HTTP 请求工具的私有主机白名单，DNS 解析到私有地址时阻止
工具门控：每 Agent 工具白名单在频道启动和每条消息时都强制检查
沙箱：更严格的 Linux 沙箱库绑定，交互式子进程不再能劫持控制终端

行为变更

方面	v0.7.x	v0.8.0
配置迁移	—	首次加载自动从 V2 迁移到 V3
Profile 设置	安全策略和运行时调优混合	拆分为 `risk_profile`（安全）和 `runtime_profile`（调优）两部分
费用管理	全局费率	按 Provider + Model 组织的费率表
定时任务	绑定到隐式默认 Agent	必须显式指定 `[cron.<name>].agent`
频道默认	所有频道都编译进二进制	精简包，额外频道需要 `--features channels-full`
Provider 环境变量	支持 `ANTHROPIC_API_KEY` 等传统名	统一使用 schema-mirror 语法 `ZEROCLAW_providers__models__<type>__<alias>__api_key`
日志宏	允许第三方日志宏	全工作区禁止第三方日志宏，统一使用内部 `record!`
Observer 事件	`ObserverEvent` 封闭枚举	`#[non_exhaustive]`，增加 `MemoryRecall`/`MemoryStore`/`RagRetrieve`

配置文件迁移对照

v0.8.0 的配置从 V2 升级到 V3，以下是关键变化：

# v0.7.x （V2）
[providers]
api_key = "..."
model = "claude-sonnet-4-5"# v0.8.0 （V3）—— 自动迁移
[providers.models.anthropic.home]
api_key = "..."
model = "claude-sonnet-4-5"

# v0.7.x —— Agent 是隐式的
# 没有 [agents.*] 块，只有一个 agent# v0.8.0 —— Agent 必须显式声明
[agents.my_agent]
model_provider = "anthropic.home"
risk_profile   = "default"

# v0.7.x —— 安全策略和运行时调优混合
[security]
level = "supervised"
workspace_only = true
max_tool_iterations = 10# v0.8.0 —— 拆分
[risk_profiles.default]
level = "supervised"
workspace_only = true[runtime_profiles.default]
max_tool_iterations = 10

# v0.7.x —— 定时任务绑定隐式 agent
[cron]
jobs = [{ schedule = "0 9 * * *", prompt = "每日报告" }
]# v0.8.0 —— 必须指定 agent
[cron.daily_report]
schedule = "0 9 * * *"
prompt   = "每日报告"
agent    = "my_agent"

升级建议

配置会自动迁移——v0.8.0 首次启动时自动将旧配置转为 V3 格式，原文件会被备份
检查频道是否可用——如果使用社交频道（Twitter、Bluesky、Nostr、Reddit 等），需要 --features channels-full 或单独启用特性：
```
./install.sh --source --preset full
# 或
cargo build --features channels-full
```
更新定时任务配置——如果使用了 cron，需要给每个任务添加 agent 字段
审计环境变量——从 ANTHROPIC_API_KEY 等传统环境变量迁移到 ZEROCLAW_providers__models__anthropic__<alias>__api_key 格式
体验 zerocode——运行 zerocode 命令启动终端 TUI，这是 v0.8.0 推荐的交互方式

v0.8.0 beta 用户请注意：自 beta-2 以来的 184 次提交主要集中在稳定性修复，包括配置正确性、频道投递、cron 调度和运行时稳定性。

安装与快速配置

安装

Linux / macOS：

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

Windows：

setup.bat

或通过 Scoop：

scoop install zeroclaw

从源码安装：

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

安装后你得到两个命令：

zeroclaw — 核心二进制（CLI、daemon、配置管理）
zerocode — 终端 TUI 界面

快速配置（Quickstart）

ZeroClaw 提供三套配置入口，最终生成的配置完全一致：

方式一：CLI 交互式配置

zeroclaw quickstart

按提示依次设置以下内容（带 * 的为必填）：

步骤	必填	说明
Model provider	是	选择模型供应商（Anthropic、OpenAI、Ollama、OpenRouter 等）并输入 API Key
Risk profile	是	选择安全等级（建议先用 `supervised`）
Memory	是	选择记忆后端（开发机用 `sqlite` 或 `markdown`）
Channels	可选	绑定消息通道（CLI 通道始终可用）
Peer groups	可选	多 Agent 之间的通信组
Agent	是	设置 Agent 名称和系统提示词

方式二：TUI 图形化配置

zerocode

进入后切换到 Quickstart 面板，用键盘或鼠标完成配置。

方式三：Web 界面配置

zeroclaw daemon

浏览器打开 http://127.0.0.1:42617/quickstart，在 Web 表单中完成配置。

使用 Agent

配置完成后，通过 CLI 与 Agent 对话：

zeroclaw agent -a <alias> -m "你好，请介绍一下你自己"

启动守护进程，让 Agent 持续在线：

zeroclaw daemon

安装为系统服务：

zeroclaw service install && zeroclaw service start

本地化（中文界面）

zeroclaw locales fetch zh-CN

然后在配置中添加 locale = "zh-CN"，重启后生效。

配置文件结构

ZeroClaw 的配置文件为 TOML 格式，默认位于 ~/.zeroclaw/config.toml。最小配置文件示例如下：

[providers.models.anthropic.home]
api_key = "sk-ant-..."
model   = "claude-sonnet-4-20250514"[risk_profiles.default]
level = "supervised"[agents.dev]
model_provider = "anthropic.home"
risk_profile   = "default"

Risk Profile：安全与自主等级

Risk Profile 是 ZeroClaw 的安全策略核心，每个 Agent 必须绑定一个。它控制 Agent 能做什么、需要什么级别的审批、能访问哪些文件、使用什么沙箱。

与 Runtime Profile 的区分

很多人把这两者搞混，它们的职责完全不同：

	Risk Profile	Runtime Profile
管理什么	安全与权限	性能与行为调优
典型字段	`level`, `workspace_only`, `forbidden_paths`	`max_tool_iterations`, `max_context_tokens`
是否必须	是（否则 Agent 无法启动）	否（有默认值）
影响范围	命令能否执行、文件能否访问	上下文窗口大小、工具迭代次数

简单说：Risk Profile = 能不能做，Runtime Profile = 怎么做得好。

四个自主等级

[risk_profiles.<alias>]
level = "supervised"   # 可选：readonly / supervised / full / yolo

等级	行为	适用场景
`readonly`	只读，不能修改任何东西。`file_read`、`http GET`、`memory_search` 等无副作用的工具可用；`file_write`、`shell`、`http POST` 被阻止。	面向公众的 Q&A Agent、分析专用部署、新工具配置上线前验证
`supervised`（默认）	低风险工具自动运行，中风险工具弹窗审批，高风险工具拦截。	日常开发、大多数业务场景
`full`	无审批门控，所有工具（低/中/高）自动执行。`workspace_only` 隐式关闭，沙箱仍有效。	受信任的本地开发、CI/CD、SOP 全自动流程
`yolo`	关闭所有安全措施。无审批、无工作区边界、无 Shell 策略、无沙箱、无 OTP 验证。	仅限开发机、家庭实验室、一次性 VM

四级的风险分类

在 supervised 模式下，工具按风险分为三档：

风险	示例	行为
低	`file_read`、`http GET`、`memory_search`、`web_search`、`time`	直接执行
中	工作区内的 `file_write`、白名单内的 `shell` 命令、允许域名的 `http POST`	弹窗审批
高	未知/被禁止的 `shell` 命令、工作区外的 `file_write`、破坏性模式	拦截

readonly 只允许低风险工具，full 和 yolo 跳过所有审批直接执行。

审核机制

supervised 模式下，中风险操作的审批弹窗通过发起对话的频道送达：

Telegram：内联键盘按钮（允许一次 / 始终允许 / 拒绝）
Slack：Block Kit 按钮
Discord / Signal / Matrix / WhatsApp：嵌入短 Token，回复 <token> approve|deny|always
CLI：内联提示
ACP：session/request_permission JSON-RPC 请求

审批超时时间由频道的 approval_timeout_secs 控制（默认 120 秒），超时视为拒绝。

完整字段参考

[risk_profiles.<alias>]
# ── 自主等级 ──
level = "supervised"                       # readonly / supervised / full / yolo# ── 路径控制 ──
workspace_only = true                      # true = 只能访问工作区目录
forbidden_paths = [                        # 始终禁止访问的路径"/etc", "/sys", "/boot","~/.ssh", "~/.gnupg","/proc", "/dev",
]# ── Shell 命令控制 ──
allowed_commands = [                       # 非空时严格执行白名单"git", "cargo", "node", "python","ls", "cat", "grep", "find", "sed", "awk",
]
block_high_risk_commands = true            # 阻止 rm -rf / 等破坏性命令
shell_env_passthrough = [                  # 传递给 shell 的环境变量"PATH", "HOME", "USER",# 含 API_KEY / _TOKEN / _SECRET / _PASSWORD 的变量不会自动传递
]# ── 工具覆盖 ──
auto_approve = [                           # 跳过审批自动执行（即使 level=supervised）"file_write",
]
always_ask = [                             # 始终弹窗审批（即使 level=full）"shell",
]
excluded_tools = [                         # 彻底禁用某些工具"http_request",
]# ── 沙箱（OS 级隔离） ──
sandbox_enabled = true                     # 启用沙箱
sandbox_backend = "auto"                   # auto / landlock / bubblewrap / firejail / docker / seatbelt / none
# firejail_args = ["--net=none"]           # 仅 Firejail 后端可用# ── 预算限制 ──
max_actions_per_hour = 100                 # 每小时最大操作次数
max_cost_per_day_cents = 200               # 每日最大费用（美分）
shell_timeout_secs = 300                   # 单个 shell 命令超时# ── 委派策略 ──
[risk_profiles.<alias>.delegation_policy]
mode = "forbidden"                         # forbidden / allow# ── 工作区跨 Agent 访问（多 Agent 共享记忆） ──
# 该配置在 [agents.<alias>.workspace] 而非 risk_profile 中

沙箱后端

后端	平台	说明
`landlock`	Linux （内核 5.13+）	零配置，内核级，极低开销
`bubblewrap`	Linux	用户命名空间，可阻断网络
`firejail`	Linux	SUID 沙箱
`docker`	全平台	强隔离，每次调用 100-500ms 容器启动开销
`seatbelt`	macOS	原生 macOS 沙箱
`none`	全平台	不沙箱（YOLO 默认）

设置 sandbox_backend = "auto" 会在启动时自动选择最佳可用后端。

完整配置示例

一个面向生产环境的 Agent 配置：

[risk_profiles.production]
level                            = "supervised"
workspace_only                   = true
block_high_risk_commands         = true
sandbox_enabled                  = true
sandbox_backend                  = "auto"
forbidden_paths                  = ["/etc", "/sys", "/boot", "~/.ssh"]
allowed_commands                 = ["git", "cargo", "ls", "cat", "grep"]
require_approval_for_medium_risk = true
shell_timeout_secs               = 60
max_actions_per_hour             = 500
shell_env_passthrough            = ["PATH", "HOME"][agents.myprod]
model_provider = "anthropic.home"
risk_profile   = "production"

多 Agent 使用不同 Risk Profile

每个 Agent 独立绑定 Risk Profile，同一台机器上的多个 Agent 可以拥有截然不同的安全等级：

[risk_profiles.strict]
level = "supervised"
workspace_only = true
block_high_risk_commands = true[risk_profiles.loose]
level = "full"[agents.internal]
model_provider = "anthropic.sonnet"
risk_profile   = "strict"
channels       = ["slack.internal"][agents.experiment]
model_provider = "anthropic.haiku"
risk_profile   = "loose"
# 没有频道绑定，只能通过 CLI 调用

内部助手需要审批才能写文件，实验 Agent 可以自由操作。

按频道收紧权限

自主等级是按 Agent 而非按频道的。如果公网频道需要更严格的权限：

创建第二个 Agent，绑定更严格的 Risk Profile，把频道指向它
或使用 excluded_tools 按频道隐藏工具 的轻量方案：

[channels.telegram.public]
token = "..."
excluded_tools = ["shell", "file_write", "http_request"]

委派策略

Risk Profile 控制 Agent 能否委派任务给其他 Agent：

[risk_profiles.default]
level = "supervised"[risk_profiles.default.delegation_policy]
mode = "allow"   # 默认 forbidden，不允许委派

开启后，同 Risk Profile 的 Agent 间可以互相委派。跨 Risk Profile 委派需要显式在 [agents.<caller>].delegates 中列出。

YOLO 模式

YOLO 模式关闭所有安全门：无需审批、没有工作区边界、不限制 Shell 命令、不限制文件访问、无沙箱。Agent 可以立即执行任何操作。

警告：YOLO 模式仅适用于开发机、家庭实验室和一次性 VM。 不要在共享服务器、存有生产凭据的机器或可通过公网频道访问的 Agent 上使用。

启用 YOLO

[risk_profiles.yolo]
level = "yolo"

然后在 Agent 上指向该配置：

[agents.myagent]
model_provider = "anthropic.home"
risk_profile   = "yolo"

YOLO 对比普通模式

安全措施	普通模式	YOLO 模式
自主权	中风险操作需审批	全自动运行
工作区边界	仅限 `~/.zeroclaw/workspace/`	无限制
Shell 策略	未知命令被阻止	任意命令均可执行
禁止路径	`/etc`、`/sys`、`~/.ssh` 等被阻止	无限制
沙箱	Docker / Firejail / Landlock 隔离	直接运行
OTP 门控	敏感操作需验证码	无验证

YOLO 仍然保留的

工具收据日志：tail -f 可实时查看执行记录
审计日志：如果 [security.audit] enabled = true 则仍会记录
对话记忆：Agent 仍然保留对话历史

强烈建议在 YOLO 模式下开启审计日志：

[security.audit]
enabled = true

恢复安全模式

删除或修改 risk_profile 中的 YOLO 设置后重启即可：

[risk_profiles.yolo]
level = "supervised"   # 或 full / readonly

接入大模型

ZeroClaw 支持 30+ 家模型供应商，所有供应商统一在 [providers.models.<type>.<alias>] 下配置。

常见供应商配置示例

Anthropic（Claude）

[providers.models.anthropic.home]
api_key = "sk-ant-..."
model   = "claude-sonnet-4-20250514"

支持 OAuth 令牌（sk-ant-oat-*形式），可使用 Claude Pro/Team 订阅。

OpenAI（GPT）

[providers.models.openai.home]
api_key = "sk-..."
model   = "gpt-4o"

Ollama（本地模型）

[providers.models.ollama.local]
uri   = "http://localhost:11434"
model = "qwen2.5-coder:7b"

无需 API Key。

OpenRouter（多供应商路由）

[providers.models.openrouter.prod]
api_key = "sk-or-..."
model   = "anthropic/claude-3.5-sonnet"

OpenRouter 是跨供应商高可用的推荐方案——供应商故障由 OpenRouter 处理。

Azure OpenAI

[providers.models.azure.mydeploy]
resource     = "my-resource"
deployment   = "gpt-4o"
api_version  = "2025-01-01-preview"
api_key      = "..."

自定义 OpenAI 兼容端点

[providers.models.custom.mylocal]
uri   = "http://192.168.1.100:8080/v1"
model = "my-model"

国内供应商

Moonshot：

[providers.models.moonshot.home]
model = "moonshot-v1-8k"
# endpoint = "cn"   # 默认国内；可选 intl / code

Qwen / DashScope：

[providers.models.qwen.home]
model    = "qwen-turbo"
api_key  = "..."
# endpoint = "cn"       # 可选 intl

GLM / MiniMax / Z.AI / Doubao 等：

国内供应商使用对应 slot 键（glm、minimax、zai、doubao），通过 endpoint 字段选择区域。

凭证管理

凭证解析顺序：

内联 api_key — 直接写在配置中（方便开发，不应提交到仓库）
密钥库 — ~/.zeroclaw/secrets 加密存储
环境变量覆盖 — ZEROCLAW_providers__models__<type>__<alias>__api_key=...
供应商默认环境变量 — 如 ANTHROPIC_API_KEY、OPENAI_API_KEY

推荐做法：使用环境变量注入，不将密钥写入配置文件：

export ZEROCLAW_providers__models__anthropic__home__api_key="sk-ant-..."

Provider 容灾

可以为 Provider 配置降级模型和降级供应商：

[providers.models.anthropic.prod]
api_key = "..."
model   = "claude-sonnet-4-5"
fallback_models = ["claude-haiku-4-5"][[providers.models.anthropic.prod.fallback]]
model_provider = "openai.backup"
model          = "gpt-4.1"

尝试顺序：

anthropic.prod/claude-sonnet-4-5→ anthropic.prod/claude-haiku-4-5→ openai.backup/gpt-4.1

本地模型 + 远程模型混合开发

[providers.models.ollama.local]
uri   = "http://localhost:11434"
model = "qwen2.5-coder:7b"[agents.dev]
model_provider  = "ollama.local"
risk_profile    = "supervised"
runtime_profile = "local_small"[runtime_profiles.local_small]
compact_context          = true
strict_tool_parsing      = true
max_tool_iterations      = 4
max_history_messages     = 20
max_context_tokens       = 8000
max_tool_result_chars    = 4000
keep_tool_context_turns  = 1

多 Agents 配置

ZeroClaw 从第一行配置开始就支持多 Agent，不存在「主 Agent」。运行时持有以 Alias 为键的 Agent 映射表，单 Agent 部署只是大小为 1 的映射。

核心概念

每个 Agent 是一个 join，连接以下两半：

  配置引用（关系侧）                   文件系统（磁盘侧）────────────────                    ──────────────- 模型供应商                          - workspace/- 风险配置              agents.<alias> - 记忆存储- 运行时配置        ──▶  (join)  ◀──  - 身份/人格文件- 频道- 对等组- 技能/知识/MCP 包- 定时任务

关键原则：Agent 不「拥有」左侧的任何引用——多个 Agent 可以共享或各自独立。

最小多 Agent 示例

两个 Agent 共享一个模型供应商，但运行不同风险策略、绑定不同频道：

[providers.models.anthropic.prod]
api_key = "..."
model   = "claude-sonnet-4-5"[risk_profiles.hardened]
level              = "supervised"
workspace_only     = true
block_high_risk_commands = true[risk_profiles.permissive]
level              = "full"[agents.researcher]
model_provider = "anthropic.prod"
risk_profile   = "hardened"
channels       = ["slack.helpdesk"][agents.support]
model_provider = "anthropic.prod"
risk_profile   = "permissive"
channels       = ["discord.main"][channels.slack.helpdesk]
# Slack 频道配置[channels.discord.main]
# Discord 频道配置

Agent 间的通信

Agent 之间有两种通信方式，分别受不同机制控制：

1. 对等组（Peer Group）

Agent 共享频道的对等组时，可以在同一频道上互相 @提及：

[peer_groups.dev_team]
channel = "discord.main"
members = ["researcher", "support"][agents.researcher]
# ...
peer_groups = ["dev_team"][agents.support]
# ...
peer_groups = ["dev_team"]

成员关系是双向的：两个 Agent 同时出现在同一 members 列表中才是对等。

2. 委派（Delegation）

Agent 可以将任务委派给另一个 Agent：

[risk_profiles.default]
level = "supervised"[risk_profiles.default.delegation_policy]
mode = "allow"   # 默认 forbidden

委派限制：

目标 Agent 必须与调用方共享同一 risk_profile（同信任层级）
或通过 [agents.<caller>].delegates 显式列出跨信任层级的委派目标
深度由 runtime_profile.max_delegation_depth 控制（默认 3）

3. SubAgent（子 Agent）

Agent 可以生成一个临时子进程，继承父 Agent 的完整权限执行子任务：

子 Agent 运行在父 Agent 的会话中
继承父 Agent 的身份、安全策略、模型
深度限制为 1 层（SubAgent 不能再生成 SubAgent）
子 Agent 结束时仅将最终结果返回给父 Agent

复杂多 Agent 架构示例

                    agents.researcher          agents.support─────────────────          ──────────────model provider     openrouter.prod ◀───────── openrouter.prod  (共享同一个)risk profile       hardened                   permissive        (不同)channel            discord.main               slack.helpdesk    (不同)peers               └──────▶ peer group on discord.main ◀───────┘

两个 Agent 共享同一个模型供应商，运行在不同风险配置下，回复不同频道，仅在对等组所在的频道上互通。

成本分层示例

使用廉价模型处理高流量频道，复杂推理需求时委派给强模型：

[providers.models.anthropic.haiku]
api_key = "..."
model   = "claude-haiku-4-5"[providers.models.anthropic.sonnet]
api_key = "..."
model   = "claude-sonnet-4-5"[risk_profiles.trusted]
level = "supervised"[risk_profiles.trusted.delegation_policy]
mode = "allow"[agents.frontline]
model_provider = "anthropic.haiku"
risk_profile   = "trusted"
channels       = ["discord.main"][agents.heavy]
model_provider = "anthropic.sonnet"
risk_profile   = "trusted"
# 无频道绑定，仅供 frontline 委派调用

frontline Agent 处理日常对话，遇到需要深度推理的问题时调用 delegate 工具，将任务交给 heavy Agent。

通过频道路由实现多模型分发

每个 Agent 绑定一个 Provider，频道选择绑定到哪个 Agent：

# 视觉模型
[agents.vision]
model_provider = "anthropic.sonnet"
channels       = ["discord.image_channel"]# 文本模型
[agents.fast]
model_provider = "anthropic.haiku"
channels       = ["discord.text_channel"]

频道变更只需编辑 Agent 的 channels 列表，Config::validate() 会在启动时检查引用是否有效。

Shell 命令执行

ZeroClaw 的 shell 工具是 Agent 最强大的内置工具之一——Agent 通过它直接在宿主机上执行命令。理解它的运作机制对安全和调优至关重要。

完整执行流程

Agent 调用 shell 工具时，经过以下 12 步流水线：

Agent 调用 shell(command="ls -la", approved=false)│├─ 1. 参数提取：获取 command 字符串和 approved 布尔值│├─ 2. SecurityPolicy.validate_command_execution()│     ├── 只读检查：readonly 模式下任何命令都拒绝│     ├── 风险分级：低/中/高三档│     ├── 白名单检查：allowed_commands 非空时严格匹配│     ├── 阻断检测：block_high_risk_commands 拦截 rm -rf / 等│     └── 审批检查：中风险且未批准时返回审批提示│├─ 3. RuntimeAdapter.build_shell_command()│     ├── Unix:   sh -c "<command>"│     └── Windows: cmd.exe /C "<command>"│├─ 4. Sandbox.wrap_command() —— OS 级隔离│     ├── Landlock   (Linux 内核 5.13+，零配置)│     ├── Bubblewrap (用户命名空间)│     ├── Firejail   (SUID 沙箱)│     ├── Docker     (容器运行)│     ├── Seatbelt   (macOS)│     └── Noop       (无沙箱)│├─ 5. 环境变量清理 —— env_clear() 防止泄露│├─ 6. 注入安全环境变量│     ├── SAFE_ENV_VARS 内置白名单（PATH、HOME、TERM 等）│     ├── shell_env_passthrough 用户自定义变量│     └── TUI 客户端环境覆盖（如有）│├─ 7. 进程组设置 (Unix) —— process_group(0)，超时可 SIGKILL 整个子树│├─ 8. Stdio 重定向：stdout→piped, stderr→piped, stdin→null│├─ 9. spawn() 启动子进程│├─ 10. 异步读取输出 —— 上限 1MB，子进程退出后继续 drain 250ms│├─ 11. 超时控制 —— 默认 60 秒后 SIGKILL 并返回超时错误│└─ 12. 输出解码├─ Windows: 查询控制台代码页 (GBK、Shift_JIS、Big5 等)└─ 其他:    String::from_utf8_lossy

ShellTool 的参数

{"command":  "string (必填)",   // 要执行的命令"approved": "boolean (默认 false)"  // 手动确认高风险操作
}

Agent 发起调用时由大模型填写 command 参数，approved 通常为 false——在 supervised 模式下，中风险操作会通过频道向用户发送审批弹窗。

核心：SecurityPolicy 的 5 层命令门控

SecurityPolicy::validate_command_execution() 执行严格的命令验证：

readonly 检查     → 只读模式下直接拒绝所有命令│
wildcard 检查     → allowed_commands 为空则放行（使用默认白名单）│
subshell 检查     → 阻止嵌套 shell、命令替换 $()、`` ` `` 等逃逸│
redirect 检查     → 检测并阻止文件重定向攻击│
白名单匹配        → 依次检查命令名，然后逐参数校验│└─ is_args_safe(base, args) 对以下命令做参数级安全校验：git:    禁止 --git-dir、--work-tree 等选项python: 禁止 -c 内联代码、禁止 -m 加载危险模块node:   禁止 -e 内联代码pip/npm/cargo: 禁止指向外部源的 install 等

默认命令白名单（allowed_commands 为空时的默认值）：

平台	默认允许的命令
Unix	`git`, `npm`, `cargo`, `ls`, `cat`, `grep`, `find`, `echo`, `pwd`, `wc`, `head`, `tail`, `date`, `df`, `du`, `uname`, `uptime`, `hostname`, `python`, `python3`, `pip`, `node`, `free`
Windows	上述全部 + `dir`, `type`, `findstr`, `where`, `more`

高风险命令（block_high_risk_commands=true 时自动拦截）：

rm, mkfs, dd, shutdown, reboot, halt, poweroff, sudo, su, chown, chmod, useradd, userdel, mount, umount, iptables, ufw, ssh, scp, curl -o, wget -O, 以及 Windows 上的 format, reg, net, runas, icacls, takeown, powershell, pwsh, netsh 等。

中风险命令（supervised 模式下触发审批）：

git commit/push/reset/clean/rebase/merge 等写操作、npm/pnpm/yarn install/add/remove、cargo add/remove/install/clean/publish、touch, mkdir, mv, cp, ln, rm（非递归删除文件）。

环境变量策略

ZeroClaw 采用 白名单优先 的环境变量策略：

cmd.env_clear() — 先彻底清空环境，防止 daemon 进程的环境变量泄露（CWE-200）
SAFE_ENV_VARS — 内置安全变量：
- Unix: PATH, HOME, TERM, LANG, LC_ALL, LC_CTYPE, USER, SHELL, TMPDIR
- Windows: 增加 PATHEXT, USERPROFILE, HOMEDRIVE, HOMEPATH, SYSTEMROOT, SYSTEMDRIVE, WINDIR, COMSPEC, TEMP, TMP, USERNAME
shell_env_passthrough — 用户通过 Risk Profile 自定义添加
TUI 客户端环境 — 通过 zerocode 连接的客户端环境叠加（如 SSH Agent 转发）

含敏感词的模式不会自动传递：变量名包含 API_KEY、_TOKEN、_SECRET、_PASSWORD 的变量必须显式在 shell_env_passthrough 中列出。

通过 Risk Profile 添加自定义环境变量：

[risk_profiles.development]
level = "supervised"
shell_env_passthrough = ["PATH", "HOME","MY_CUSTOM_VAR","SSH_AUTH_SOCK",    # SSH 代理转发
]

沙箱对 Shell 的影响

沙箱在 wrap_command() 环节对命令进行 OS 级隔离，不同后端的影响：

沙箱后端	文件系统	网络	启动开销
无沙箱	全部可访问	全部可访问	0
Landlock	限制到工作区 + 系统库路径	不限制（Landlock 不控制网络）	极低
Bubblewrap	限制到工作区	可选阻断	低
Firejail	限制到工作区 + 自定义 profile	可选阻断	低
Docker	容器隔离，仅挂载工作区	可通过 `--network` 控制	100-500ms
Seatbelt (macOS)	限制到工作区	不限制	低

Docker 运行时下的 Shell 执行（[runtime] kind = "docker"）：

[runtime]
kind = "docker"[runtime.docker]
image = "zeroclaw-sandbox:local"
memory = "512m"
cpus = 1.0
network = "none"

这会生成实际命令：docker run --rm --init --interactive --memory 512m --cpus 1.0 --network none -v <workspace>:<workspace> -w <workspace> <image> sh -c "<command>"

Shell 工具的内外层包装

在工具注册时，shell 工具被三层包裹：

RateLimitedTool       ← 按 SecurityPolicy.max_actions_per_hour 限速└─ PathGuardedTool  ← 扫描命令参数中的禁止路径└─ ShellTool   ← 实际执行（验证 → 构建 → 沙箱 → 执行 → 解码）

PathGuardedTool 从命令参数中解析出所有路径引用（文件路径、重定向目标、选项值），与 forbidden_paths 比对，阻止访问 /etc、~/.ssh 等敏感路径。

默认禁止路径

平台	禁止路径
Unix	`/etc`, `/root`, `/home`, `/usr`, `/bin`, `/sbin`, `/lib`, `/opt`, `/boot`, `/dev`, `/proc`, `/sys`, `/var`, `/tmp`, `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config`
Windows	`C:\Windows`, `C:\Windows\System32`, `C:\Program Files`, `C:\Program Files (x86)`, `C:\ProgramData`, `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config`

超时与输出限制

参数	默认值	配置位置
Shell 超时	60 秒	`[shell_tool] timeout_secs` 或 Risk Profile 的 `shell_timeout_secs`
输出上限	1 MB	硬编码 `MAX_OUTPUT_BYTES`
退出后 drain	250 ms	硬编码 `POST_EXIT_DRAIN`

# 全局 Shell 超时
[shell_tool]
timeout_secs = 120# 或按 Risk Profile 单独设置（优先级更高）
[risk_profiles.development]
shell_timeout_secs = 300

Windows 特有处理

Windows 上额外处理以下几个问题：

raw_arg() 避免引号破坏：使用 raw_arg() 绕过 Rust 的 CommandLineToArgvW 转义，确保带空格的路径和双引号参数原样传递给 cmd.exe
CREATE_NO_WINDOW：0x08000000 标志让 cmd.exe 不在桌面上弹出黑窗口
代码页转码：运行时查询活动控制台代码页（CP936/GBK、CP932/Shift_JIS、CP949/EUC-KR、CP950/Big5 等），用 encoding_rs 正确解码输出

在 ZeroClaw 中使用 tmux

ZeroClaw 通过 claude_code_runner 工具原生支持 tmux 会话管理，用于在后台长期运行 Claude Code 任务。

claude_code_runner 工具

claude_code_runner 是一个内置工具，在 tmux 中创建独立会话运行 claude 命令：

执行流程：

Agent 调用 claude_code_runner(prompt="...", working_directory="...")│├─ 1. 安全策略检查：enforce_tool_operation（只读模式拒绝、限速检查）│├─ 2. 工作目录验证：必须在 workspace 目录内│├─ 3. 生成唯一 session ID（UUID 前 8 位）│├─ 4. tmux new-session -d -s zc-claude-<id> -c <work_dir>│      └── 在后台创建 tmux 会话│├─ 5. tmux send-keys -t zc-claude-<id> "<env_exports> <claude命令>" Enter│      └── 向 tmux 会话发送命令并执行│├─ 6. 环境变量注入│     ├── SAFE_ENV_VARS（PATH, HOME, TERM 等）│     ├── CLAUDE_CODE_SESSION_ID=<id>│     ├── CLAUDE_CODE_HOOK_URL=http://localhost:42617/hooks/claude-code│     └── CLAUDE_CODE_SLACK_CHANNEL=<channel>（可选）│├─ 7. 返回立即响应│     ├── Session started: zc-claude-<id>│     ├── 本地 attach: tmux attach-session -t zc-claude-<id>│     └── SSH attach（如有配置）: ssh -t <host> tmux attach-session -t zc-claude-<id>│└─ 8. TTL 到期自动清理└── session_ttl 秒后自动 kill-session

配置 tmux 支持

claude_code_runner 的配置在 ClaudeCodeRunnerConfig 中：

[claude_code_runner]
enabled = true                  # 启用工具
tmux_prefix = "zc-claude-"     # tmux 会话名前缀
ssh_host = "dev.example.com"   # SSH 主机（可选），用于远程 attach
session_ttl = 3600             # 会话 TTL（秒），默认 3600（1 小时）

使用场景

场景一：Agent 自动启动 Claude Code 任务

在对话中，Agent 会判断何时需要启动长时间运行的 Claude Code 任务。当 Agent 调用 claude_code_runner 后，你得到类似如下的回复：

Session started: zc-claude-a1b2c3d4
Session ID: a1b2c3d4
Hook URL: http://localhost:42617/hooks/claude-code
Local attach: tmux attach-session -t zc-claude-a1b2c3d4

然后你可以用 tmux attach-session -t zc-claude-a1b2c3d4 实时查看进度。

场景二：SSH 远程访问

如果配置了 ssh_host，返回信息会包含 SSH attach 命令：

SSH attach: ssh -t dev.example.com tmux attach-session -t zc-claude-a1b2c3d4

这适合在服务器上运行时，允许团队成员通过 SSH 远程查看任务进度。

场景三：Slack 进度推送

如果传入了 slack_channel 参数（需要启动 Slack 频道支持），Claude Code 的 --hook-url 端点会将工具执行事件推送到指定 Slack 频道：

Slack channel: C123ABC456 (progress updates enabled)

手动使用 tmux 与 ZeroClaw 配合

除了 claude_code_runner，你也可以手动用 tmux 管理 ZeroClaw 自身：

在 tmux 中启动 ZeroClaw daemon：

tmux new-session -d -s zeroclaw 'zeroclaw daemon'

这样 daemon 会在后台运行，断开 SSH 也不会退出。查看 daemon 日志：

tmux attach-session -t zeroclaw

多窗口布局：

# 创建一个新会话，三个窗口
tmux new-session -d -s zeroclaw -n daemon 'zeroclaw daemon'
tmux new-window -t zeroclaw -n logs 'tail -f ~/.zeroclaw/logs/zeroclaw.log'
tmux new-window -t zeroclaw -n shell 'zeroclaw agent -a dev'
tmux attach-session -t zeroclaw

与 Agent 交互时保持上下文：

tmux new-session -d -s agent-session 'zeroclaw agent -a dev'
tmux attach-session -t agent-session

不安全命令隔离

tmux 会话中的命令不经过 ZeroClaw ShellTool 的安全门控——因为它们是在 tmux 中直接运行的，绕过了 SecurityPolicy.validate_command_execution()。claude_code_runner 工具本身仍受安全策略控制（只读模式拒绝、限速、工作目录校验），但一旦启动，会话内执行的命令完全取决于 Claude Code 自身的权限。

因此 tmux 会话适合在 受信任的环境（YOLO 模式或开发机）中使用 claude_code_runner。

启动与运行

命令	说明
`zeroclaw quickstart`	交互式快速配置
`zeroclaw daemon`	启动守护进程（含频道、调度器、监控）
`zeroclaw agent -a <alias> -m "消息"`	向指定 Agent 发送消息
`zerocode`	启动终端 TUI
`zeroclaw daemon --port 8080`	指定 HTTP 端口

配置管理

命令	说明
`zeroclaw config set <key> <value>`	设置配置项
`zeroclaw config get <key>`	读取配置项
`zeroclaw config schema`	查看完整配置 schema
`zeroclaw doctor traces --contains "retry"`	查询重试日志