2026最新windows ZeroClaw 完整安装配置教程，使用QQ远程指挥claude干活

本文已收录到 AI编程一站式导航。本文链接：[03.9 2026 年最佳 AI 编码工具完全指南](code.ai80.vip/ai-tool-gui… 2026 年最佳 AI 编码工具完全指南) 强烈推荐：AI编程巴士网站：稳定纯净的ClaudeCode套餐供应；

最终效果:

目录

1. OpenClaw vs ZeroClaw 对比
2. 环境准备
3. 安装 Rust 工具链
4. 安装 Visual Studio Build Tools
5. 下载 ZeroClaw 源码
6. 编译 ZeroClaw
7. 初始配置（onboard）
8. 配置文件详解
9. 配置 QQ 机器人频道
10. 配置开机自启动
11. 常用命令速查
12. 已知问题与解决方案

1. OpenClaw vs ZeroClaw 对比

1.1 什么是 OpenClaw？

OpenClaw 是一款开源的 AI 自动化 Agent，可运行在本地机器上，获得对系统的完整控制权（键盘、鼠标、文件系统等），实现像人一样操作电脑。

1.2 什么是 ZeroClaw？

ZeroClaw 是用 Rust 编写的轻量级 AI Agent 框架，定位为 OpenClaw 的高性能替代品。二进制文件仅约 3.4 MB，启动时间不到 10ms，支持 23+ 种 AI 提供商。

1.3 核心差异对比

对比维度	OpenClaw	ZeroClaw
技术栈	Python / JavaScript	Rust
二进制大小	数百 MB	~3.4 MB
空闲内存占用	~394 MB	~7–8 MB
活跃时内存	高达 1.52 GB	极低
启动速度	慢（秒级）	< 10ms
最低硬件要求	推荐 Mac/高配 PC	树莓派零即可运行
跨平台支持	有限	ARM / x86 / RISC-V
外部依赖	LangChain 等大量依赖	零外部依赖
Provider 支持	有限	23+（含 Ollama 本地模型）
安全性	被批评为"安全噩梦"	沙箱、白名单、工作区隔离
内存迁移	—	支持从 OpenClaw 迁移

1.4 选择建议

• 追求轻量、低资源、稳定：选 ZeroClaw
• 需要可视化操作（控制鼠标键盘）：选 OpenClaw
• 内网/低配服务器部署：强烈推荐 ZeroClaw

2. 环境准备

2.1 前置要求检查

打开 Git Bash（推荐）或 PowerShell，依次运行以下命令确认环境：

# 检查 Git 是否已安装（必需）
git --version
# 期望输出：git version 2.x.x.windows.x

# 检查网络连通性
curl -s "https://api.github.com" | head -c 50

2.2 必需工具清单

工具	版本要求	用途
Git for Windows	2.x+	版本控制、提供 bash 环境
Rust (rustup)	1.92.0（项目要求）	编译 ZeroClaw 源码
Visual Studio Build Tools 2022	含 C++ 工作负载	MSVC 链接器（Rust 编译依赖）

⚠️ 重要：ZeroClaw 项目 rust-toolchain.toml 指定使用 Rust 1.92.0，安装时会自动下载对应版本。

3. 安装 Rust 工具链

Step 1：下载并安装 rustup

# 方法一：通过 sh 脚本安装（Git Bash 中执行）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup-init.sh
sh /tmp/rustup-init.sh -y --default-toolchain stable

安装完成后输出类似：

stable-x86_64-pc-windows-msvc installed - rustc 1.93.x
Rust is installed now. Great!

Step 2：验证安装

重新打开终端后执行：

export PATH="$HOME/.cargo/bin:$PATH"
rustc --version
cargo --version

⚠️ 注意：安装后必须重新打开终端，或手动执行 export PATH="$HOME/.cargo/bin:$PATH" 使环境变量生效。

4. 安装 Visual Studio Build Tools

