🪟 OpenClaw v2026.5.27 部署指南（Windows）

OpenClaw 是一款AI 智能体网关平台，把分散在各聊天平台（Telegram / Discord / 飞书 / 微信 / QQ / Slack）的消息统一路由到一个本地 Gateway，再分发给后端 Agent（Hermes、Codex、Claude Code、OpenCode 等）。本指南基于 v2026.5.27 (commit 27ae826) 实测。

一、OpenClaw 是什么？

OpenClaw 的核心定位是 "All your chats, one OpenClaw"——一个本地化的消息枢纽：

• Channel 聚合 — Telegram / Discord / 飞书 / 微信 / QQ / Slack / iMessage / Matrix / Signal 全部接进来
• Agent 路由 — 6+ isolated agents 共享一个 Gateway，每个 agent 独立 workspace/auth/routing
• 模型无关 — 支持 OpenAI / Anthropic / Gemini / DeepSeek / Ollama 本地模型 / 自定义 provider
• 插件生态 — memory-core、webhooks、tts、transcripts、sandbox 容器等
• ACP coding agents — 内置 Claude Code / Codex / OpenCode 委派子 agent

二、📋 系统要求

三、方案 A：WSL2 安装（⭐推荐）

3.1 启用 WSL2（管理员 PowerShell）

# 装 WSL + Ubuntu 22.04
wsl --install -d Ubuntu-22.04

# 重启后自动启动 Ubuntu，设置用户名/密码
# 然后验证
wsl -l -v
# 期望: Ubuntu-22.04  Running  2

wsl --shutdown

3.2 在 WSL Ubuntu 内：装 Node + pnpm

# 装 Node 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 验证
node -v   # v22.x.x

# 装 pnpm（推荐，比 npm 快）
sudo npm install -g pnpm

# 验证
pnpm -v   # 9.x.x

3.3 安装 OpenClaw

# pnpm 推荐（快 3-5x）
pnpm install -g openclaw@latest

# 验证
openclaw --version
# 期望: OpenClaw 2026.5.27 (27ae826)

# 也可 npm，但慢
# npm install -g openclaw@latest

3.4 初始化（setup + onboard）

v2026.5.27 拆成两步：setup（创配置） + onboard（引导）

# 1) 创建 baseline 配置
openclaw setup

# 2) 引导式配置（gateway/workspace/auth/channels）
openclaw onboard

onboard 会问：

1. 是否要装 Gateway（默认 yes）
2. Workspace 路径（默认 ~/.openclaw）
3. 至少 1 个 chat channel 凭证（先 skip 后面用 openclaw channels add 配）
4. 默认模型 provider + API key

3.5 启动 Gateway（systemd 服务）

v2026.5.27 默认用系统服务管理 Gateway（不是手动跑）：

# 安装为 systemd user service（自动开机启动）
openclaw onboard --install-daemon

# 或手动启停
openclaw gateway run --force      # 临时前台跑
openclaw gateway stop              # 停
openclaw gateway restart           # 重启

# 状态
openclaw status                    # Gateway / channel / model / sessions
openclaw doctor --fix              # 修复常见问题

# 实时日志
openclaw logs                      # tail 风格

四、方案 B：原生 Windows 安装（备选）

4.1 装 Node 22+

# winget（推荐）
winget install OpenJS.NodeJS.LTS

# 或官网下载 https://nodejs.org

# 验证
node -v
npm -v

4.2 装 Git

winget install Git.Git

4.3 装 OpenClaw

npm install -g openclaw@latest

# 验证
openclaw --version

4.4 配置 PATH

# 看全局路径
npm prefix -g
# 把返回的路径加到系统环境变量 PATH

4.5 初始化 + 启动

openclaw setup
openclaw onboard

# 服务以 Windows Service / 计划任务 形式跑
openclaw onboard --install-daemon

五、v2026.5.27 配置 chat channel

装完 Gateway 后，用 openclaw channels 子命令管理消息平台：

