OpenClaw不安全，Rust写的ZeroClaw给出满意答案

@TOC## 一、项目简介

ZeroClaw 是一款轻量、可组合的自主 AI 助手运行时，用 Rust 编写，单二进制部署，面向智能体工作流。它抽象了模型、工具、记忆与执行层，实现「一次构建、随处运行」。

核心特点

特点	说明
轻量	常见 CLI/status 仅需数 MB 内存，发布版二进制约 8.8MB
低成本	面向约 10 美元级硬件与小型云实例，无重量级运行时依赖
冷启动快	单二进制 Rust 运行时，命令与守护进程启动接近「秒开」
可移植	同一套流程覆盖 ARM、x86、RISC-V，Provider/Channel/Tool 可替换
安全默认	配对鉴权、沙箱、显式 allowlist、工作区作用域约束

基准对比（参考）

项目	语言	内存	启动时间	成本
OpenClaw	TypeScript	>1GB	>500s	Mac Mini $599
ZeroClaw	Rust	<5MB	<10ms	约 $10 硬件

二、环境要求

2.1 必需环境

Linux / macOS：

构建工具
- Debian/Ubuntu：sudo apt install build-essential pkg-config
- Fedora/RHEL：sudo dnf group install development-tools && sudo dnf install pkg-config
- macOS：xcode-select --install

Rust 工具链

bash 复制代码

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustc --version
cargo --version

Windows：

Visual Studio Build Tools（含「使用 C++ 的桌面开发」工作负载）
Rust：winget install Rustlang.Rustup，然后 rustup default stable

2.2 编译资源（从源码构建时）

资源	最低	推荐
RAM + swap	2 GB	4 GB+
可用磁盘	6 GB	10 GB+

资源不足时可优先使用预编译二进制（见下文安装方式）。

2.3 可选

Docker ：仅在使用 runtime.kind = "docker" 沙箱运行时需要。

三、安装方式

方式 1：Homebrew（macOS / Linuxbrew）

bash 复制代码

brew install zeroclaw

方式 2：一键脚本（推荐）

bash 复制代码

# 克隆后本地执行
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

脚本默认会：cargo build --release --locked 然后 cargo install --path . --force --locked。

常用参数：

参数	说明
`--install-system-deps --install-rust`	新机：安装系统依赖与 Rust
`--prefer-prebuilt`	优先下载预编译二进制，失败再源码构建
`--prebuilt-only`	仅使用预编译，不构建源码
`--onboard --api-key "sk-..." --provider openrouter`	安装后顺带做非交互式配置
`--docker`	Docker 容器内构建与安装

查看全部选项：./install.sh --help

方式 3：远程一行命令（需自行评估安全）

bash 复制代码

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

方式 4：预编译二进制

支持平台：Linux（x86_64 / aarch64 / armv7）、macOS（x86_64 / aarch64）、Windows（x86_64）。

示例（ARM64 Linux）：

bash 复制代码

curl -fsSLO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-aarch64-unknown-linux-gnu.tar.gz
tar xzf zeroclaw-aarch64-unknown-linux-gnu.tar.gz
install -m 0755 zeroclaw "$HOME/.cargo/bin/zeroclaw"

请将 ~/.cargo/bin 加入 PATH。

方式 5：本地源码安装（无全局 install）

bash 复制代码

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo build --release --locked
cargo install --path . --force --locked
export PATH="$HOME/.cargo/bin:$PATH"

之后所有命令用 zeroclaw 即可；开发时也可用 cargo run --release -- <子命令> 代替。

四、首次配置（Onboard）

配置文件会生成在 ~/.zeroclaw/config.toml。

4.1 快速配置（无交互）

bash 复制代码

zeroclaw onboard --api-key sk-... --provider openrouter
# 可选指定模型
zeroclaw onboard --api-key sk-... --provider openrouter --model "openrouter/auto"

4.2 交互式向导

bash 复制代码

zeroclaw onboard --interactive

4.3 已有配置时

已有 config.toml 时，非交互 onboard 会拒绝执行，除非加 --force（会覆盖）。
仅更新通道/allowlist：zeroclaw onboard --channels-only
完全重新初始化：zeroclaw onboard --reinit --interactive（会先备份再新建配置）

4.4 订阅制鉴权（OpenAI Codex / Claude Code）

配置与密钥：~/.zeroclaw/auth-profiles.json、~/.zeroclaw/.secret_key
Profile 格式：<provider>:<profile_name>，例如 openai-codex:work

OpenAI Codex（ChatGPT 订阅）：

bash 复制代码

# 无头/服务器推荐
zeroclaw auth login --provider openai-codex --device-code

