openclaw

你会遇到什么

你想要一个自己机器上常驻的 AI 助手：能接多个聊天通道（Telegram/WhatsApp/Slack/Discord…）、能定时干活（每天 9 点汇总）、能操控浏览器、能跨会话记忆——而不是每次打开网页版聊天。OpenClaw 就是干这个的：一个本地 Gateway（控制面）+ CLI/TUI/网页控制台 + 通道接入 + 定时自动化（cron）的一体化个人 AI 助手平台，GitHub 38.8 万 stars（2026 顶流开源项目，原 Clawdbot）。 什么时候用：

• 你要一个常驻的本地 AI 助手，通过聊天软件遥控它干活（多通道）；
• 你要定时/触发式自动化（每天自动跑任务、定期汇总、定时提醒）——openclaw cron 内置；
• 你要 AI 帮你操作浏览器（填表、发帖、跨页面任务）——openclaw browser 内置；
• 你要 skills/插件生态（ClawHub 5.4 万+ skills）扩展助手能力。

什么时候别用：只是临时跑一次对话（用聊天客户端就行）；只需要单命令的代码工具（那是 CLI 工具的活）；对常驻服务/Node 运行时敏感的环境（它是 Node 平台 + 常驻 Gateway）。

本文路径：快速修复（一条命令装好并验证版本）→ 一步步来（Node 版本检查 + 隔离安装）→ 怎么确认修好了 → FAQ（Node 版本不满足怎么办）。

为什么会这样

OpenClaw 是 Gateway 架构：一个本地常驻的 Gateway 进程是控制面（管理会话、工具、事件、通道连接），CLI/TUI/网页 Control UI 都连它；通道（Channels）把助手接到 WhatsApp/Telegram/Slack/Discord 等；cron/automations 子命令在 Gateway 上跑定时任务；browser 子命令管理专属浏览器实例。模型层支持 hosted 和本地 provider（可接 ollama）。 装完它动哪里：npm 全局包（Node 运行时）+ 首次 openclaw onboard 会建 ~/.openclaw/ 工作区（配置 + 数据库 + 日志）+ 可选 systemd user 服务（daemon）。零账号红线：onboard/通道接入需要模型 API key 或聊天账号，本指南只覆盖安装与 CLI 验证，不碰任何账号。

一步步来

第 1 步：检查 Node 版本（前置条件）

卡住怎么办：node: command not found → 先装 Node（apt/nvm/官方二进制）；版本 <22.22.3 → 不要动系统 Node，用「依赖警告」的隔离部署法（本机实测路径 /opt/node-v24.15.0-linux-x64/bin 前置 PATH）。

node --version

预期输出: 22.22.3 或更高（22.22.3+ / 24.15.0+ / 25.9.0+ 任一满足）。实测坑：本机系统 Node v22.22.1 不满足（差 patch 级），npm 安装直接报错 [openclaw] detected Node 22.22.1——不要动系统 Node，用隔离部署（见「依赖警告」），不碰系统环境。

第 2 步：安装（清华镜像）

卡住怎么办：报 [openclaw] detected Node xx → Node 版本不满足，回第 1 步隔离部署；报 enoent spawn sh → PATH 被污染（检查 PATH 是否含 /usr/bin、/bin）；超时 → 镜像不可达时换 registry.npmjs.org 直连（视网络）。

npm_config_registry=https://registry.npmmirror.com npm install -g openclaw@latest --no-audit --no-fund

预期输出: changed 331 packages in 9s（包约 204MB unpacked；本机 9s 是缓存加速，首装 1-3 分钟属正常）

第 3 步：验证安装

卡住怎么办：openclaw: command not found → 确认全局 bin 在 PATH（npm prefix -g 查全局目录，隔离部署时前置其 bin）。

openclaw --version && openclaw --help | head -20

