Skip to content
OpenClaw 书稿预览

10 分钟上手：安装、启动、第一次对话

很多读者第一次接触 OpenClaw，第一反应不是“这也太强了”，而是“我怎么一装就报错”。
这章就是来解决这个痛点：把“安装—启动—首聊”拆成一条最短可跑通路径，先把第一轮对话跑通，再补细节。

你会在本章看到两类内容：一类是可直接复制执行的步骤，另一类是高频报错的定位方法。
只要按顺序完成，你就能在本地确认 OpenClaw 已经可用，并具备继续进入后续章节（渠道接入、技能开发、排障优化）的基础。

本章你将学会什么

Section titled “本章你将学会什么”
  • 在终端/命令行（CLI）里完成 OpenClaw 的最短安装路径。
  • 判断“我现在的环境是否真的满足要求”，避免一上来卡在版本与网络问题。
  • 用一次最小成功闭环确认 OpenClaw 可用：打开控制台页面、发出消息、收到回复。
  • 遇到首轮高频报错时，知道先查哪里、先改什么。

读者前置

Section titled “读者前置”
  • 你至少有一台可用电脑（macOS、Linux，或 Windows + WSL2）。
  • 你可以打开终端并执行基础命令（如 node --version）。
  • 你已经准备好至少一个可用模型的 API 密钥（例如 OpenAI、Anthropic、OpenRouter 或其他兼容提供商）。
  • 你的网络可以访问以下地址（本章会再次检查）：

动手步骤

Section titled “动手步骤”

2.1 运行环境检查：先做 3 个确认（别急着装）

Section titled “2.1 运行环境检查：先做 3 个确认（别急着装）”

很多新手一上来就直接安装，结果最容易遇到两种情况：

  • 装完跑不起来（版本不对）
  • 明明照着做，却卡在下载/网络

所以这一步的目标很简单：先确认“地基”没问题，再进入安装。

2.1.1 确认 1：Node.js 版本是否满足要求（必须）

Section titled “2.1.1 确认 1：Node.js 版本是否满足要求（必须）”

OpenClaw 当前文档要求 Node >= 22。先在终端执行：

Terminal window
node --version

你期望看到的结果类似：

v22.x.x

如果低于 v22，先升级 Node，再继续本章。
参考：https://docs.openclaw.ai/install/node

2.1.2 确认 2：安装地址与文档是否可访问（必须）

Section titled “2.1.2 确认 2：安装地址与文档是否可访问（必须）”

在你的网络环境下，至少确认这两个地址能访问：

你可以用下面命令做一个快速连通性检查：

Terminal window
curl -I https://openclaw.ai/install.sh
curl -I https://docs.openclaw.ai/start/getting-started

看到 200 / 301 / 302 都通常表示可达（重定向是正常现象）。

2.1.3 确认 3：你使用的是“可执行命令”的环境（建议）

Section titled “2.1.3 确认 3：你使用的是“可执行命令”的环境（建议）”

如果你在 Windows 上，官方当前建议优先通过 WSL2 路径执行命令。
参考：https://github.com/openclaw/openclaw

验证命令放到本节最后统一执行（见 2.1.5），避免和安装命令混在一起导致误操作。

2.1.4 如果 node / npm 未安装，应该怎么装

Section titled “2.1.4 如果 node / npm 未安装，应该怎么装”

如果你执行 node --version 或 npm --version 提示“command not found”，可以按系统走下面路径（按官方 Node 文档常用方案）：

macOS（推荐 Homebrew）：

Terminal window
brew install node

Windows（推荐 winget）：

Terminal window
winget install OpenJS.NodeJS.LTS

Ubuntu / Debian：

Terminal window
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

如果你是 Fedora / RHEL，可先执行：

Terminal window
sudo dnf install nodejs

2.1.5 安装完成后统一验证（所有系统都一样）

Section titled “2.1.5 安装完成后统一验证（所有系统都一样）”

安装完成后，再执行下面两条验证命令：

Terminal window
node --version
npm --version

判断标准：

  • node --version 返回 v22.x.x（或更高）；
  • npm --version 返回版本号（任意正常数字版本均可）。

