Skip to content
OpenClaw 书稿预览

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

友情提示：第一次装 OpenClaw 报错千万别慌，十个人里有八个会遇到这样那样的问题。这章就是帮你把“安装—启动—聊天”这条最短路跑通，跑通之后，后面的渠道接入、技能开发啥的都好说。

很多读者第一次接触 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.js 版本至少是 22（你可以理解为“版本号大于等于 22”）。先在终端执行：

Terminal window
node --version

你期望看到类似这样的结果：

v22.x.x

如果显示的版本号低于 v22，比如 v20、v18，那就先别急着装 OpenClaw，先把 Node 升级到 22 以上再说。

升级 Node 的方法放在 2.1.4 节，先看完这节再动手。

2.1.2 确认 2：网络能不能访问（必须）

Section titled “2.1.2 确认 2：网络能不能访问（必须）”

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

可以用下面命令快速检查（Windows 用户建议用 PowerShell）：

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

看到 200、301 或 302 就说明能访问（301/302 是重定向，正常现象）。如果显示超时或者连接失败，先解决网络问题。

2.1.3 确认 3：Windows 用户要注意

Section titled “2.1.3 确认 3：Windows 用户要注意”

如果你用的是 Windows，官方建议通过 WSL2（Windows 上的 Linux 子系统）来运行命令，这样兼容性最好。

至于怎么装 WSL2，可以先搜一下“Windows WSL2 安装”，或者直接看官方文档：https://github.com/openclaw/openclaw

2.1.4 如果 Node 没装或者版本太低，怎么装

Section titled “2.1.4 如果 Node 没装或者版本太低，怎么装”

如果你执行 node --version 提示“command not found”，说明 Node 还没装。如果版本低于 v22，也需要升级。按你的系统选下面一种方式：

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 验证 Node 和 npm 都装好了

Section titled “2.1.5 验证 Node 和 npm 都装好了”

装完以后，执行下面两条命令确认：

Terminal window
node --version
npm --version

判断标准：

  • node --version 返回 v22.x.x 或更高
  • npm --version 返回一个版本号（任意正常数字都行）

小贴士：每次只复制执行当前这一步需要的命令，不要把安装和验证一起复制粘贴。如果提示命令找不到，检查一下 npm 全局路径有没有加到 PATH 里（可以用 npm prefix -g 查看）。

2.2 安装 OpenClaw（跟着向导走）

Section titled “2.2 安装 OpenClaw（跟着向导走）”

2.2.1 推荐方式：向导安装

Section titled “2.2.1 推荐方式：向导安装”

官方给出的首选路径是运行向导命令。简单理解就是“让程序一步步问你问题，你回答就行”。

如果你本机还没有 openclaw 命令，先装一下 CLI（命令行工具）：

Terminal window
npm install -g openclaw@latest

然后执行向导：

Terminal window
openclaw onboard --install-daemon

--install-daemon 这个参数的意思是“把 Gateway 的后台服务装上”，这样它才能在后台一直运行。

官方文档参考：

2.2.2 安装过程中的两种情况

Section titled “2.2.2 安装过程中的两种情况”
正常情况：一步到位
Section titled “正常情况：一步到位”

先执行 CLI 安装命令：

Terminal window
npm install -g openclaw@latest

执行时重点看三类提示：

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

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

异常情况：遇到 EACCES 权限错误（Ubuntu / Debian）
Section titled “异常情况：遇到 EACCES 权限错误（Ubuntu / Debian）”

如果你在 Ubuntu 或 Debian 上执行安装命令时出现 EACCES: permission denied（大致意思是“没有权限写入系统目录”），可以先用临时方案：

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 选一个）：

bash 用户：

Terminal window
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc

zsh 用户：

Terminal window
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
  1. 让 PATH 生效：

bash 用户：

Terminal window
source ~/.bashrc

zsh 用户：

Terminal window
source ~/.zshrc
  1. 重新安装 OpenClaw（这次不用 sudo）：
Terminal window
npm install -g openclaw@latest
  1. 最后验证：
Terminal window
which openclaw
openclaw --version

2.2.3 向导里到底问什么（逐项说明）

Section titled “2.2.3 向导里到底问什么（逐项说明）”

这部分按向导的真实提示文案来写，和你终端里看到的应该是一一对应的。

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

Terminal window
openclaw onboard --install-daemon

下面按步骤来解释每个问题是什么意思、该怎么选。

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。

  3. Existing config detected（如果之前装过）
    会显示当前配置摘要。

  4. Config handling
    三个选项：

    • Use existing values（推荐：先用现有的）
    • Update values（在现有配置上改）
    • Reset（谨慎使用，会清空配置）

    如果选 Reset，还会问 Reset scope（重置范围）：

    • Config only（只清配置）
    • Config + creds + sessions（清配置、凭证、会话）
    • Full reset（全部清空）

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

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

  6. Model/auth provider（重要！这是选模型的地方）
    这里选你要用的 AI 模型提供商。建议首次先把模型配好，别选 Skip for now。

    下面是中国大陆读者的推荐选择：

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

    • 步骤：Model/auth provider 选 MiniMax → MiniMax auth method 选 MiniMax OAuth (Coding Plan) → Select MiniMax endpoint 选 CN
    • 默认模型通常是 minimax/MiniMax-M2.5

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

    • 步骤：Model/auth provider 选 Z.AI → Z.AI auth method 选 Coding-Plan-CN
    • 输入 API Key
    • 完成后确认默认模型为 zai/glm-5；如果不是，执行 openclaw models set zai/glm-5

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

    • 步骤：Model/auth provider 选 Moonshot AI (Kimi K2.5) → Moonshot AI auth method 选 Kimi Code API key (subscription)
    • 输入 Kimi Coding API Key
    • 默认模型是 kimi-coding/k2p5（这就是 K2.5）

  7. Channel status
    显示各渠道（微信、飞书、Slack 等）是否已配置。

  8. Select channel (QuickStart)
    这里让你选要接入哪个聊天平台。常见选项包括 Telegram、WhatsApp、Discord、IRC、Google Chat、Slack、Signal、iMessage，以及飞书、Matrix 等插件渠道。

    建议：首次选 Skip for now。先把“本地 Web UI 能稳定对话”这条主线跑通，再进入第 8 章（飞书）等渠道接入章节。

  9. Skills status / Configure skills now?
    建议选 Yes，按默认走。如果提示缺依赖，按提示安装就行，后续可以再调整。

