【OpenClaw 第 2 篇】一行命令装起来:从 onboard 到第一条消息

很多开源项目的安装文档能把人劝退。OpenClaw 的 onboard 流程是个例外。

上一篇聊了为什么你需要一个个人 AI Agent。这篇直接动手——从零开始，把 OpenClaw 跑起来。

前置环境

OpenClaw 是 TypeScript 写的，运行在 Node.js 上。官方推荐：

• Node.js 24（推荐）

– Node.js 22.16+（最低）

macOS 用户建议用 nvm 或 fnm 管理 Node 版本。Linux 用户可以直接用 NodeSource 仓库。Windows 用户——强烈建议使用 WSL2，原生 Windows 不是推荐路径。

安装与 onboard

一行命令：

1
npm install -g openclaw@latest

支持 npm、pnpm、bun 三种包管理器。

然后运行 onboard 引导：

1
openclaw onboard --install-daemon

这一步会做几件事：

1. 创建配置文件~/.openclaw/openclaw.json

2. 初始化 workspace，生成 AGENTS.md、SOUL.md、TOOLS.md 等引导文件

3. 引导你配置至少一个 AI 模型 Provider

4. 引导你连接至少一个聊天渠道（Telegram / Discord / WhatsApp 等）

5. 安装 Gateway 守护进程（macOS 用 launchd，Linux 用 systemd）

整个过程是交互式的终端向导，每一步都有提示。不算下载时间，5 分钟能走完。

最小配置文件

如果你不想走 onboard，手写最小配置也可以。~/.openclaw/openclaw.json：

1
2
3
4
5
{  agent: {    model: "anthropic/claude-sonnet-4",  },}

只需要指定一个模型。OpenClaw 会自动从 ~/.openclaw/auth.json 读取 API Key（onboard 过程中已配置）。

模型格式是 /。支持的 Provider 包括 OpenAI、Anthropic、Google、DeepSeek、MiniMax、通义千问等。完整的模型配置见官方文档。

启动 Gateway

Gateway 是 OpenClaw 的核心——它是一个常驻后台的控制平面：

1
openclaw gateway --port 18789 --verbose

– --port 18789：Gateway 监听端口

– --verbose：打印详细日志，调试时很有用

如果 onboard 时选择了 --install-daemon，Gateway 已经作为系统服务在运行了。可以用以下命令检查状态：

1
2
launchctl list | grep openclaw   # macOSsystemctl --user status openclaw # Linux

发送第一条消息

Gateway 跑起来后，验证它是否正常工作：

1
openclaw message send --target +1234567890 --message "Hello from OpenClaw"

这会通过你配置的渠道（比如 WhatsApp）发送一条消息。--target 是接收者的 ID。

与 Agent 对话

测试 Agent 的推理能力：

1
openclaw agent --message "Ship checklist" --thinking high

– --message：你的指令

– --thinking high：启用深度思考模式（适合复杂任务）

--thinking 有多个级别：off、low、medium、high。日常简单对话可以不加这个参数，复杂推理建议用 high。

常用运维命令

1
2
3
4
5
6
7
8
9
10
11
# 诊断工具——遇到问题先跑这个openclaw doctor# 安全检查——检查 DM Policy 等配置openclaw security audit# 更新到最新版openclaw update --channel stable# 切换到 beta 频道openclaw update --channel beta

OpenClaw 有三个发布频道：

• stable：正式发布版（npm dist-tag latest）

• beta：预发布版

• dev：main 分支最新提交

大多数用户用 stable 就够了。想尝鲜又有一定折腾能力，可以切 beta。

源码安装（开发者）

如果你想改代码或贡献 PR：

1
2
3
4
5
6
7
git clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm openclaw setuppnpm ui:build        # 构建 Web 控制台pnpm gateway:watch   # 开发模式，自动重载

注意：源码安装只能用 pnpm，npm install 在仓库根目录不是受支持的路径。

排坑指南

笔者在实际安装中踩过的坑：

1. Node 版本太低：如果用的是 Node 20 或更早版本，部分依赖会报错。务必升级到 Node 22.16+。运行 node --version 确认。

2. daemon 启动失败：macOS 上如果 launchd 报权限错误，运行 openclaw onboard --install-daemon 重新注册。

3. Gateway 端口被占用：18789 被占的话换一个端口，比如 --port 18790。

4. API Key 未配置：onboard 没走完或跳过了 Provider 配置。检查 ~/.openclaw/auth.json 是否存在且包含有效凭证。

5. 诊断优先：不管遇到什么问题，第一反应应该是跑 openclaw doctor。它会列出配置问题、权限风险、版本兼容性。

下一步

Gateway 跑起来、第一条消息发出去了。下一篇，我们深入 OpenClaw 的记忆系统——它是怎么做到跨会话记住你的偏好和上下文的。这个机制是整个 Agent 体验的基石。

你安装过程中踩了什么坑？留言分享，帮助后来者少走弯路。