预期输出: 第一行 OpenClaw 2026.8.1 (ea80657)，随后列出命令面（acp/agent/channels/cron/gateway/memory/models/browser…）

第 4 步：查看 Gateway 状态（诊断面，不启动服务）

卡住怎么办：报连接错误 → 未 onboard 属正常（config missing 不是故障）；想完整使用需 openclaw onboard（交互向导 + API key，零账号纪律本指南不涉及）。

openclaw gateway status

预期输出: 显示 Service: systemd user (disabled) + Gateway: bind=loopback (127.0.0.1), port=18789 + Dashboard: http://127.0.0.1:18789/。未 onboard 时 config 显示 missing，属正常——首次完整使用需跑 openclaw onboard（交互向导，需要模型 API key，本指南不涉及）。

怎么确认修好了

• openclaw --version 输出版本号（2026.8.1），命令不报错；
• openclaw --help 能列出完整命令面（cron/browser/channels/gateway 都在）；
• openclaw gateway status 正常退出（exit 0）并能给出诊断信息。
• 完整可用（能对话/能定时）需要 onboard 配置模型——那一步需要 API key，本环境未实测（零账号纪律），不冒充。

其它环境的表现

日常使用

前置说明：cron/browser/channels 的子命令都通过本地 Gateway 执行，首次使用需先 openclaw onboard（交互向导 + 模型 API key / 通道账号；零账号红线，本指南不实测）。未配置凭据时命令会明确报错，见下方真实输出——这不是故障，是"还没 onboard"的正常提示。下面给出命令面实测可见的用法与预期输出。

定时任务（cron / automations）

note: 命令面实测可见；真正执行需 Gateway 凭据（onboard 后）

先看当前有哪些自动化。未配置凭据时的真实输出（教你会认这个报错）：

openclaw cron list

预期输出:

gateway cron.list requires credentials before opening a websocket Fix: configure gateway.auth token/password, pair this device, or pass --token/--password. Config: ~/.openclaw/openclaw.json 含义：还没 onboard / 设备未配对。按提示配置 gateway.auth（token/password）或配对设备后重试；不想配凭据就先用 openclaw doctor 看全局状态。 定时任务子命令面（onboard 后可用，命令面实测可见）：add 新增、list 列出、show/get 查看单个、edit 修改、enable/disable 启停、rm 删除、run 立即跑一次、runs 运行历史、status 调度器状态、scratch 读写私有暂存。参数细节见官方文档 docs.openclaw.ai/cli/cron。

浏览器自动化（browser）

note: 命令面实测可见；执行需 Gateway 凭据

检查浏览器插件就绪状态。未配置凭据时的真实输出：

openclaw browser doctor

预期输出:

FAIL gateway: GatewayCredentialsRequiredError: gateway browser.request requires credentials before opening a websocket Fix: configure gateway.auth token/password, pair this device, or pass --token/--password. Config: ~/.openclaw/openclaw.json 含义与上面同理：browser 子命令全走 Gateway，未 onboard 时统一报 credentials 错误。 浏览器子命令面（onboard 后可用，命令面实测可见）：create-profile/delete-profile 管理专属浏览器配置、click/click-coords/fill/drag/highlight 页面交互、evaluate 对页面执行函数、close 关标签页、console/errors 取页面日志、download 保存下载、batch 一次跑一组动作、doctor 就绪检查。参数见官方文档 docs.openclaw.ai/cli/browser。

通道管理（channels）

note: 命令面实测可见；接入通道需聊天账号（零账号不实测）

查看已配置通道。未配置时的真实输出：

openclaw channels list

预期输出:

Chat channels:

• no configured chat channels (run openclaw channels list --all to see installable channels)

Model provider usage moved out of channels list — see openclaw status or openclaw models list. 查看可安装通道目录：

openclaw channels list --all

预期输出: 可安装通道清单（telegram/whatsapp/slack/discord 等，以命令输出为准）