给新手的操作建议：每次只复制并执行你“当前这一步”需要的命令，不要把安装与验证一起整块复制。若后续提示命令找不到，优先检查 npm 全局路径（npm prefix -g）是否已进入 PATH。

2.2 安装 OpenClaw（最短路径）

Section titled “2.2 安装 OpenClaw（最短路径）”

2.2.1 选择安装方式（推荐：向导）

Section titled “2.2.1 选择安装方式（推荐：向导）”

官方 README 明确给出的首选路径是：在终端运行向导（Wizard）openclaw onboard。
如果你本机还没有 openclaw 命令，先安装 CLI：

Terminal window
npm install -g openclaw@latest

然后执行向导：

Terminal window
openclaw onboard --install-daemon

这个参数会安装 Gateway 的后台服务（daemon），让它能在后台保持运行。
参考：

2.2.2 执行安装命令并校验结果

Section titled “2.2.2 执行安装命令并校验结果”

先按“正常路径”安装；只有报错时再看“异常处理”。

2.2.2.1 正常安装路径
Section titled “2.2.2.1 正常安装路径”

先执行 CLI 安装命令：

Terminal window
npm install -g openclaw@latest

执行时请重点关注三类提示：

  1. 是否提示 Node 版本不满足要求；
  2. 是否提示网络下载失败或超时；
  3. 是否提示安装完成且无权限错误。

如果向导中途失败，不要跳步，先修复当前报错再继续。
对初学者来说，“每步都成功”比“一次跑到底”更重要。

2.2.2.2 安装报错处理：EACCES（Ubuntu / Debian）
Section titled “2.2.2.2 安装报错处理：EACCES（Ubuntu / Debian）”

如果你在 Ubuntu / Debian 上执行第一条命令出现 EACCES: permission denied（例如无权限写入 /usr/lib/node_modules），先用临时方案：

Terminal window
sudo npm install -g openclaw@latest

安装后立刻验证：

Terminal window
openclaw --version

如果你希望长期不使用 sudo（推荐），可以一次性把 npm 全局目录切到当前用户：

  1. 创建用户级全局目录：
Terminal window
mkdir -p ~/.npm-global
  1. 设置 npm 全局前缀：
Terminal window
npm config set prefix ~/.npm-global
  1. 把目录加入 PATH（按所用 shell 选择其一）：
Terminal window
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
Terminal window
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
  1. 让 PATH 生效（按所用 shell 选择其一）：
Terminal window
source ~/.bashrc
Terminal window
source ~/.zshrc
  1. 重新安装 OpenClaw（此时不需要 sudo）：
Terminal window
npm install -g openclaw@latest
  1. 最后验证：
Terminal window
which openclaw
Terminal window
openclaw --version

2.2.3 openclaw onboard 选项逐项说明（重点）

Section titled “2.2.3 openclaw onboard 选项逐项说明（重点）”

完成 2.2.2 的 CLI 安装后，再执行向导命令：

Terminal window
openclaw onboard --install-daemon

该命令会进入交互式向导，同时安装 Gateway 的后台服务（daemon）。

下面这部分按 源码中的真实提示文案（v2026.2.17）来写，与你终端里看到的标签一一对应。

