ZeroClaw：个人 AI 助理运行时

项目简介

ZeroClaw 是一个 agent runtime（代理运行时）：一个可以自行配置并运行的单文件 Rust 二进制程序。你可以完全掌控这个代理，也掌控数据和运行它的机器。

它连接 LLM 供应商（Anthropic、OpenAI、Ollama 以及约 20 家其他供应商），通过 30+ 个渠道（Discord、Telegram、Matrix、邮件、语音、webhook、你自己的 CLI）触达外部，并通过工具（shell、浏览器、HTTP、硬件、自定义 MCP server）执行操作。所有内容都在你的机器上、用你的密钥、在你的工作区里运行。

主要功能

• 多渠道：无论来自 Discord、Telegram、Matrix、邮件、webhook 还是 CLI，所有入站消息都会交给同一个 agent loop 处理，一个代理即可跨所有已配置渠道应答。
• 对供应商不敏感：模型供应商可插拔，可配置 Anthropic、OpenAI、本地 Ollama 或任意 OpenAI 兼容端点；回退链与路由可在供应商不稳定时保持代理继续运行。
• 安全优先，并提供多种放宽选项：默认自主级别为 supervised，中风险操作需要批准，高风险操作被阻止；提供工作区边界、命令策略、操作系统级沙箱（Landlock、Bubblewrap、Seatbelt、Docker），并为每个动作生成加密的工具收据；可信开发环境可使用 YOLO 模式。
• 可连接硬件：通过 Peripheral trait 支持 Raspberry Pi、STM32、Arduino、ESP32 上的 GPIO、I2C、SPI、USB。
• Gateway 与仪表盘：为客户端提供 HTTP 与 WebSocket gateway，并附带 Web 仪表盘，用于聊天、浏览记忆、编辑配置、管理 cron 和检查工具。
• SOP 引擎：事件触发的标准作业流程（MQTT、webhook、cron、外设），带审批环节和可恢复运行。
• ACP：通过 Agent Client Protocol（stdio 上的 JSON-RPC 2.0）集成 IDE 或编辑器。

安装与使用

Unix（推荐）：

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh
"${CARGO_HOME:-$HOME/.cargo}/bin/zeroclaw" quickstart

Windows 推荐使用 预构建 PowerShell 安装路径。

快速开始：

zeroclaw quickstart               # 一次性设置：选择供应商，写入可用配置
zeroclaw agent -a <alias>         # 使用 [agents.<alias>] 条目进行交互式聊天
zeroclaw service install          # 注册为 systemd / launchctl / Windows Service
zeroclaw service start            # 在后台常驻运行

配置是一个 TOML 文件，位于 ~/.zeroclaw/config.toml。V3 配置至少包含四个段头（形如 <type>.<alias>）：一个供应商条目、一个引用它的 agent，以及一个供 agent 判断风险的风险配置。

使用 OpenAI Codex 订阅认证时，Quickstart 可代为写入供应商条目：

zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json
zeroclaw quickstart --model-provider openai-codex --model gpt-5.4

[providers.models.openai.coding]   # type = openai; alias = coding（自行选择）
model = "gpt-5.4"
wire_api = "responses"
requires_openai_auth = true

然后在 agent 中用 model_provider = "openai.<alias>" 指向它。

注意事项

• 常规 OpenAI Codex 订阅认证使用已保存的认证配置，不会在供应商条目上设置 api_key。
• Claude Max setup-token 认证放在 Anthropic 的标准位置：运行 claude setup-token，在 Quickstart 中选择 setup_token，粘贴生成的 token。
• 只有特意指向自定义 OpenAI 兼容网关或端点时，才在 [providers.models.openai.<alias>] 上设置 api_key 或 uri。
• 若出现 provider streaming failed, falling back to non-streaming chat，说明 ZeroClaw 正以非流式模式重试同一请求；修改供应商配置前先检查 zeroclaw auth status。
• 平台说明见 Linux、macOS、Windows、FreeBSD、NixOS、Docker。
• 安全漏洞请勿提交公开 issue，可发邮件至 [email protected]。

---

本作品整理自 GitHub 开源项目 zeroclaw-labs/zeroclaw，原作者 @zeroclaw-labs，许可证 Apache-2.0。中文介绍由 AI 根据项目 README 整理，以原仓库为准。