# 列出已配置的 channel
openclaw channels list

# 列出所有可安装的 channel（catalog）
openclaw channels list --all

# 引导式添加一个 channel
openclaw channels add
# 交互式选 Telegram → 填 Bot Token → 完成

# 状态
openclaw channels status
openclaw channels status --probe    # 深度探测（含登录态）

# 解绑
openclaw channels logout telegram
openclaw channels remove telegram

# 直接发消息
openclaw message send --channel telegram --target @mychat --message "Hello from OpenClaw"

5.1 常用 channel 配置

5.2 添加 agent（多 Agent 路由）

openclaw agents add                    # 引导加 agent
openclaw agents list                   # 列出所有 agent
openclaw agents bind                   # 加 routing 规则
openclaw agents set-identity main      # 改 main agent 身份

# 跑一次 agent turn
openclaw agent --to +15555550123 --message "Run summary" --deliver

六、v2026.5.27 常用命令速查

七、⚙️ 常用环境变量

profile 隔离：openclaw --profile staging 状态走 ~/.openclaw-staging/，用于多环境测试。

八、❓ 常见问题 FAQ

Q1: openclaw is not recognized 怎么办？

PATH 没配。运行 npm prefix -g 或 pnpm root -g，把返回路径加入系统 PATH。重启终端。

Q2: sharp 模块安装失败（Windows 原生）

set SHARP_IGNORE_GLOBAL_LIBVIPS=1
npm install -g openclaw@latest

或直接用 WSL2 方案避开。

Q3: Gateway 端口 18789 被占用

openclaw configure → Gateway 改端口。或 openclaw gateway run --force 强制替换。

Q4: 关闭终端后 Gateway 停了

v2026.5.27 默认 openclaw onboard --install-daemon 装为系统服务（systemd/LaunchAgent），不需要手动前台跑。

Q5: WSL2 服务怎么被局域网访问？

# PowerShell 管理员
$WslIp = (wsl --hostname -I).Trim().Split(" ")[0]
netsh interface portproxy add v4tov4 listenport=18789 connectaddress=$WslIp connectport=18789
# 防火墙放行
New-NetFirewallRule -DisplayName "WSL OpenClaw" -Direction Inbound -LocalPort 18789 -Protocol TCP -Action Allow

Q6: 怎么和 Hermes 联动？

典型架构：

用户消息 → OpenClaw Gateway (18789)
         → 路由到某个 agent
         → agent 调 Hermes CLI/HTTP API
         → 结果回传 OpenClaw → 转发回原 channel

v2026.5.27 通过 openclaw mcp + openclaw plugins 配置 MCP bridge，把 Hermes 作为后端 model provider。

Q7: cron 定时任务该用 OpenClaw 还是 Hermes？

用 Hermes cronjob（2026-06 已迁移）。OpenClaw 的 cron 模块已 deprecated，文档保留作历史参考。新项目直接 hermes cronjob create。

Q8: 如何升级到最新版本？

pnpm install -g openclaw@latest    # 或 npm install -g openclaw@latest
openclaw --version                  # 验证
openclaw doctor --fix               # 检测升级后兼容性

九、卸载

# v2026.5.27 标准卸载
openclaw uninstall
# 卸服务 + 状态数据，CLI 本身保留（再装覆盖即可）

# 完全清空（含配置）
# macOS/Linux
rm -rf ~/.openclaw

# Windows
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"

# 卸 CLI
pnpm remove -g openclaw    # 或 npm uninstall -g openclaw

十、相关资源

• OpenClaw 官网
• 官方文档
• GitHub 仓库
• CLI 完整参考
• Hermes Agent v0.15.2 部署指南 →

本文由 AI Know 工具教程组实测于 2026-06-13，基于 OpenClaw v2026.5.27 (commit 27ae826) 在 WSL2 Ubuntu 22.04 + Node 22.x 环境。版本更新请关注 官方 changelog。