2.2.3.1 QuickStart 路径（首次上手推荐）
Section titled “2.2.3.1 QuickStart 路径（首次上手推荐）”

  1. I understand this is powerful and inherently risky. Continue?
    安全确认，首次建议选 Yes（否则向导退出）。

  2. Onboarding mode
    可选 QuickStart 或 Manual。零基础先选 QuickStart。

  3. Existing config detected（如果检测到已有配置）
    会展示当前摘要（如 workspace、model、gateway.port、gateway.bind、skills.nodeManager）。

  4. Config handling
    三个选项：

    • Use existing values（推荐：先沿用）
    • Update values（在现有配置上改）
    • Reset（谨慎）

    若选 Reset，还会出现 Reset scope：

    • Config only
    • Config + creds + sessions
    • Full reset (config + creds + sessions + workspace)

  5. QuickStart（说明卡片，不是输入框）
    展示将采用的网关设置，例如：

    • Gateway port: 18789
    • Gateway bind: Loopback (127.0.0.1)
    • Gateway auth: Token (default)
    • Tailscale exposure: Off

  6. Model/auth provider
    这里是你真正选择模型/鉴权入口的地方。
    建议：首次 onboarding 不要选 Skip for now，先把模型与鉴权配好，再做 Channels。
    进入提供商后，若该提供商有多种方式，会出现 <Provider> auth method 二级选择。
    对中国大陆读者，建议默认优先 Coding Plan 路径（截至 2026-02-14）。

    • A) MiniMax（目标模型：M2.5）

      1. Model/auth provider 选 MiniMax。
      2. 在 MiniMax auth method 里，优先选 MiniMax OAuth（Coding Plan）。
      3. 继续选择 Select MiniMax endpoint：
        • CN（中国大陆默认）
      4. 完成后默认模型通常为 minimax/MiniMax-M2.5。
      5. MiniMax M2.5 / MiniMax M2.5 Lightning 是 API Key 路径，放在第二选择；首次不建议走 Global 线路。

    • B) Zhipu/GLM（目标模型：GLM-5）

      1. Model/auth provider 选 Z.AI。
      2. 在 Z.AI auth method 里，优先选择 Coding Plan：
        • Coding-Plan-CN（中国大陆默认）
      3. 按提示输入 Enter Z.AI API key。
      4. 若你明确要固定 GLM-5，建议在完成 onboarding 后切到 CN 非 Coding 入口（对应 zai/glm-5）。
      5. 说明：Coding Plan 入口在当前向导探测逻辑下，可能默认落到 glm-4.7。

    • C) Moonshot/Kimi（目标模型：K2.5）

      1. Model/auth provider 选 Moonshot AI (Kimi K2.5)。
      2. 在 Moonshot AI (Kimi K2.5) auth method 里，优先选 Kimi Code API key (subscription)（Coding Plan）。
      3. 按提示输入 Enter Kimi Coding API key。
      4. 完成后默认模型为 kimi-coding/k2p5（K2.5）。
      5. Kimi API key (.cn/.ai) 属于 Moonshot Open Platform API 路径，不是 Kimi Code 订阅路径；大陆读者首次建议只用 .cn 或 Kimi Code 订阅路径。

  7. Channel status（状态卡片）
    列出各渠道是否已配置、是否需安装插件。

  8. Select channel (QuickStart)
    这是 QuickStart 的单选渠道入口。常见会看到：

    • Telegram (Bot API)
    • WhatsApp (QR link)
    • Discord (Bot API)
    • IRC (Server + Nick)
    • Google Chat (Chat API)
    • Slack (Socket Mode)
    • Signal (signal-cli)
    • iMessage (imsg)
    • 以及插件渠道（如 Feishu/Lark、Matrix、Mattermost、BlueBubbles 等，取决于插件状态）
    • Skip for now

    建议（本书统一流程）：首次一律选 Skip for now。
    原因很简单：先把 “本机 Web UI 能稳定对话” 这条主线跑通，再进入第 8 章（飞书）与第 15 章（其他渠道）做接入会更稳，排错成本也更低。

  9. Skills status / Configure skills now? (recommended)
    建议首次选 Yes，按默认走；若出现依赖安装：

    • Install missing skill dependencies
    • Preferred node manager for skill installs 可先用默认值，后续再精调。
2.2.3.2 Manual 路径（比 QuickStart 多出来的关键项）
Section titled “2.2.3.2 Manual 路径（比 QuickStart 多出来的关键项）”

当你在 Onboarding mode 选 Manual 后，常见会额外看到：

  • What do you want to set up?

    • Local gateway (this machine)
    • Remote gateway (info-only)

  • Workspace directory（可自定义）

  • Gateway 逐项输入（Manual 才会逐项问）：

    • Gateway port
    • Gateway bind（Loopback / LAN / Tailnet / Auto / Custom IP）
    • Gateway auth（Token / Password）
    • Tailscale exposure（Off / Serve / Funnel）
    • Gateway token (blank to generate) 或 Gateway password

  • 渠道流程会变成：

    • Configure chat channels now?
    • Select a channel
    • Finished
    • （可选）Configure DM access policies now? (default: pairing)

    首次上手建议在这里选“先不配渠道”（No 或 Skip for now），按本书后续章节再逐项接入。

