第一章 · SETUP & DEPLOYMENT

搭建 · 部署 · 使用

从零开始安装 zeroclaw，配置 API Key，选择合适的运行模式，以及通过 Docker 或 WASM 插件扩展功能。本页涵盖所有平台的安装方法和完整的配置参考。

📋 系统要求

🦀 Rust（源码构建） stable ≥ 1.75

💻 操作系统 Linux · macOS · Windows

💾 磁盘空间 ~10 MB

🔑 API Key 至少一个 LLM 提供商

ℹ️

无需 Rust 也可使用。 如果只想运行 zeroclaw，直接下载预编译二进制即可。仅在需要从源码构建或开发插件时才需要 Rust 工具链。

⬇️ 安装方式

# 从 crates.io 安装（推荐）
cargo install zeroclaw

# 验证安装
zeroclaw --version

# macOS Apple Silicon (aarch64)
curl -fsSL https://releases.zeroclaw.dev/latest/zeroclaw-aarch64-apple-darwin.tar.gz | tar xz
sudo mv zeroclaw /usr/local/bin/

# macOS Intel (x86_64)
curl -fsSL https://releases.zeroclaw.dev/latest/zeroclaw-x86_64-apple-darwin.tar.gz | tar xz
sudo mv zeroclaw /usr/local/bin/

# Linux x86_64
curl -fsSL https://releases.zeroclaw.dev/latest/zeroclaw-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv zeroclaw /usr/local/bin/

# 验证
zeroclaw --version

# 添加 tap 并安装
brew install zeroclaw-labs/tap/zeroclaw

# 升级到最新版本
brew upgrade zeroclaw

# 验证安装
zeroclaw --version

# Windows Package Manager (winget)
winget install zeroclaw-labs.zeroclaw

# 或使用 Scoop
scoop bucket add zeroclaw https://github.com/zeroclaw-labs/scoop-bucket
scoop install zeroclaw

# 验证 (PowerShell)
zeroclaw --version

# 克隆仓库
git clone https://github.com/zeroclaw-labs/zeroclaw
cd zeroclaw

# Release 构建（推荐）
cargo build --release

# 安装到 PATH
sudo cp target/release/zeroclaw /usr/local/bin/

# 或直接运行
./target/release/zeroclaw --version

🔑 API Key 配置

zeroclaw 支持两种方式配置 LLM API Key：交互式引导或直接设置环境变量。

方式一：交互式初始化

# 启动交互式认证配置向导
zeroclaw auth

# 按提示选择提供商并输入 API Key
? Select LLM provider:
  ❯ Anthropic
    OpenAI
    Google Gemini
    AWS Bedrock
    ... (more)

? Enter your Anthropic API key: sk-ant-...

方式二：环境变量

# Anthropic Claude（推荐默认提供商）
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Google Gemini
export GOOGLE_API_KEY=AIza...

# 可同时配置多个，zeroclaw 根据配置自动选择
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_API_KEY=AIza...

⚙️ 配置文件详解

配置文件位于 ~/.config/zeroclaw/config.toml，首次运行 zeroclaw auth 会自动创建。

# ~/.config/zeroclaw/config.toml

[agent]
# 默认 LLM 提供商
default_provider = "anthropic"
# 默认模型（可被 --model 命令行参数覆盖）
default_model = "claude-sonnet-4-5"
# 最大 token 数
max_tokens = 8192

[tools]
# 是否允许执行 shell 命令
allow_shell = true
# shell 执行超时（秒）
shell_timeout = 30
# 允许访问的文件系统路径（沙箱白名单）
allowed_paths = ["/home/user/projects", "/tmp"]

[plugins]
# 已启用的 WASM 插件列表
enabled = ["wasm-plugin-name"]

[safety]
# 审批模式: auto（自动）/ confirm（确认）/ strict（严格）
approval_mode = "auto"
# 是否启用 OS 级别沙箱
sandbox = true

[gateway]
# Gateway 模式默认监听地址
bind = "127.0.0.1:8080"
# 最大并发 Agent 数量
max_sessions = 50

🚀 三种运行模式

💬 Chat 模式

交互式 TUI 对话。单进程、阻塞 I/O，适合个人开发使用。每次运行对应一个会话，退出后会话持久化到 SQLite。

🌐 Gateway 模式

HTTP + WebSocket 服务器，多客户端并发，基于 tokio 异步运行时。适合作为应用后端 API 或 MCP 协议端点。

👻 Daemon 模式

