跳到主要内容

OpenClaw：安装与快速上手

目录​

开始之前：先对齐环境与权限​

官方 README 对运行时版本写得很明确：Node 24（推荐）或 Node 22.16+（见 Install 段落）。建议你在安装前先执行：

node -v

若版本低于要求，优先用 nvm、fnm 或操作系统推荐的 Node 管理方式升级，再安装 OpenClaw。原因很实际：Node 版本不足时，常见表现是「CLI 装了，但 gateway/agent 运行期直接报错」，排障会浪费大量时间在错误方向上。

权限与目录预期​

OpenClaw 会在用户目录下创建工作区与配置（README 提到 ~/.openclaw 与 workspace 路径）。你需要确认：

  • 当前用户对 home 目录可写；
  • 若你在企业环境使用托管账号，确认是否有对 ~/.openclaw 的持久化策略（重装系统会丢配置）。

平台说明​

若你在 Windows 上操作，请优先阅读官方 Getting started 的平台建议；很多团队最终会选择 WSL2 作为稳定路径，而不是在不受支持组合上硬跑。

安装 CLI（npm / pnpm）​

全局安装命令（与 README 一致）：

npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

安装完成后，建议立刻验证二进制是否可用：

openclaw --help

为什么不建议“混用多个全局包管理器”​

在同一台机器上混用 npm/pnpm/bun 的全局安装，可能导致 PATH 指向旧版本二进制。团队规范建议：选定一种全局安装方式并写进内部 runbook，避免“我这边能用你那边不能”的不可复现问题。

推荐路径：onboard 与守护进程​

官方推荐用 Onboarding 向导完成 Gateway、工作区、渠道与 Skills 的初始化：

openclaw onboard --install-daemon

--install-daemon 的含义是：把 Gateway 安装为 launchd（macOS）/ systemd 用户服务（Linux） 等守护进程，使进程在你登录会话中常驻。这对「个人助手」体验很重要：否则你每次重启机器都要手动拉起 gateway。

若你只是在实验环境想「先跑起来再决定是否常驻」，可以先阅读 Onboarding / Wizard，再决定是否安装 daemon。

下面用流程图表达「从安装到常驻」的建议顺序（便于你做 checklist）：

最小可验证闭环​

下面是一条「先证明链路通了，再接入复杂渠道」的 CLI 脉络。端口与 flag 可能随版本微调，请以你本机 openclaw gateway --help、openclaw agent --help 为准：

openclaw onboard --install-daemon

openclaw gateway --port 18789 --verbose

# 与 agent 对话（thinking 级别可按文档调整）
openclaw agent --message "你好，做一次自检清单" --thinking high

README 里还给了 openclaw message send ... 的示例，用于验证「消息发送」能力；是否在你的环境可用，取决于你配置的渠道与权限。

闭环通过的标准​

建议你为“闭环通过”定义可验证标准，避免“好像能跑”：

  • Gateway 进程按预期监听端口；
  • agent 能返回结构化自检项（而不是空响应或无限重试）；
  • doctor 无高危配置提示（或你已理解并接受提示）。

配置入口：openclaw.json 长什么样​

官方 README 给出最小配置示例（路径通常为 ~/.openclaw/openclaw.json），核心字段是 agent.model：

{
  "agent": {
    "model": "<provider>/<model-id>"
  }
}

完整配置键、示例与解释，请直接以官方配置文档为准：Configuration。实战建议：

  • 先最小配置跑通，再逐步加入渠道、工具与白名单。
  • 把密钥当密钥：不要把含 API Key 的配置文件提交到仓库；团队内用密钥管理或私有部署策略。
  • 配置变更可回滚：至少保留上一份可用配置副本（脱敏后）以便紧急恢复。

模型、鉴权与故障转移​

  • 模型选择：README 建议优先使用你信任且已在用的 provider 的当前旗舰模型；具体列表与 CLI 用法见 Models。
  • 故障转移：多 profile、轮换与 failover 见 Model failover。

鉴权失败的典型原因（便于排障）​

  • OAuth 过期、系统时间不对、代理拦截；
  • provider 侧额度/配额用尽；
  • 模型名写错（大小写、后缀、region）。

遇到鉴权问题，优先对照官方 Models 文档与 doctor 输出，而不是先怀疑“模型变笨”。

升级、通道与健康检查​

  • 升级：官方提供 Updating 指南；README 也提到 openclaw update --channel stable|beta|dev 与渠道切换。
  • 健康检查：把 openclaw doctor 当作排障第一站（README 明确建议用它发现 DM 策略等风险配置）。

升级建议节奏：

  1. 阅读 Updating 与 release notes（若可用）。
  2. 备份配置与工作区（脱敏策略由你定义）。
  3. 升级后跑 doctor，再跑最小闭环验证。

渠道接入：别跳过的安全步骤​

只要你接入的是「真实消息表面」，就必须按 Security 理解默认策略。README 里对 DM pairing 有清晰描述：未知发送方可能收到配对码，而 bot 不会处理其消息，直到你执行 openclaw pairing approve ...（详见 README Security defaults）。

遇到连接问题，优先查：

常见阻塞与对应处理思路​

现象优先检查次要检查
命令找不到PATH、全局安装是否成功是否多个包管理器冲突
gateway 起不来端口占用、权限防火墙、代理
agent 无响应模型鉴权、网络配置是否指向错误 model id
doctor 报 DM 风险pairing/allowFrom 策略是否误用 open 模式

下一步读什么​

原文链接​