# 浏览器流程
zeroclaw auth login --provider openai-codex --profile default
zeroclaw auth paste-redirect --provider openai-codex --profile default

zeroclaw auth status
zeroclaw auth refresh --provider openai-codex --profile default
zeroclaw auth use --provider openai-codex --profile work

Claude Code / Anthropic：

bash 复制代码

zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
# 或
zeroclaw auth setup-token --provider anthropic --profile default

使用订阅鉴权运行 agent：

bash 复制代码

zeroclaw agent --provider openai-codex -m "hello"
zeroclaw agent --provider anthropic -m "hello"

五、试用流程

5.1 检查状态

bash 复制代码

zeroclaw status
zeroclaw auth status    # 若用了订阅鉴权
zeroclaw providers      # 查看支持的 Provider

5.2 单次对话

bash 复制代码

zeroclaw agent -m "Hello, ZeroClaw!"

5.3 交互式对话

bash 复制代码

zeroclaw agent

可指定 provider/model/温度等：

bash 复制代码

zeroclaw agent --provider openrouter --model "anthropic/claude-sonnet-4-6" --temperature 0.7

5.4 启动网关（Webhook 服务）

bash 复制代码

zeroclaw gateway                    # 默认 127.0.0.1:42617
zeroclaw gateway --port 0           # 随机端口（更安全）

5.5 启动完整自主运行时（网关 + 通道 + 可选心跳/调度）

bash 复制代码

zeroclaw daemon

Telegram、Discord、Slack 等通道需在 daemon 运行时可收到消息。

5.6 诊断与通道

bash 复制代码

zeroclaw doctor              # 系统诊断
zeroclaw channel doctor      # 通道健康
zeroclaw channel list        # 通道列表
zeroclaw channel bind-telegram 123456789   # 将 Telegram 用户 ID 加入 allowlist
zeroclaw integrations info Telegram       # 查看 Telegram 集成说明

5.7 后台服务（Linux）

systemd（用户级，默认）：

bash 复制代码

zeroclaw service install
zeroclaw service start
zeroclaw service status
zeroclaw service restart

Alpine OpenRC（需 sudo）：

bash 复制代码

sudo zeroclaw service install
sudo rc-update add zeroclaw default
sudo rc-service zeroclaw start

5.8 Web 界面

核心产品 ：ZeroClaw 官方主打 CLI + Gateway API ，没有随二进制一起提供的内置 Web 管理界面。日常使用方式是终端命令 zeroclaw agent、zeroclaw gateway 等，以及通过 HTTP 调用 Gateway 的 /webhook、/pair 等接口。

官方仓库内的 Web 前端 ：仓库里有 web/ 目录，是一个独立的 React + Vite + Tailwind 前端项目（zeroclaw-web），需在克隆后的项目中单独启动，例如：

bash 复制代码

cd zeroclaw/web
npm install
npm run dev

该前端是否提供完整配置/对话界面以官方文档或 web/ 内 README 为准；主 README 未将其作为默认使用方式。

第三方 Web/桌面 UI ：社区有 ZeroClaw UI 等第三方项目（例如 nicholasbester/zeroclaw-ui），提供桌面端仪表盘、配置编辑、技能管理、内置聊天等，可与本地 ZeroClaw 配合使用。此类项目非官方维护，使用前请自行评估安全与兼容性。

结论：若你希望用「网页」和 ZeroClaw 交互，可以：

1）自建前端调用 zeroclaw gateway 的 /webhook（需先完成 /pair 获取 token）；

2）使用仓库内 web/ 前端（若有）；

3）使用社区 ZeroClaw UI 等第三方界面。

六、常用命令速查

命令	用途
`zeroclaw onboard`	快速/交互式初始化配置
`zeroclaw agent`	交互或单条消息对话
`zeroclaw agent -m "..."`	单次提问
`zeroclaw gateway`	启动 Webhook 网关
`zeroclaw daemon`	启动完整运行时
`zeroclaw status`	查看配置与状态
`zeroclaw doctor`	运行诊断
`zeroclaw channel list/start/doctor`	通道管理
`zeroclaw channel bind-telegram <ID>`	绑定 Telegram 身份到 allowlist
`zeroclaw service install/start/stop/status`	服务管理
`zeroclaw cron list/add/remove`	定时任务
`zeroclaw skills list/install/remove`	技能列表与安装
`zeroclaw migrate openclaw [--dry-run]`	从 OpenClaw 迁移记忆（可先试跑）
`zeroclaw completions bash/zsh`	生成 Shell 补全

更多子命令：zeroclaw --help、zeroclaw <命令> --help。

七、配置要点

配置文件：~/.zeroclaw/config.toml（由 onboard 创建）。