结论：向导步骤请以终端原文标签为准；本书本节已与源码提示名对齐，避免二次翻译造成误解。

2.2.4 版本与路径验证

Section titled “2.2.4 版本与路径验证”

安装完成后，至少做这三项验证：

Terminal window
openclaw --version
which openclaw
openclaw doctor

验证通过的标准：

  • openclaw --version 能返回版本号；
  • which openclaw 能返回命令路径（说明命令已进 PATH）；
  • openclaw doctor 不再报“命令不存在”这类基础错误。

如果 which openclaw 没结果，通常是 shell 环境没有加载全局 npm 路径。先重开终端，再试一次。

2.3 最小配置（模型密钥与基础参数）

Section titled “2.3 最小配置（模型密钥与基础参数）”

2.3.1 必填配置项

Section titled “2.3.1 必填配置项”

本章按中国大陆读者的默认路径，建议你在 onboard 里一次填完这三件事：

  1. Provider 与 auth method（优先 Coding Plan）；
  2. 可用的默认模型（先跑通，再微调）；
  3. Workspace 与 Gateway 默认值（先用默认，减少变量）。

可直接按这张“最小可用清单”执行：

Provider向导里建议选择默认模型落点（常见）
MiniMaxMiniMax -> MiniMax OAuth -> CNminimax/MiniMax-M2.5
Zhipu/GLMZ.AI -> Coding-Plan-CN常见为 zai/glm-5（见下方说明）
Moonshot/KimiMoonshot AI (Kimi K2.5) -> Kimi Code API key (subscription)kimi-coding/k2p5

说明（重要）：Z.AI 的 Coding Plan 入口在当前向导探测逻辑下可能落到 glm-4.7；如果你必须固定 GLM-5，可在完成 onboarding 后改用 zai/glm-5（见 2.3.3）。

2.3.2 最小可用参数

Section titled “2.3.2 最小可用参数”

对新手最稳的做法，是先保持以下默认：

  • Gateway 绑定本地回环地址（loopback）；
  • 默认端口使用 18789；
  • 先不开远程暴露和公网访问。

这样做的优势是：安全边界清晰、排障变量更少。
等第 3~4 章理解架构和权限后，再做进阶网络配置。

如果你已经跑过一次 onboarding，可直接再执行：

Terminal window
openclaw onboard

然后在 Existing config detected -> Config handling 里选 Update values，仅调整模型与 auth，不改其余项。

2.3.3 配置后自检

Section titled “2.3.3 配置后自检”

按下面顺序做“最小自检”：

  1. 看默认模型与鉴权状态：
Terminal window
openclaw models status
  1. 看模型列表里是否出现你配置的 provider：
Terminal window
openclaw models list | rg "minimax|zai|moonshot|kimi-coding"
  1. 检查本地端口监听（按系统择一）：
Terminal window
lsof -iTCP:18789 -sTCP:LISTEN

或（Linux 常见）：

Terminal window
ss -ltnp | rg 18789

看到 models status 正常、模型列表存在目标 provider、18789 在监听，通常就表示配置生效。
下一步进入 2.4 做第一次对话验证。

如果你要把 Z.AI 默认模型固定为 GLM-5，可执行：

Terminal window
openclaw models set zai/glm-5

2.4 启动与第一次对话

Section titled “2.4 启动与第一次对话”

2.4.1 Onboard 收尾入口：hatch 选项（承接上文）

Section titled “2.4.1 Onboard 收尾入口：hatch 选项（承接上文）”

在 openclaw onboard 接近结束时，向导会出现：

  • 提示语：How do you want to hatch your bot?
  • 选项 1：Hatch in TUI (recommended)
  • 选项 2：Open the Web UI
  • 选项 3：Do this later