后台常驻进程，支持 systemd / launchd 托管，Webhook 触发任务，SOP 自动化执行。适合无人值守的自治 Agent 场景。

Chat 模式

# 直接启动交互式对话（默认模式）
zeroclaw

# 指定模型
zeroclaw --model claude-opus-4-5

# 严格审批模式（每次工具调用都需确认）
zeroclaw --approval strict

# 无 TUI，纯 stdout 输出（适合脚本）
zeroclaw --headless

Gateway 模式

# 本地监听 8080
zeroclaw gateway --port 8080

# 监听所有网卡（生产部署）
zeroclaw gateway --bind 0.0.0.0:8080

# 指定最大并发会话数
zeroclaw gateway --bind 0.0.0.0:8080 --max-sessions 100

# 测试 API
curl -X POST http://localhost:8080/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, zeroclaw!"}'

Daemon 模式

# 启动后台 daemon
zeroclaw daemon start

# 查看 daemon 状态
zeroclaw daemon status

# 停止 daemon
zeroclaw daemon stop

# 查看 daemon 日志
zeroclaw daemon logs

# 以 systemd 服务形式安装
zeroclaw daemon install --systemd

🐳 Docker 部署

zeroclaw 提供官方 Docker 镜像，适合在容器化环境中以 Gateway 模式运行。

docker-compose.yml

version: '3.8'
services:
  zeroclaw:
    image: zeroclaw/zeroclaw:latest
    ports:
      - "8080:8080"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./config:/root/.config/zeroclaw
      - zeroclaw-data:/data
    command: gateway --bind 0.0.0.0:8080
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  zeroclaw-data:

启动命令

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f zeroclaw

# 直接运行（不用 compose）
docker run -d \
  -p 8080:8080 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v $(pwd)/config:/root/.config/zeroclaw \
  zeroclaw/zeroclaw:latest \
  gateway --bind 0.0.0.0:8080

⚠️

沙箱注意事项： 在 Docker 容器中，OS 级别沙箱（Landlock/Bubblewrap）默认可用。若容器运行时限制了权限，可在配置文件中设置 sandbox = false 或使用 --no-sandbox 标志，但这会降低安全隔离级别。

🧩 WASM 插件管理

zeroclaw 通过 WebAssembly 插件扩展工具集。插件以 .wasm 文件形式分发，运行在受限沙箱中，通过 JSON-RPC 2.0 与主进程通信。

插件生命周期管理

# 安装本地 .wasm 文件
zeroclaw plugin install my-plugin.wasm

# 从 registry 安装（远程）
zeroclaw plugin install zeroclaw-labs/web-scraper

# 列出已安装插件
zeroclaw plugin list

# 启用插件
zeroclaw plugin enable my-plugin

# 禁用插件（不删除）
zeroclaw plugin disable my-plugin

# 卸载插件
zeroclaw plugin remove my-plugin

# 查看插件详情（暴露的工具、权限要求）
zeroclaw plugin info my-plugin

在配置文件中预启用插件

# ~/.config/zeroclaw/config.toml
[plugins]
enabled = ["web-scraper", "image-analyzer", "db-connector"]

🏳️ 常用 CLI 参数

参数	类型	说明	示例
--model	string	覆盖配置文件中的默认 LLM 模型	--model gpt-4o
--approval	enum	安全审批级别：auto / confirm / strict	--approval confirm
--no-sandbox	flag	禁用 OS 沙箱隔离（不推荐生产环境）	--no-sandbox
--port	number	Gateway 模式监听端口	--port 9090
--bind	string	Gateway 模式完整监听地址	--bind 0.0.0.0:8080
--headless	flag	禁用 TUI，仅输出到 stdout	--headless
--config	path	指定自定义配置文件路径	--config ./my.toml
--provider	string	指定 LLM 提供商（覆盖默认）	--provider openai
--verbose	flag	输出详细日志，包括工具调用详情	--verbose
--version	flag	显示版本信息	--version

⚡ 完整初始化流程

安装 zeroclaw

选择上述任意安装方式，推荐 cargo install zeroclaw。

配置 API Key

运行 zeroclaw auth 或设置环境变量 ANTHROPIC_API_KEY。

（可选）编辑配置文件

修改 ~/.config/zeroclaw/config.toml 设置默认模型、沙箱策略等。

启动

直接运行 zeroclaw 进入 Chat 模式，或用 zeroclaw gateway 启动 API 服务器。

（可选）安装 WASM 插件

通过 zeroclaw plugin install 扩展工具集。