OpenClaw 配置教程

OpenClaw 是一个本地优先的个人 AI agent / Gateway：它在本机跑一个 Gateway 服务，接入聊天频道（Telegram / Discord / Slack 等）与各类工具，并通过任意模型提供方驱动 agent。OpenClaw 支持 Anthropic 兼容 的自定义提供方，因此可以直接接到 PrimeRouter 中转站——所有请求都走你的 PrimeRouter 令牌、余额、调用日志和计费规则。

本教程覆盖 macOS / Linux / Windows 三个平台，从安装 Node.js、安装 OpenClaw、配置 PrimeRouter，一直到本地 Gateway 服务跑通、agent 调试成功。

适用环境

OpenClaw 2026.6.10 及以上
Node.js v22.19+（OpenClaw 硬性要求）
PrimeRouter 提供 Anthropic 兼容接口
示例模型：claude-opus-4-8

开始前请先准备好 PrimeRouter API Key（参考通用准备）。

总览：六步跑通

步骤	操作
1	准备 Node.js `v22.19+`
2	`npm install -g openclaw@latest`
3	在 PrimeRouter 控制台创建令牌
4	运行 `openclaw onboard` 向导，选 Custom Provider + 兼容 Anthropic
5	安装本地 Gateway 后台服务
6	启动 agent / 打开 Control UI 验证

1. 准备 Node.js（v22.19+）

OpenClaw 要求 Node.js v22.19+。版本过低会看到类似报错：

text

openclaw: Node.js v22.19+ is required (current: v22.12.0).

推荐直接安装官方 Node.js LTS（v22 或更高），不需要额外的版本管理器：

macOS（Homebrew）Windows（winget）Linux（NodeSource）

bash

brew install node          # 安装最新稳定版 Node（≥ v22）
node -v                    # 期望 v22.19.0 或更高

powershell

winget install OpenJS.NodeJS.LTS
# 或到 https://nodejs.org/ 下载 .msi 安装包，双击安装
node -v                    # 期望 v22.19.0 或更高

bash

# Debian / Ubuntu，安装系统级 Node 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v                    # 期望 v22.19.0 或更高

也可以用 PrimeRouter 一键脚本

PrimeRouter 提供了自动检测并安装 Node LTS 的脚本（macOS 用 Homebrew、Linux 用 NodeSource、Windows 用 winget），检测到 Node 22+ 已存在时会直接跳过。详见 Node.js 环境安装：

bash

# macOS / Linux / WSL
curl -fsSL https://primerouter.ai/install/nodejs.sh | bash

powershell

# Windows PowerShell
irm https://primerouter.ai/install/nodejs.ps1 | iex

2. 安装 OpenClaw

全平台都用 npm 全局安装：

bash

npm install -g openclaw@latest
openclaw --version   # 期望输出 OpenClaw 2026.6.10 (xxxxxxx) 或更高

升级 Node 后 command not found: openclaw

全局包绑定在安装时的 Node 上。如果你升级或更换了 Node（尤其是大版本变化），需要在新的 Node 下重新执行一次 npm install -g openclaw@latest。

3. 创建 PrimeRouter 令牌

打开 PrimeRouter 控制台令牌页。
点击创建令牌，建议为 OpenClaw 单独建一个，便于后续查日志、限模型或单独停用。
复制 sk-... 令牌。令牌只完整展示一次，请妥善保存。

4. 运行初始化向导并配置 PrimeRouter

OpenClaw 用 onboard 向导完成首次配置。加上 --install-daemon 会顺带把 Gateway 安装成后台服务：

macOS / LinuxWindows PowerShell

bash

OPENCLAW_LOCALE=zh-CN openclaw onboard --install-daemon

powershell

$env:OPENCLAW_LOCALE = "zh-CN"
openclaw onboard --install-daemon

想用英文界面就去掉 OPENCLAW_LOCALE=zh-CN。

4.1 基础选择

向导会逐步询问，按下表选择即可：

提示	选择
我理解 OpenClaw 默认面向个人使用…继续？	Yes
设置模式	QuickStart（推荐）

QuickStart 的默认配置适合本机安全调试：

text

Gateway 端口：18789
Gateway 绑定：Loopback (127.0.0.1)
Gateway 认证：令牌（默认）
Tailscale 暴露方式：关闭

4.2 选择模型提供方（关键步骤）

在 Model/auth provider 步骤，不要选 Anthropic → Anthropic Claude CLI——那个选项要求本机已登录官方 Claude CLI，否则会报：