ZeroClaw 使用 MSVC 工具链编译，需要 Microsoft 的 C++ 链接器 link.exe。

Step 1：下载安装程序

curl -L -o /tmp/vs_buildtools.exe "https://aka.ms/vs/17/release/vs_BuildTools.exe"

Step 2：静默安装（包含 C++ 工作负载）

"/tmp/vs_buildtools.exe" --quiet --wait --norestart \
  --add Microsoft.VisualStudio.Workload.VCTools \
  --includeRecommended

⏳ 此步骤需下载约 4–6 GB 文件，根据网速可能需要 10–30 分钟，请耐心等待。

Step 3：等待安装完成并验证

# 等待安装进程结束
while tasklist.exe 2>/dev/null | grep -q "vs_buildtools.exe"; do
  sleep 30
  echo "Still installing..."
done
echo "Done!"

# 验证安装路径
ls "/c/Program Files (x86)/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/"
# 期望输出：类似 14.44.35207 的版本目录

5. 下载 ZeroClaw 源码

由于网络环境限制，git clone 可能失败，使用 GitHub API 下载压缩包：

Step 1：通过 API 下载源码

curl -L \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/zeroclaw-labs/zeroclaw/zipball/main" \
  -o /tmp/zeroclaw.zip

Step 2：解压源码

cd /tmp && unzip -q zeroclaw.zip -d zeroclaw_src
# 查看解压目录名
ls zeroclaw_src/
# 输出类似：zeroclaw-labs-zeroclaw-xxxxxxx

Step 3：进入源码目录

cd /tmp/zeroclaw_src/zeroclaw-labs-zeroclaw-*/
ls
# 应看到：Cargo.toml  Cargo.lock  src/  rust-toolchain.toml 等

6. 编译 ZeroClaw

Step 1：将 MSVC 链接器加入 PATH

# 替换版本号为实际安装的版本
export PATH="/c/Program Files (x86)/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.44.35207/bin/Hostx64/x64:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"

Step 2：编译（使用项目指定工具链）

cargo +1.92.0-x86_64-pc-windows-msvc build --release --locked

⏳ 首次编译需下载并编译所有依赖，约需 5–10 分钟。

编译成功后输出：

Finished `release` profile [optimized] target(s) in 5m 02s

Step 3：安装到系统

cargo +1.92.0-x86_64-pc-windows-msvc install --path . --locked

Step 4：验证安装

zeroclaw --version
# 输出：zeroclaw 0.1.0

7. 初始配置（onboard）

7.1 使用自定义 Anthropic 兼容端点

如果使用标准 Anthropic API：

zeroclaw onboard --api-key "sk-ant-xxxx" --provider anthropic

如果使用自定义 Anthropic 兼容端点（如中转代理）：

zeroclaw onboard \
  --api-key "YOUR_API_KEY" \
  --provider "anthropic-custom:https://your-api-endpoint.com"

⚠️ 注意：onboard 自动选择的默认模型名格式为 anthropic/claude-sonnet-4.5， 需手动修改为端点实际支持的模型名（如 claude-sonnet-4-5-20250929），详见第 8 节。

7.2 其他 Provider 示例

# OpenRouter
zeroclaw onboard --api-key "sk-or-xxxx" --provider openrouter

# 本地 Ollama（无需 API Key）
zeroclaw onboard --provider ollama --model llama3.2

# OpenAI
zeroclaw onboard --api-key "sk-xxxx" --provider openai

7.3 测试连通性

export PATH="$HOME/.cargo/bin:$PATH"
zeroclaw agent -m "你好，请用中文回复一句话"

8. 配置文件详解

配置文件路径：C:\Users<用户名>.zeroclaw\config.toml

8.1 Provider 配置

api_key = "enc2:..."                               # 自动加密存储
default_provider = "anthropic-custom:https://your-endpoint.com"
default_model = "claude-sonnet-4-5-20250929"       # ⚠️ 需与端点支持的模型名一致
default_temperature = 0.7

8.2 Agent 行为配置