7.1 基础示例

toml 复制代码

api_key = "sk-..."
default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4-6"
default_temperature = 0.7

# 自定义 OpenAI 兼容端点
# default_provider = "custom:https://your-api.com"

# 自定义 Anthropic 兼容端点
# default_provider = "anthropic-custom:https://your-api.com"

7.2 记忆（Memory）

toml 复制代码

[memory]
backend = "sqlite"             # sqlite | lucid | postgres | markdown | none
auto_save = true
embedding_provider = "none"    # none | openai | custom:https://...
vector_weight = 0.7
keyword_weight = 0.3

backend = "none" 表示不持久化记忆。

7.3 网关与安全

toml 复制代码

[gateway]
port = 42617
host = "127.0.0.1"
require_pairing = true
allow_public_bind = false

默认只监听本机，不对外暴露。
对外访问需配合隧道（Tailscale、Cloudflare、ngrok 等）。

7.4 自治与沙箱

toml 复制代码

[autonomy]
level = "supervised"           # readonly | supervised | full
workspace_only = true
allowed_commands = ["git", "npm", "cargo", "ls", "cat", "grep"]
forbidden_paths = ["/etc", "/root", "/proc", "/sys", "~/.ssh", "~/.gnupg", "~/.aws"]

7.5 通道 Allowlist（重要）

空列表 []：拒绝所有入站消息（默认安全）。
"*"：允许所有（仅建议临时测试用）。
其他：按配置做精确匹配（如 Telegram 用户 ID、Discord 用户 ID 等）。

Telegram 推荐：在配置中 allowlist 自己的 @username（不带 @）或数字用户 ID；不确定时可先发一条消息给机器人，看日志中的 sender 身份，再执行 zeroclaw channel bind-telegram <ID> 或写入配置后 zeroclaw onboard --channels-only。

7.6 本地/远程模型示例

Ollama 本地： 不设 api_url，本地运行 ollama serve，模型如 llama3.2。

Ollama 远程：

toml 复制代码

default_provider = "ollama"
default_model = "qwen3:cloud"
api_url = "https://ollama.com"
api_key = "ollama_api_key_here"

llama.cpp 服务：

toml 复制代码

default_provider = "llamacpp"
api_url = "http://127.0.0.1:8033/v1"
default_model = "ggml-org/gpt-oss-20b-GGUF"

vLLM：

toml 复制代码

default_provider = "vllm"
default_model = "meta-llama/Llama-3.1-8B-Instruct"

八、Gateway API 简要

端点	方法	认证	说明
`/health`	GET	无	健康检查
`/pair`	POST	X-Pairing-Code	用一次性码换 Bearer token
`/webhook`	POST	Authorization: Bearer <token>	发送消息 `{"message": "你的提示"}`
`/whatsapp`	GET/POST	见 Meta 文档	WhatsApp Webhook 校验与收消息

九、故障排查与文档

9.1 常见问题

安装/编译失败 ：确认 Rust 与系统构建工具已装；Linux 若遇 OpenSSL 相关错误，可尝试：
bash 复制代码
```
cargo build --release --locked
cargo install --path . --force --locked
```
通道收不到消息 ：确认 zeroclaw daemon 或 zeroclaw channel start 已运行；检查对应通道的 allowlist 是否包含你的身份。
配置不生效：网关/通道运行时会对部分配置热更新（如 default_provider、default_model、api_key 等），下次入站消息生效；其余修改需重启服务。

9.2 官方文档入口

英文主文档：README
中文简介：README.zh-CN
文档总览：仓库内 docs/README.md
命令参考：docs/reference/cli/commands-reference.md
配置参考：docs/reference/api/config-reference.md
Provider 参考：docs/reference/api/providers-reference.md
通道参考：docs/reference/api/channels-reference.md
运维手册：docs/ops/operations-runbook.md
故障排查：docs/ops/troubleshooting.md

9.3 官方来源声明

唯一官方仓库 ：https://github.com/zeroclaw-labs/zeroclaw
官网：zeroclawlabs.ai
请勿信任 zeroclaw.org、zeroclaw.net 及其他未经验证的仓库/域名。

十、快速试用清单（复制即用）

bash 复制代码

# 1. 安装（任选其一）
brew install zeroclaw
# 或
git clone https://github.com/zeroclaw-labs/zeroclaw.git && cd zeroclaw && ./install.sh

# 2. 配置（替换成你的 API Key 和 provider）
zeroclaw onboard --api-key "sk-..." --provider openrouter

# 3. 检查
zeroclaw status

# 4. 对话
zeroclaw agent -m "用一句话介绍你自己"

# 5. 交互对话
zeroclaw agent