资料核对日期:2026-11-16;未做本地安装实测。本文适用于通过命令行运行 OpenClaw 的 macOS、Linux 与 Windows 环境;Windows 原生 PowerShell 和 WSL2 路线均受官方文档支持。以下内容依据指定提交中的官方入门文档整理,不把主分支内容视为稳定版本承诺;执行前应再次查看 Getting started 的当前要求。
准备条件
这次自查的任务是确认两件事:Node.js 版本是否满足要求,以及 OpenClaw 能否使用已有的 AI 访问方式完成一次真实请求。你需要准备命令行终端,并具备现有 Claude Code 或 Codex CLI 登录,或者可用的服务商 API 密钥。密钥占位符不能作为实际配置值;具体服务商、密钥内容和登录状态需由使用者确认。
官方当前列出的 Node.js 条件是:24.x 分支至少为 24.16.0,或使用 26.1.0 及以上版本;推荐 Node 26。若需要包含文档所述安全修复,应使用 24.22.1 及以上或 26.12.1 及以上。其他系统级依赖是否适用于你的部署方式:待确认。
检查 Node.js 版本
在终端输入:
node --version
预期得到 Node.js 版本号。将主版本和完整版本与上述范围逐项比较,不要只判断命令是否有输出。例如,24.x 必须达到该分支的最低版本,不能因为主版本是 24 就直接判定通过。
如果终端提示找不到 node,或者版本低于适用门槛,应先按照官方 Node setup 更新或安装 Node.js,再继续 OpenClaw 验证。本文不补充来源未覆盖的软件包名称、安装路径或第三方安装命令。
验证 OpenClaw 与 AI 访问链路
尚未安装或希望按最短官方入口启动时,输入:
npx openclaw@latest
在全新环境中选择 Quick start。官方说明该流程会查找已有的 Claude Code、Codex CLI 登录或 API 密钥,并通过一次真实 completion 验证可用性。若系统询问是否让 OpenClaw 在后台持续运行,选择 No 可让 Gateway 暂时留在当前终端;按 Ctrl+C 可停止,但配置仍会保存。因此,这一步并非纯只读检查,执行前应确认允许写入 OpenClaw 配置。
成功验收以流程找到可用 AI 访问方式、完成真实 completion,并打开 Web dashboard 为准。随后在 Control UI 中发送一条普通消息;按官方文档,预期应收到 AI 回复。只有完成这一步,才能确认当前 AI 登录或密钥所对应的请求链路可用,不能仅凭网页可以打开就推断服务商端点正常。
已安装环境的状态确认
若 OpenClaw CLI 已经安装并且 Gateway 已配置,可输入:
openclaw gateway status
预期看到 Gateway 正在端口 18789 监听。还可以输入:
openclaw dashboard
浏览器能够加载 Control UI,说明 Gateway 与本地界面链路正常;最终仍应以发送消息并收到 AI 回复作为 AI 访问验收。
相关失败场景与检查顺序
若 Quick start 找不到可用路由,或真实 completion 验证失败,不要把问题直接归因于公网、DNS、防火墙或代理,因为现有来源没有提供这些结论的判定命令。先确认 Node.js 版本满足要求,再确认 Claude Code、Codex CLI 登录或真实 API 密钥确实存在且有效。
对于已经安装的环境,可运行只读诊断:
openclaw triage
该命令执行只读健康检查并生成已清理敏感信息的诊断提示;在你主动选择代理之前,内容不会离开本机。根据输出修复已明确指出的问题,再重新运行启动流程和消息验收。若仍无法定位,可进入官方 Troubleshooting 按具体症状继续核对。