text

Error: Claude CLI is not authenticated on this host.
Run claude auth login first, then re-run this setup.

PrimeRouter 是中转站，正确路径是自定义提供方：

text

Model/auth provider → More…
Model/auth provider → Custom Provider

然后按下表填写：

提示	填写内容
API 基础 URL	`https://primerouter.ai`
How do you want to provide this API key?	Paste API key now
API Key	粘贴第 3 步的 PrimeRouter 令牌
端点兼容性	兼容 Anthropic
模型 ID	`claude-opus-4-8`

向导会立即发一条验证请求。看到下面的输出即代表 PrimeRouter 通了：

text

验证成功。

继续填写端点信息：

提示	填写内容
端点 ID	`primerouter`
模型别名（可选）	`claude-opus-4-8`

成功时会打印：

text

Configured custom provider: primerouter/claude-opus-4-8

完整模型列表

示例用的是 claude-opus-4-8，你也可以填 PrimeRouter 控制台里任意可用模型，详见可用模型。

4.3 频道 / 搜索 / 技能 / Hooks 先跳过

第一次只为把本地链路跑通，下面这些都可以先跳过，之后再单独配置：

提示	选择
选择频道（QuickStart）	暂时跳过
搜索提供方	暂时跳过
现在配置技能？（推荐）	No
启用 hooks？	暂时跳过

Hooks 是复选框界面

启用 hooks？ 是多选界面，直接回车可能报 Please select at least one option.。操作方式：方向键移到 暂时跳过 → 按 Space 选中 → 按 Enter 提交。

5. 安装本地 Gateway 后台服务

Gateway 是 OpenClaw 的常驻进程——agent、Control UI、各聊天频道都连到它。--install-daemon 会把它注册成开机自启、后台常驻的系统服务，关掉终端也照样在跑。

一句话：你不用记各平台细节

不同系统底层用的服务机制不一样（macOS 是 launchd，Linux 是 systemd），但管理命令是跨平台统一的。装完只要一句 openclaw gateway status 确认在运行即可，下面那张平台对照表只是给你排查日志时用。

安装成功后向导会打印服务和日志路径。以 macOS 为例：

text

Installed LaunchAgent: ~/Library/LaunchAgents/ai.openclaw.gateway.plist
Logs: ~/Library/Logs/openclaw/gateway.log
Gateway 服务已安装。

各平台对照（仅用于排查 / 找日志，具体路径以向导实际打印为准）：

平台	服务机制	默认日志位置
macOS	launchd LaunchAgent	`~/Library/Logs/openclaw/gateway.log`
Linux	systemd user service	`journalctl --user -u openclaw*`
Windows	后台服务 / 启动项	见向导打印的路径

管理 Gateway 用同一套命令，不用关心底层是 launchd 还是 systemd：

bash

openclaw gateway status     # 是否在运行（首选验证方式）
openclaw gateway restart    # 重启
openclaw gateway stop       # 停止
openclaw gateway start      # 启动
openclaw gateway install    # 重新注册后台服务（没装成功时用）

系统残留旧版 Node 时

如果机器上还有一个低于 22.19 的旧 Node（例如 /usr/local/bin/node），向导可能提示：

text

System Node 18.16.0 at /usr/local/bin/node is below the required Node 22.19+.

按第 1 步把系统 Node 升到 22 LTS（或更高）后，重新运行向导即可让 daemon 用上新版 Node。

6. 打开 Control UI

向导完成后会显示本地 Control UI 地址：

text

Web UI：http://127.0.0.1:18789/
Gateway WS：ws://127.0.0.1:18789
Gateway：可访问

打开 dashboard：

bash

openclaw dashboard            # 自动打开浏览器
openclaw dashboard --no-open  # 只打印 URL，不自动打开

如果 Web UI 要求 token，可查看：

bash

openclaw config get gateway.auth.token

打开后就是 OpenClaw 的 Control UI——左侧是会话 / 概览 / 活动 / 实例等面板，中间是与 agent 的聊天，底部能看到当前模型（claude-opus-4-8）和上下文用量：

OpenClaw Control UI 聊天界面

不要外泄令牌

带 token 的 dashboard URL 等同于网关的完整访问权限，不要把它发给任何人，也不要贴到聊天 / issue 里。

7. 启动并调试 agent

向导最后会问 你想如何启动 agent？，选 在终端中启动（推荐），会进入 TUI：

bash

openclaw tui