通道子命令面（命令面实测可见）：add 新增/更新通道、login/logout 链接/退出会话、remove 删除、status --probe 状态探测、logs 通道日志、capabilities 各 provider 能力。非交互示例（来自命令面 Examples，需真实 token 才有意义）：openclaw channels add --channel telegram --token <token>。

健康检查（doctor）

note: 命令面实测可见

openclaw doctor

预期输出: 健康检查报告（模型/网关/通道配置状态；未 onboard 时输出未配置项，属正常诊断面）

卸载与清理

note: 卸载 = 移除 npm 全局包；清理 = 删工作区（配置/数据库/日志）。daemon 若启用需先停服务

npm uninstall -g openclaw --no-audit --no-fund && rm -rf ~/.openclaw

预期输出: npm 移除输出（

emoved N packages）；~/.openclaw 不存在即为清理干净。注意：删除工作区会丢失全部配置/记忆/通道绑定，卸载前如需保留先 openclaw backup

依赖警告

note: 版本/环境/冲突四态；冲突对子以矩阵为准

• 版本要求：Node ≥ 22.22.3 / 24.15.0+ / 25.9.0+（npm 12+ 建议；npm 11.15 及以下安装命令需省略 --allow-scripts 参数）。实测：Node 22.22.1 被拒。
• 环境要求：Linux/macOS/Windows 均支持；常驻 Gateway 需要 systemd user 或等效服务管理（daemon 子命令）；磁盘 ~1GB（npm 包 204MB unpacked + 工作区/日志增长）。
• 冲突（矩阵判定）：与同域 moltis（Rust 单二进制个人 Agent 服务器）定位相邻——命令名不同、写面不重叠（各自 ~/.config 目录），静态判定可共存；与 herdr/ruflo/claude-mem 等 CLI 工具写面不重叠。矩阵对子状态以冲突矩阵页为准。
• 网络：npm 安装必须走镜像（官方 registry 直连慢）；首次 onboard 拉模型/连通道视网络环境（本指南零账号不涉及）。
• 安全：入站消息视为不可信输入；DM 通道默认需配对（openclaw pairing approve <channel> <code>）；工具默认跑在 host 主会话（建议按官方 security 指南配置沙箱后再暴露远程）。

FAQ

• 问：npm 报 [openclaw] detected Node 22.22.1 怎么办？
• 答：系统 Node 不满足 22.22.3+。不要动系统 Node——隔离部署一个满足版本的 Node（如 24.15.0）到独立目录，用它前缀跑 npm 安装（本机实测路径：/opt/node-v24.15.0-linux-x64/bin 前置到 PATH）。安装后 openclaw 命令也走该 Node 前缀。
• 问：openclaw gateway status 显示 config missing 是坏了吗？
• 答：不是。未执行 onboard 前的正常状态；onboard 会创建 ~/.openclaw/openclaw.json 并配置 Gateway。
• 问：安装后 openclaw 命令找不到？
• 答：检查全局 bin 是否在 PATH（npm prefix -g 查全局目录）；隔离 Node 部署时确认 PATH 前缀含其 bin。
• 问：onboard 一定要 API key 吗？能接本地模型吗？
• 答：官方支持 hosted 和本地 provider（可配 ollama 等本地模型）。onboard 为交互向导，本指南零账号未实测，配置细节见官方文档 docs.openclaw.ai/concepts/model-providers。
• 问：定时任务需要 Gateway 一直跑吗？
• 答：是——cron/automations 跑在 Gateway 上，需要 daemon 常驻。未实测（零账号 + 避免常驻进程干扰），如实标注。
• 问：OpenClaw 和 moltis 有什么区别？
• 答：OpenClaw = Node 平台的完整个人 AI 助手（多通道 + cron + 浏览器 + skills 生态）；moltis = Rust 单二进制轻量 Agent 服务器（安全优先）。定位相邻、形态不同，按「你要完整助手还是轻量服务器」选。