[agent]
compact_context = false        # false = 加载完整 workspace 文件（推荐）
max_tool_iterations = 50       # 单次任务最大工具调用次数（默认10太少）
max_history_messages = 100     # 保留对话历史条数
parallel_tools = true          # 并行工具调用（提升速度）
tool_dispatcher = "auto"

8.3 自治与安全配置

[autonomy]
level = "full"                 # readonly | supervised | full
workspace_only = false         # false = 可访问任意路径
allowed_commands = [           # 白名单，不含 rm/del/rmdir
    "*",
    "ls", "dir", "cat", "find", "grep", "echo", "pwd",
    "git", "cargo", "npm", "node", "python", "python3",
    "curl", "wget", "ssh", "scp",
    "mkdir", "cp", "mv", "touch",
    "docker", "kubectl",
    "powershell", "cmd", "bash",
    "tar", "zip", "unzip",
    "ping", "netstat", "ipconfig"
    # ... 按需添加，不加 rm/del/rmdir
]
forbidden_paths = []           # 空 = 无路径限制
max_actions_per_hour = 9999
max_cost_per_day_cents = 99999
require_approval_for_medium_risk = false
block_high_risk_commands = false

⚠️ 安全提示：生产环境建议设置 level = "supervised" 和合理的 allowed_commands 白名单。

8.4 HTTP 请求工具配置

[http_request]
enabled = true
allowed_domains = [
    "com", "org", "net", "io", "dev", "ai",
    "cn", "vip", "info", "edu", "gov",
    "tech", "app", "co", "me", "tv", "cc"
]
# 使用顶级域名匹配，如 "com" 可匹配所有 .com 域名
max_response_size = 10485760   # 10MB
timeout_secs = 30

⚠️ allowed_domains = [] 空列表不是全放行，而是报错。必须至少填一个域名或 TLD。

8.5 QQ 频道配置

[channels_config]
cli = true

[channels_config.qq]
app_id = "YOUR_QQ_APP_ID"
app_secret = "YOUR_QQ_APP_SECRET"
allowed_users = ["*"]          # "*" = 允许所有用户，或填具体 OpenID 白名单

8.6 Agent 身份与语言配置

编辑 C:\Users<用户名>.zeroclaw\workspace\SOUL.md，在 Communication 部分添加：

## Communication

**语言规则（最高优先级）：始终使用中文回答，无论用户用什么语言提问。代码、命令、专有名词除外。**

---

9. 配置 QQ 机器人频道

Step 1：注册 QQ 官方机器人

1. 访问 QQ 开放平台 登录

2. 创建应用 → 选择"机器人"类型

3. 在开放平台后台开启以下权限：

   • GROUP_AT_MESSAGE_CREATE（群组 @ 消息）
   • C2C_MESSAGE_CREATE（私聊消息）

4. 获取 AppID 和 AppSecret

Step 2：写入配置文件

编辑 ~/.zeroclaw/config.toml，在 [channels_config] 下添加：

[channels_config.qq]
app_id = "102860714"           # 替换为实际 AppID
app_secret = "YOUR_SECRET"     # 替换为实际 AppSecret
allowed_users = ["*"]

Step 3：测试频道连接

export PATH="$HOME/.cargo/bin:$PATH"
zeroclaw channel start

成功输出：

📡 Channels: qq
QQ: authenticating...      ✅
QQ: fetching gateway URL...✅
QQ: connected and identified ✅

✅ 无需 ngrok：QQ 官方 Bot 使用 WebSocket 长连接（本机主动连接 QQ 服务器），不需要公网入站端口。

---

10. 配置开机自启动

ZeroClaw 内置服务管理（zeroclaw service）不支持 Windows，使用任务计划程序代替：

Step 1：创建计划任务

在 PowerShell 中执行：

$action = New-ScheduledTaskAction `
    -Execute 'C:\Users<用户名>.cargo\bin\zeroclaw.exe' `
    -Argument 'daemon'

$trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME

$settings = New-ScheduledTaskSettingsSet `
    -ExecutionTimeLimit 0 `
    -RestartCount 3 `
    -RestartInterval (New-TimeSpan -Minutes 1) `
    -StartWhenAvailable

$principal = New-ScheduledTaskPrincipal `
    -UserId $env:USERNAME `
    -LogonType Interactive `
    -RunLevel Limited

Register-ScheduledTask `
    -TaskName 'ZeroClaw Daemon' `
    -Action $action `
    -Trigger $trigger `
    -Settings $settings `
    -Principal $principal `
    -Description 'ZeroClaw AI agent daemon' `
    -Force

Step 2：立即启动测试

Start-ScheduledTask -TaskName 'ZeroClaw Daemon'
Start-Sleep 3
Get-ScheduledTask -TaskName 'ZeroClaw Daemon' | Select-Object TaskName, State
# 期望输出：Running

Step 3：日常管理命令

# 查看运行状态
Get-ScheduledTask -TaskName 'ZeroClaw Daemon'

# 停止
Stop-ScheduledTask -TaskName 'ZeroClaw Daemon'

# 启动
Start-ScheduledTask -TaskName 'ZeroClaw Daemon'

# 卸载（取消开机启动）
Unregister-ScheduledTask -TaskName 'ZeroClaw Daemon' -Confirm:$false

---

11. 常用命令速查

# 单次对话
zeroclaw agent -m "你的问题"

# 启动频道监听（前台）
zeroclaw channel start

# 启动完整守护进程（含网关、调度器、心跳）
zeroclaw daemon

# 查看系统状态
zeroclaw status

# 查看频道健康状态
zeroclaw channel doctor

# 迁移 OpenClaw 数据
zeroclaw migrate openclaw --dry-run   # 预览
zeroclaw migrate openclaw             # 执行迁移

---

12. 已知问题与解决方案

问题 1：link.exe 报错，找到的是 GNU link 而非 MSVC link

现象：

error: linking with `link.exe` failed
link: extra operand '...'

原因： Git for Windows 的 link.exe 与 MSVC 的 link.exe 冲突。

解决： 将 MSVC 的 bin 目录加到 PATH 最前面：

export PATH="/c/Program Files (x86)/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.44.35207/bin/Hostx64/x64:$PATH"

---

问题 2：SSL 证书验证失败

现象： curl 访问某些 HTTPS 站点报错 SSL certificate problem

原因： Windows Schannel 证书库缺少 Let's Encrypt 根证书。

解决：

# 下载并导入 ISRG Root X1 证书
curl -sk -o /tmp/isrg-root-x1.crt "https://letsencrypt.org/certs/isrgrootx1.pem"

powershell.exe -Command "Import-Certificate \
  -FilePath 'C:\Users<用户名>\AppData\Local\Temp\isrg-root-x1.crt' \
  -CertStoreLocation 'Cert:\CurrentUser\Root'"

---

问题 3：模型名格式错误，API 返回 upstream_error

现象： Agent 报错，日志显示模型名为 anthropic/claude-sonnet-4.5

原因： onboard 自动生成的模型名格式与端点不匹配。

解决： 直接修改 ~/.zeroclaw/config.toml：

# 错误
default_model = "anthropic/claude-sonnet-4.5"

# 正确（根据实际端点支持的模型名）
default_model = "claude-sonnet-4-5-20250929"

问题 4：http_request 工具报错"no allowed_domains configured"

现象：

HTTP request tool is enabled but no allowed_domains are configured

原因： allowed_domains = [] 空列表不是"全放行"，而是报错。

解决： 填写顶级域名列表（支持后缀匹配）：

[http_request]
enabled = true
allowed_domains = ["com", "org", "net", "io", "dev", "ai", "cn", "vip"]

问题 5：QQ 频道回答质量远差于直接 agent 模式

现象： 通过 QQ 提问得到的回答简单，无法使用网络工具