这一步本质上就是“完成配置后，立刻进入第一次对话入口”的承接动作。

给你一张“一屏决策表”：

你当前的情况该选什么为什么下一步
第一次接触、希望最少命令Open the Web UI页面可视化，最容易判断“是否跑通”打开浏览器发第一条消息
平时主要在终端工作Hatch in TUI (recommended)不离开终端，调试链路短在 TUI 里直接发“给我 3 条今天可执行待办”
现在不方便继续测试Do this later先完成安装，后续再验证稍后执行 openclaw dashboard --no-open 或 openclaw tui
远程服务器/无图形环境Hatch in TUI 或 Do this later避免浏览器打开失败干扰主线先 openclaw tui，必要时再做端口转发

本书建议：

  1. 新手主线优先选 Open the Web UI（更直观，便于截图和复盘）；
  2. 偏终端工作流的读者可选 Hatch in TUI (recommended)；
  3. 如果选了 Do this later，可手动进入：
Terminal window
openclaw dashboard --no-open
Terminal window
openclaw tui

2.4.2 启动服务与日志观察

Section titled “2.4.2 启动服务与日志观察”

如果你刚通过 openclaw onboard --install-daemon 完成安装，Gateway 往往已经在后台运行。
若没有运行，可在当前终端手动启动：

Terminal window
openclaw gateway --port 18789 --verbose

--verbose 的作用是输出更详细日志，便于定位初始化问题。
建议你在首次启动时保留日志窗口，不要立即关闭。

2.4.3 进入 Control UI 并发送首条消息

Section titled “2.4.3 进入 Control UI 并发送首条消息”

在浏览器打开：

进入页面后，先发一条低上下文测试消息，例如：

请给我一个“今天就能执行”的 5 条待办清单（每条不超过 18 个字），并按优先级排序。

如果你想再测一次查询能力，可补发：

请告诉我北京今天的天气，并给出 1 句穿衣建议。

这一步的目标不是“测模型聪明不聪明”，而是验证“请求能发出、模型能返回、页面能显示”。

2.4.4 判断“已跑通”的标准

Section titled “2.4.4 判断“已跑通”的标准”

满足下面 3 条，就可以判定你已跑通最短跑通路径：

  1. 浏览器能稳定打开 127.0.0.1:18789；
  2. 你发送的消息能被系统接收；
  3. 页面能在可接受时间内返回可读回复。

如果只满足 1、2，不满足 3，优先排查密钥、模型可用性与网络代理（见 2.5）。

2.5 10 分钟内最常见 5 个坑

Section titled “2.5 10 分钟内最常见 5 个坑”

2.5.1 端口与权限问题

Section titled “2.5.1 端口与权限问题”

常见现象：

  • 打不开 127.0.0.1:18789；
  • 启动时提示端口被占用；
  • 命令存在，但启动即退出。

优先处理：

  1. 用 lsof -iTCP:18789 -sTCP:LISTEN 看谁占用端口；
  2. 确认你不是在受限目录执行（尤其公司管控机器）；
  3. 临时换端口启动（例如 openclaw gateway --port 18889 --verbose）再验证。

2.5.2 密钥与模型调用问题

Section titled “2.5.2 密钥与模型调用问题”

常见现象：

  • 页面能打开，但一直无回复；
  • 返回 401 / 403 / 429 类错误；
  • 返回“模型不存在/无权限”。

优先处理：

  1. 确认密钥未过期、未复制错（常见是多一个空格）；
  2. 确认所选模型在当前账号下确实可调用；
  3. 先用成本更低、稳定性更高的基础模型做连通性验证，再升级模型档位。

2.5.3 代理与网络问题

Section titled “2.5.3 代理与网络问题”

常见现象：

  • 安装阶段下载超时；
  • 启动后请求长期 pending；
  • 同一配置在别的网络可用、在当前网络不可用。

优先处理：

  1. 先确认文档与安装地址可访问（2.1.2）；
  2. 区分“本地服务没起”与“外部模型不可达”两类问题；
  3. 在公司网络场景优先和网络管理员确认出站策略，不要反复盲试。