第一次会自动发送一条 醒醒，我的朋友！，agent 用 primerouter/claude-opus-4-8 回复即代表整条链路打通。TUI 底部状态栏会显示当前模型与 token 用量，例如：

text

agent main | session main | primerouter/claude-opus-4-8 | tokens 19k/128k (15%)

也可以退出 TUI，用一次性命令验证：

bash

openclaw agent --message "请用一句话确认你已经通过 PrimeRouter 正常工作" --thinking high

回到 PrimeRouter 控制台 → 调用日志，应能看到对应的 claude-opus-4-8 请求记录——这是「请求确实走了 PrimeRouter」的最终证据。

8. 日常运维命令

体检与状态检查：

bash

openclaw doctor                          # 体检：环境 / 配置 / 网关一把过
openclaw gateway status                  # 网关是否在运行
openclaw config get gateway.auth.token   # 查看网关令牌

网关的启动 / 重启 / 停止命令见第 5 节。

9. 关于聊天频道（含微信）

OpenClaw 支持 Telegram / Discord / Slack / 微信（Weixin）等大量频道。建议先把本地 Gateway + PrimeRouter + 终端 agent 跑通，再单独配置频道。

上手最简单的是 Telegram（在 @BotFather 注册 bot 即可）。
微信个人号通常涉及扫码登录、账号风控、消息权限与会话安全，比主流 IM 更容易受平台策略影响，建议放到最后，确认无误再开。
开启任何入站频道前，保持 Gateway 只绑定 127.0.0.1、不公网暴露，并开启配对 / 允许列表。

10. 常见问题

现象	原因	处理
`Node.js v22.19+ is required`	Node 版本过低	按第 1 步安装 / 升级到 Node 22 LTS，再重装 OpenClaw
`command not found: openclaw`	升级 Node 后全局包未重装	在当前 Node 下重新 `npm install -g openclaw@latest`
`Claude CLI is not authenticated`	选错了 `Anthropic Claude CLI`	改选 `More… → Custom Provider`
验证失败 / 401	PrimeRouter 令牌错误或被禁用	重新创建令牌，确认完整复制
验证失败 / 404 model	模型 ID 写错或令牌分组无权限	在可用模型确认 ID
`Please select at least one option.`	Hooks 复选框直接回车	用 `Space` 选中 `暂时跳过` 再回车
Web UI 要求 token	未带令牌访问	`openclaw config get gateway.auth.token` 取令牌

11. 安全建议

OpenClaw 能连模型、读文件、执行工具，请至少遵守：

Gateway 保持绑定 127.0.0.1，不要公网暴露
不要把 PrimeRouter 令牌、OpenClaw gateway token 发给别人
多用户 / 公开频道不要共用同一个高权限 agent
不熟悉前不要启用过多工具和技能
定期运行安全检查：

bash

openclaw security audit --deep
openclaw security audit --fix

12. 本次成功状态摘要

text

Node.js:       v22.23.1
OpenClaw:      2026.6.10
Provider:      Custom Provider
API Base URL:  https://primerouter.ai
Compatibility: 兼容 Anthropic
Model ID:      claude-opus-4-8
Endpoint ID:   primerouter
Gateway:       http://127.0.0.1:18789/

13. 完整终端记录（脱敏）

下面是一次从安装到调试成功的完整终端记录，所有敏感信息已脱敏：sk-prouter-**** 是 PrimeRouter 令牌，#token=**** 是 Gateway / Control UI 共享认证令牌（等同完整访问权限，切勿外发），路径里的用户名统一用 ~/ 代替。

点击展开完整终端记录

console

# ── 1. 确认 Node.js 版本（OpenClaw 要求 v22.19+）──────────────────────────
$ node -v
v22.23.1

# ── 2. 全局安装 OpenClaw ─────────────────────────────────────────────────
$ npm install -g openclaw@latest
added 1 package in 12s

$ openclaw --version
OpenClaw 2026.6.10 (aa69b12)

# ── 3. 运行初始化向导，并安装为后台 Gateway 服务 ─────────────────────────
$ OPENCLAW_LOCALE=zh-CN openclaw onboard --install-daemon