2.2.3.2 Manual 路径（比 QuickStart 多一些选项）
Section titled “2.2.3.2 Manual 路径（比 QuickStart 多一些选项）”

如果不小心选了 Manual，会多出这些问题：

  • What do you want to set up?：选 Local gateway（本地网关）
  • Workspace directory：可以自定义，也可以用默认
  • Gateway 逐项配置（Manual 模式才会逐个问）：
    • Gateway port（端口）
    • Gateway bind（绑定地址：Loopback / LAN / Tailnet 等）
    • Gateway auth（鉴权方式：Token / Password）
    • Tailscale exposure（是否暴露到公网）
  • 渠道配置流程变成手动选择

结论：向导步骤请以终端原文为准；本节已经和源码提示名对齐，不会造成误解。

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 必填配置项”

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

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

下面是一张“最小可用清单”：

Provider向导里建议选择默认模型落点
MiniMaxMiniMax → MiniMax OAuth → CNminimax/MiniMax-M2.5
Zhipu/GLMZ.AI → Coding-Plan-CNzai/glm-5
Moonshot/KimiMoonshot AI (Kimi K2.5) → Kimi Code API key (subscription)kimi-coding/k2p5

2.3.2 参数建议保持默认

Section titled “2.3.2 参数建议保持默认”

对新手最稳的做法是先保持这些默认：

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

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

如果你已经跑过一次向导，想改配置，可以直接再执行：

Terminal window
openclaw onboard

然后在 Existing config detected → Config handling 里选 Update values，只改模型和鉴权，其他保持不变。

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. 检查本地端口有没有在监听（按系统选一个）：

macOS：

Terminal window
lsof -iTCP:18789 -sTCP:LISTEN

Linux：

Terminal window
ss -ltnp | rg 18789

如果 models status 正常、模型列表里有目标 provider、18789 端口在监听，那说明配置已经生效，可以进入下一步：第一次对话。

2.4 启动与第一次对话

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

2.4.1 向导结束时的选项

Section titled “2.4.1 向导结束时的选项”

在 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不离开终端，调试方便在 TUI 里直接发“给我 3 条今天可执行待办”
现在不方便测试Do this later先完成安装，后续再试稍后执行 openclaw dashboard --no-open 或 openclaw tui
远程服务器/无图形界面Hatch in TUI 或 Do this later避免浏览器打不开先执行 openclaw tui

本书建议：

  • 新手主线选 Open the Web UI（更直观，便于截图和复盘）
  • 偏终端工作流可以选 Hatch in TUI
  • 如果选了 Do this later，可以手动启动：
Terminal window
openclaw dashboard --no-open
# 或者
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 打开网页发第一条消息

Section titled “2.4.3 打开网页发第一条消息”

在浏览器打开：

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

请给我一个“今天就能执行”的 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 个坑”

坑 1：端口与权限问题

Section titled “坑 1：端口与权限问题”

常见现象：

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

怎么办：

  1. 用 lsof -iTCP:18789 -sTCP:LISTEN（macOS）或 ss -ltnp | rg 18789（Linux）看看谁占用了端口
  2. 确认你不是在受限目录执行（特别是公司电脑）
  3. 临时换端口试试：openclaw gateway --port 18889 --verbose

坑 2：密钥与模型调用问题

Section titled “坑 2：密钥与模型调用问题”

常见现象：

  • 页面能打开，但一直无回复
  • 返回 401、403、429 这些错误码
  • 返回“模型不存在”或“无权限”

怎么办：

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

坑 3：代理与网络问题

Section titled “坑 3：代理与网络问题”

常见现象：

  • 安装阶段下载超时
  • 启动后请求一直 pending（卡住）
  • 同样的配置在别的网络能用、在当前网络不能用

怎么办：

  1. 先确认文档和安装地址能访问（2.1.2 节）
  2. 分清楚是“本地服务没启动”还是“外部模型不可达”
  3. 在公司网络下，先跟网管确认出站策略，别盲目反复试

坑 4：Node 版本不对

Section titled “坑 4：Node 版本不对”

常见现象：

  • 安装时报“Node 版本不满足要求”
  • 启动时报类似错误

怎么办：

  • 回到 2.1.4 节，把 Node 升级到 v22 以上

坑 5：Windows 环境问题

Section titled “坑 5：Windows 环境问题”

常见现象：

  • 各种奇怪报错
  • 命令执行结果和教程不一样

怎么办：

  • 确认是否用了 WSL2（Windows 推荐方式）
  • 如果没用 WSL2，切到 WSL2 终端按同样步骤重走

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

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

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

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 页面获取 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
  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 路径，再配置渠道。