常见错误与排查

Section titled “常见错误与排查”
现象高概率原因第一处理动作
openclaw: command not foundCLI 未安装或 PATH 未生效重新执行 npm install -g openclaw@latest，并重开终端
node: command not found / npm: command not foundNode.js 未安装，或 PATH 未生效先按 2.1.4 安装 Node 22+，再重新打开终端验证
npm install -g openclaw@latest 报 EACCESLinux 下全局 npm 目录需要更高权限临时方案：sudo npm install -g openclaw@latest；长期方案：按 2.2.2 的“无 sudo”步骤配置用户级 npm 全局目录
提示 Node 版本不满足本机 Node < 22升级到 Node 22+ 后重试
浏览器打不开 127.0.0.1:18789Gateway 未启动或端口被占用用 lsof 检查监听状态，再手动启动 openclaw gateway --port 18789 --verbose
页面能打开但无回复密钥无效、模型无权限、网络不可达先检查密钥与模型权限，再检查代理/网络
Windows 下流程异常未使用 WSL2 或 shell 环境不完整切到 WSL2 终端按同样步骤重走

2.6 补充内容：三家 Coding Plan 开通步骤（截至 2026-02-14）

Section titled “2.6 补充内容：三家 Coding Plan 开通步骤（截至 2026-02-14）”

目的：把“订阅开通 → 拿到 Key → 回到 openclaw onboard 继续配置”这条链路补完整。
说明：控制台菜单可能微调，请以官方页面实时展示为准。

2.6.1 MiniMax Coding Plan（M2.5）

Section titled “2.6.1 MiniMax Coding Plan（M2.5）”
  1. 打开订阅页并登录：https://platform.minimaxi.com/subscribe/coding-plan
  2. 选择套餐（Starter / Plus / Max）并完成支付。
  3. 打开 Account/Coding Plan 页面获取 Coding Plan API Key：
    https://platform.minimaxi.com/user-center/payment/coding-plan
  4. 回到 openclaw onboard，在 Model/auth provider 选 MiniMax，再在 MiniMax auth method 里优先走 MiniMax OAuth（Coding Plan 路径）。

2.6.2 Zhipu GLM Coding Plan

Section titled “2.6.2 Zhipu GLM Coding Plan”
  1. 登录 Bigmodel 控制台：https://bigmodel.cn/console/overview
  2. 在独立入口开通 GLM Coding Plan：
    https://bigmodel.cn/glm-coding
  3. 开通后在计划管理页查看套餐状态与额度：
    https://bigmodel.cn/usercenter/glm-coding/my-plan
  4. 在 API Keys 页面创建或获取 Key（用于工具接入）：
    https://bigmodel.cn/usercenter/apikeys
  5. 回到 openclaw onboard，在 Model/auth provider 选 Z.AI，再在 Z.AI auth method 里优先选 Coding-Plan-CN。

2.6.3 Moonshot / Kimi Coding Plan（K2.5）

Section titled “2.6.3 Moonshot / Kimi Coding Plan（K2.5）”
  1. 打开 Kimi Code 首页并登录：https://www.kimi.com/code
  2. 选择并开通 Coding Plan（官方“Getting Started”步骤）。
  3. 进入 Kimi Code Console 的 API Keys 创建 Key：
    https://www.kimi.com/code/console
  4. 回到 openclaw onboard，在 Model/auth provider 选 Moonshot AI (Kimi K2.5)，并在 auth method 里优先选 Kimi Code API key (subscription)。

本章小结

Section titled “本章小结”
  • 先做环境检查，再安装，是新手成功率最高的顺序。
  • 对 OpenClaw 首次上手而言，openclaw onboard --install-daemon 是最短主线。
  • “已跑通”的核心判断很朴素：本地页面可打开、能发消息、能收到回复。
  • 一旦报错，先做最小排查：版本、端口、密钥、网络，不要同时改十个参数。
  • 中国大陆读者首次实操建议：Model/auth provider 优先走三家 Coding Plan 路径，再做渠道配置。