┌  OpenClaw 设置
│
◇  安全免责声明 …… 继续？        │  Yes
◇  设置模式                       │  QuickStart（推荐）
│
◇  QuickStart
│  Gateway 端口：18789
│  Gateway 绑定：Loopback (127.0.0.1)
│  Gateway 认证：令牌（默认）
│  Tailscale 暴露方式：关闭
│
◇  Model/auth provider           │  More…
◇  Model/auth provider           │  Custom Provider
◇  API 基础 URL                  │  https://primerouter.ai
◇  How do you want to provide this API key?  │  Paste API key now
◇  API Key（不需要可留空）       │  sk-prouter-****************************
◇  端点兼容性                    │  兼容 Anthropic
◇  模型 ID                       │  claude-opus-4-8
◇  验证成功。
◇  端点 ID                       │  primerouter
◇  模型别名（可选）              │  claude-opus-4-8
│
Configured custom provider: primerouter/claude-opus-4-8

# ── 频道 / 搜索 / 技能 / Hooks 首次全部跳过 ──────────────────────────────
◇  选择频道（QuickStart）        │  暂时跳过
◇  搜索提供方                    │  暂时跳过
◇  现在配置技能？（推荐）        │  No
◇  启用 hooks？                  │  暂时跳过      # 复选框：Space 选中 → Enter 提交

Updated config: ~/.openclaw/openclaw.json
Workspace OK:   ~/.openclaw/workspace
Sessions OK:    ~/.openclaw/agents/main/sessions

# ── 4. 安装 Gateway 后台服务（macOS = LaunchAgent）──────────────────────
Installed LaunchAgent: ~/Library/LaunchAgents/ai.openclaw.gateway.plist
Logs:                  ~/Library/Logs/openclaw/gateway.log
◇  Gateway 服务已安装。

# ── 5. Control UI 地址（令牌已脱敏）─────────────────────────────────────
Web UI：          http://127.0.0.1:18789/
Web UI（含令牌）：http://127.0.0.1:18789/#token=****************************************
Gateway WS：      ws://127.0.0.1:18789
Gateway：         可访问

◇  你想如何启动 agent？          │  在终端中启动（推荐）

# ── 6. 进入 TUI，验证 agent 走 PrimeRouter ──────────────────────────────
$ openclaw tui
 openclaw tui - local embedded - agent main - session main

醒醒，我的朋友！
> 你是谁啊？
（agent 正常回复……）

 local ready | idle
 agent main | session main | primerouter/claude-opus-4-8 | tokens 19k/128k (15%)

# ── 运维 / 自检命令（可单独执行）────────────────────────────────────────
$ openclaw agent --message "请用一句话确认你已经通过 PrimeRouter 正常工作" --thinking high
已通过 PrimeRouter（primerouter/claude-opus-4-8）正常工作。

$ openclaw doctor
$ openclaw gateway status

$ openclaw config get gateway.auth.token        # 输出已脱敏，请勿外发
****************************************

$ openclaw dashboard --no-open
http://127.0.0.1:18789/#token=****************************************

$ openclaw gateway restart
$ openclaw gateway stop

下一步

在控制台令牌页管理 OpenClaw 专用令牌。
在调用日志确认 OpenClaw 请求已进入 PrimeRouter。
在可用模型切换适合 agent 任务的模型。

OpenClaw 配置教程 ​

总览：六步跑通 ​

1. 准备 Node.js（v22.19+） ​

2. 安装 OpenClaw ​

3. 创建 PrimeRouter 令牌 ​

4. 运行初始化向导并配置 PrimeRouter ​

4.1 基础选择 ​

4.2 选择模型提供方（关键步骤） ​

4.3 频道 / 搜索 / 技能 / Hooks 先跳过 ​

5. 安装本地 Gateway 后台服务 ​

6. 打开 Control UI ​

7. 启动并调试 agent ​

8. 日常运维命令 ​

9. 关于聊天频道（含微信） ​

10. 常见问题 ​

11. 安全建议 ​

12. 本次成功状态摘要 ​

13. 完整终端记录（脱敏） ​

下一步 ​

OpenClaw 配置教程

总览：六步跑通

1. 准备 Node.js（v22.19+）

2. 安装 OpenClaw

3. 创建 PrimeRouter 令牌

4. 运行初始化向导并配置 PrimeRouter

4.1 基础选择

4.2 选择模型提供方（关键步骤）

4.3 频道 / 搜索 / 技能 / Hooks 先跳过

5. 安装本地 Gateway 后台服务

6. 打开 Control UI

7. 启动并调试 agent

8. 日常运维命令

9. 关于聊天频道（含微信）

10. 常见问题

11. 安全建议

12. 本次成功状态摘要

13. 完整终端记录（脱敏）

下一步