ZeroClaw 使用方式与启动指南

1. 先给结论：最常见的三种启动方式

目标	推荐命令	说明
先把项目跑起来并完成配置	`zeroclaw onboard`	首次使用的首选路径
只启动控制平面和 Web 控制台	`zeroclaw gateway`	会提供 Web API、WebSocket、Dashboard、Webhook
启动完整长期运行态	`zeroclaw daemon`	会拉起 gateway、channels、scheduler、heartbeat

如果你只想在当前仓库里本地体验，不一定非要先全局安装，也可以直接：

powershell 复制代码

cargo run --release -- onboard
cargo run --release -- gateway

2. 运行前需要什么

通用依赖

Rust stable 工具链
Git

仅在某些场景需要

依赖	什么时候需要
Node.js + npm	需要从源码构建 Web 控制台，或 `web/dist` 过期/缺失时
Visual Studio Build Tools	Windows 上做源码构建时
Docker	想用容器启动
各消息平台 Token / API Key	想接入 Telegram、Slack、Discord、WhatsApp 等时
各家模型凭证	想真正调用 LLM 时

3. 当前仓库下的推荐启动路径

你当前仓库位置是：

text 复制代码

D:\longxia\zeroclaw

3.1 Windows / PowerShell 下直接从源码运行

powershell 复制代码

cd D:\longxia\zeroclaw
cargo build --release --locked
cargo install --path . --force --locked
zeroclaw onboard
zeroclaw gateway

配置完成后，还可以这样用：

powershell 复制代码

zeroclaw agent -m "你好，介绍一下你自己"
zeroclaw status
zeroclaw doctor
zeroclaw daemon

3.2 不做全局安装，直接运行仓库里的二进制

powershell 复制代码

cd D:\longxia\zeroclaw
cargo run --release -- onboard
cargo run --release -- gateway
cargo run --release -- agent -m "你好"

3.3 Windows 的脚本化入口

仓库还提供了：

cmd 复制代码

setup.bat

它更偏向 Windows 用户的一键安装/构建路径。

4. 首次使用流程

第一步：初始化

推荐执行：

bash 复制代码

zeroclaw onboard

从 src/main.rs 和 src/onboard/ 的实现看，onboard 会根据当前环境自动选择：

交互式向导
快速脚本模式
TUI onboarding

你也可以显式指定：

bash 复制代码

zeroclaw onboard --quick --api-key "sk-..." --provider openrouter
zeroclaw onboard --tui
zeroclaw onboard --channels-only
zeroclaw onboard --reinit

第二步：启动控制面

bash 复制代码

zeroclaw gateway

Gateway 启动后主要提供：

Dashboard
REST API
WebSocket chat
SSE event stream
Pairing
Webhook 接口

第三步：开始使用助手

bash 复制代码

zeroclaw agent
zeroclaw agent -m "帮我总结今天的日志"

第四步：如需长期运行，切换到 daemon

bash 复制代码

zeroclaw daemon

5. 配置与工作目录如何解析

根据 docs/reference/api/config-reference.md 和 src/config/schema.rs，配置解析优先级大致为：

ZEROCLAW_WORKSPACE
已持久化的 active workspace 标记
默认 ~/.zeroclaw/config.toml

默认情况下，核心配置与数据会落在用户目录下的 .zeroclaw。

重要配置项

最值得先关注的几个配置分组：

配置段	作用
顶层 `default_provider` / `default_model`	决定默认模型后端
`[gateway]`	控制 Web/API 监听地址、配对、限流
`[channels_config]`	控制外部消息渠道
`[memory]`	记忆后端、检索与快照
`[autonomy]` / `[security]`	安全级别、审批、OTP、E-stop、沙箱
`[cron]` / `[scheduler]`	定时任务和轮询
`[skills]`	技能加载
`[runtime]`	native / docker 运行时

6. 默认行为要点

6.1 Gateway 默认值

从 src/config/schema.rs 看，核心默认值是：

port = 42617
host = "127.0.0.1"
require_pairing = true
allow_public_bind = false