原因： ZeroClaw 源码中 channel 模式的工具描述列表只有 8 个基础工具，缺少 http_request、cron 等工具，导致 AI 认为自己没有这些能力。

解决： 修改源码 src/channels/mod.rs，在 tool_descs 列表中补充缺失工具，然后重新编译：

# 编译
export PATH="/c/Program Files (x86)/Microsoft Visual Studio/2022/BuildTools/VC/Tools/MSVC/14.44.35207/bin/Hostx64/x64:$PATH"
export PATH="$HOME/.cargo/bin:$PATH"
cd /tmp/zeroclaw_src/zeroclaw-labs-zeroclaw-*/
cargo +1.92.0-x86_64-pc-windows-msvc build --release --locked

# 停止正在运行的进程后替换二进制
powershell.exe -Command "Stop-ScheduledTask -TaskName 'ZeroClaw Daemon'; Get-Process zeroclaw -ErrorAction SilentlyContinue | Stop-Process -Force"
cp target/release/zeroclaw.exe "$HOME/.cargo/bin/zeroclaw.exe"

# 重启服务
powershell.exe -Command "Start-ScheduledTask -TaskName 'ZeroClaw Daemon'"

问题 6：Agent 报错 exceeded maximum tool iterations (10)

原因： 默认 max_tool_iterations = 10 对复杂任务不够用。

解决： 修改配置：

[agent]
max_tool_iterations = 50

问题 7：安装/替换时报"拒绝访问"

原因： zeroclaw.exe 正在运行，文件被占用。

解决：

Stop-ScheduledTask -TaskName 'ZeroClaw Daemon'
Get-Process zeroclaw -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Sleep 2
# 然后再执行替换操作

附录：完整 config.toml 参考

api_key = "enc2:..."
default_provider = "anthropic-custom:https://your-endpoint.com"
default_model = "claude-sonnet-4-5-20250929"
default_temperature = 0.7
model_routes = []

[observability]
backend = "none"

[autonomy]
level = "full"
workspace_only = false
allowed_commands = [
    "ls", "dir", "cat", "type", "find", "grep", "echo", "pwd", "wc", "head", "tail",
    "sort", "awk", "sed", "xargs", "cut", "tr", "diff",
    "git", "cargo", "npm", "npx", "node", "yarn", "python", "python3", "pip",
    "mkdir", "cp", "mv", "touch", "ln",
    "curl", "wget", "ssh", "scp", "rsync",
    "ping", "netstat", "ipconfig", "nslookup",
    "docker", "kubectl", "helm",
    "powershell", "pwsh", "cmd", "bash", "sh",
    "tar", "zip", "unzip", "7z",
    "ps", "tasklist", "taskkill",
    "whoami", "hostname", "date"
]
forbidden_paths = []
max_actions_per_hour = 9999
max_cost_per_day_cents = 99999
require_approval_for_medium_risk = false
block_high_risk_commands = false
auto_approve = ["file_read", "memory_recall"]
always_ask = []

[agent]
compact_context = false
max_tool_iterations = 50
max_history_messages = 100
parallel_tools = true
tool_dispatcher = "auto"

[memory]
backend = "sqlite"
auto_save = true

[channels_config]
cli = true

[channels_config.qq]
app_id = "YOUR_APP_ID"
app_secret = "YOUR_APP_SECRET"
allowed_users = ["*"]

[http_request]
enabled = true
allowed_domains = ["com", "org", "net", "io", "dev", "ai", "cn", "vip", "info", "tech", "app", "co", "me"]
max_response_size = 10485760
timeout_secs = 30

[gateway]
port = 3000
host = "127.0.0.1"
require_pairing = true

本文已收录到 AI编程一站式导航。本文链接：[03.9 2026 年最佳 AI 编码工具完全指南](code.ai80.vip/ai-tool-gui… 2026 年最佳 AI 编码工具完全指南) 强烈推荐：AI编程巴士网站：稳定纯净的ClaudeCode套餐供应；