这意味着源码默认更偏向本地安全模式。

6.2 容器和开发模板不完全一样

dev/config.template.toml 和 Docker 模板里为了容器使用，会改成类似：

host = "[::]"
allow_public_bind = true
require_pairing = false

这说明：

"源码默认"
"容器模板默认"

是两套不同的运行姿态，使用时不要混淆。

6.3 Agent 默认行为

从 AgentConfig 默认值可看出：

compact_context = true
max_tool_iterations = 10
max_history_messages = 50
parallel_tools = false
tool_dispatcher = "auto"

适合先求稳，再逐步调大能力。

6.4 Memory 默认行为

从 MemoryConfig 默认值可看出：

backend = "sqlite"
auto_save = true
默认启用 hygiene
embedding provider 默认是 "none"

也就是说，默认更像"有结构化长期记忆，但不强依赖向量服务"。

7. 常见运行方式

7.1 只做本地 CLI 助手

bash 复制代码

zeroclaw onboard
zeroclaw agent

适合单机、命令行体验。

7.2 需要 Web 控制台

bash 复制代码

zeroclaw onboard
zeroclaw gateway

然后访问 Gateway 提供的 Dashboard。

7.3 需要长期在线、多渠道运行

bash 复制代码

zeroclaw onboard
zeroclaw daemon

适合真正当作个人 AI 助手常驻。

7.4 只启动消息渠道

bash 复制代码

zeroclaw channel start

这个更像运行消息入口，不等于完整控制面。

7.5 只做健康检查或诊断

bash 复制代码

zeroclaw status
zeroclaw doctor
zeroclaw doctor models

7.6 使用桌面端

Tauri 桌面端依赖本地 Gateway。

这意味着正确理解是：

先启动 Gateway
再启动桌面伴侣程序

因为 apps/tauri/tauri.conf.json 明确把前端地址指向了：

text 复制代码

http://127.0.0.1:42617/_app/

8. Docker 启动方式

8.1 最简单

bash 复制代码

docker compose up -d

docker-compose.yml 已经定义了：

镜像
环境变量
数据卷
端口映射
健康检查

8.2 你需要知道的容器默认点

数据卷：zeroclaw-data
默认暴露端口：42617
健康检查命令：zeroclaw status --format=exit-code

8.3 容器适合什么

想快速部署
想和宿主系统隔离
想更方便迁移数据卷

9. Web 控制台如何构建

这个项目的前端不是单独部署为 Node 服务，而是：

build.rs 检查 web/dist
如果 npm 可用且前端资源过期，会尝试自动执行：
- npm ci
- npm run build
编译后的资源通过 rust-embed 嵌入到 Rust 二进制
Gateway 在 /_app/* 下提供静态文件

如果你发现 Dashboard 打不开，最直接的修复路径是：

bash 复制代码

cd web
npm ci
npm run build
cd ..
cargo build --release --locked

10. 开发者常用命令

按 AGENTS.md 和仓库脚本，最重要的验证命令是：

bash 复制代码

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test

完整本地 CI：

bash 复制代码

./dev/ci.sh all

快捷命令也可以走：

bash 复制代码

just fmt-check
just lint
just test

11. 日常使用建议

如果你是第一次接触这个项目

推荐顺序：

zeroclaw onboard
zeroclaw gateway
打开 Dashboard
zeroclaw agent -m "你好"
再考虑接入消息平台、调度和外设

如果你是开发者

推荐顺序：

看 src/main.rs
看 src/config/schema.rs
看 src/agent/
看 src/providers/、src/tools/、src/channels/
最后看 src/gateway/ 和 web/

如果你要长期部署

推荐优先：

daemon
service install
status / doctor
成本限制
pairing / OTP / sandbox

12. 一句话启动建议

如果你现在就要把这个项目用起来，最现实的命令序列是：

powershell 复制代码

cd D:\longxia\zeroclaw
cargo build --release --locked
cargo run --release -- onboard
cargo run --release -- gateway

如果想让它变成长期在线的完整助手，则把最后一步改成：

powershell 复制代码

cargo run --release -- daemon