openclaw.html

OpenClaw 是开源 AI Agent 平台，支持 Node.js 22+/24+。通过胜算云统一接口，一个 Key 可调用数百种模型，并可与官方模型并存。本文从安装 → 三种配置方式（Web to Agent / CC-Switch / 手动改配置）→ 测试与换模型，一步步带完。

一、安装 OpenClaw

OpenClaw 通过 npm 安装，需要 Node.js 22.14 或 24+。国内用户推荐中文优化版。

方式 1：中文优化版（推荐国内用户）

npm install -g @qingchencloud/openclaw-zh@latest

方式 2：官方版

npm install -g openclaw@latest

验证安装

node -v          # 需 >= 22.14 或 24+
openclaw --version

能看到版本号即安装成功。

方式 A · Web to Agent 一键写入（推荐，浏览器内完成）

无需手动编辑配置文件：在下面卡片里输入胜算云 Key，组件自动拉取全部可用模型，授权 .openclaw 目录后一键写入 openclaw.json（合并写入，保留其它供应商配置）。

在上方卡片输入胜算云 Key（旁边「🗝 控制台获取 Key」可直达密钥页）。
组件自动拉取模型列表，下拉选择默认模型（推荐 anthropic/claude-opus-4.8）。
点「写入配置」，授权访问 .openclaw 目录（Win: C:\Users\<你>\.openclaw；mac/linux: ~/.openclaw）。
写入完成会自动备份原文件，然后运行 openclaw gateway restart 使配置生效。

💡

组件会按模型自动匹配协议：选 Claude 用 anthropic-messages（baseUrl 为 /api）；选 GPT 等用 openai-completions（baseUrl 为 /api/v1），与 CC-Switch 预设一致。

方式 B · CC-Switch 桌面工具配置

CC-Switch 是桌面 GUI 工具，可管理多套供应商配置并一键切换。

1. 下载安装 CC-Switch

按你的系统选择推荐安装包，点击直接下载（均为 v3.18.0 稳定版）：

Windows：推荐 CC-Switch-v3.18.0-Windows.msi（MSI 安装包，支持自动更新）；或便携版 zip（解压即用，不写注册表）。Windows ARM64 设备请选文件名带 arm64 的对应制品。
macOS：推荐 CC-Switch-v3.18.0-macOS.dmg（拖入 Applications 即可）；或 zip 版（Universal Binary），tar.gz 用于 Homebrew 安装与自动更新。
Linux / 其他平台 / 历史版本：前往 Releases v3.18.0 页面查看全部制品。

2. 配置胜算云（详细步骤）

打开 CC-Switch，进入「供应商」管理页，工具选 OpenClaw，点「新增供应商」。
在供应商列表中选择「胜算云」，API Key 和 Base URL 会自动填充。
粘贴你的胜算云 API Key，点「获取模型列表」拉取可用模型。
从模型列表里选择默认模型（推荐 anthropic/claude-opus-4.8）。
勾选「写入通用配置」，CC-Switch 自动合并写入 openclaw.json。
点「启用 / 保存」，然后运行 openclaw gateway restart 使配置生效。

3. CC-Switch 配置注意事项

⚠

给 OpenClaw 用 CC-Switch，务必确认以下设置：

选「胜算云」供应商后，API Key 和 Base URL 会自动填充，不要手动改。
选 Claude 模型时协议为 anthropic-messages（Base URL 不带 /v1）；选 GPT 等模型时为 openai-completions（Base URL 带 /v1），CC-Switch 会自动切换。
必须勾选「写入通用配置」才能覆盖旧配置，否则改了不生效。
写入后需运行 openclaw gateway restart 才能让新配置生效。

方式 C · 手动修改配置文件

直接编辑 openclaw.json（位置：mac/linux ~/.openclaw/openclaw.json；Win C:\Users\<你>\.openclaw\openclaw.json）。推荐备份后再编辑。

1. 写入配置（以 Claude 模型为例）

{
  "models": {
    "mode": "merge",
    "providers": {
      "shengsuanyun": {
        "baseUrl": "https://router.shengsuanyun.com/api",
        "apiKey": "sk-你的胜算云API Key",
        "api": "anthropic-messages",
        "models": [
          { "id": "anthropic/claude-opus-4.8", "name": "Claude Opus 4.8" },
          { "id": "anthropic/claude-sonnet-5", "name": "Claude Sonnet 5" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "shengsuanyun/anthropic/claude-opus-4.8"
      }
    }
  }
}

若用 GPT 等模型，把 baseUrl 改成 https://router.shengsuanyun.com/api/v1，api 改成 "openai-completions"。

2. 重启生效

openclaw gateway restart
openclaw config validate

3. 配置项详细解析：为什么这么改 & 这样改有什么用

OpenClaw 启动时读 openclaw.json，决定模型库、供应商、默认模型。每个字段作用如下：

models.mode = "merge"
作用：把胜算云模型合并进模型库，而非替换。
为什么：merge 模式下官方模型和胜算云模型共存，你可以随时切换；用 replace 会清空官方模型。

models.providers.shengsuanyun
作用：自建一个名为 shengsuanyun 的供应商。
为什么：OpenClaw 不内置胜算云，需自建供应商把请求指向胜算云。

baseUrl
作用：供应商 API 地址。
为什么：用 Claude（anthropic-messages）时填 https://router.shengsuanyun.com/api（不带 /v1，OpenClaw 会请求 /v1/messages）；用 GPT 等（openai-completions）时填 /api/v1（带 /v1，请求 /chat/completions）。

api
作用：调用协议。
为什么：必须和模型 + baseUrl 三者匹配。Claude 用 anthropic-messages，GPT 等用 openai-completions；选错协议会请求错端点导致失败。

models（数组）
作用：声明该供应商下可用的模型清单。
为什么：只有写进这里的模型才会在 OpenClaw 里可选；id 要和胜算云控制台一致。

agents.defaults.model.primary
作用：默认主模型，格式 供应商名/模型ID。
为什么：Agent 执行任务时默认用这个模型；前缀 shengsuanyun/ 指向上面自建的供应商。

4. CLI 快捷命令（不写文件，逐项设置）

openclaw config set models.providers.shengsuanyun.baseUrl "https://router.shengsuanyun.com/api"
openclaw config set models.providers.shengsuanyun.apiKey "sk-你的胜算云API Key"
openclaw config set models.providers.shengsuanyun.api "anthropic-messages"
openclaw config set agents.defaults.model.primary "shengsuanyun/anthropic/claude-opus-4.8"
openclaw gateway restart

首次运行与测试

查看网关状态：
```
openclaw gateway status
```
打开仪表板（浏览器访问 http://127.0.0.1:18789）：
```
openclaw dashboard
```
CLI 测试对话：
```
openclaw tui chat
```

📸 截图位置：openclaw tui chat 对话界面

如何更换模型

临时切换：在仪表板或 TUI 里选另一个模型。
永久修改：编辑 openclaw.json 的 agents.defaults.model.primary，或运行 openclaw config set agents.defaults.model.primary "shengsuanyun/模型ID"，然后 openclaw gateway restart。
交互式面板：运行 openclaw config 进可视化面板修改。

常见问题排查

调用报错 / 协议不匹配 → api 和 baseUrl 要配套：Claude 用 anthropic-messages + /api，GPT 用 openai-completions + /api/v1。
改了配置没生效 → 必须运行 openclaw gateway restart。
官方模型不见了 → 确认 models.mode 是 "merge" 而非 "replace"。
Node 版本不够 → 需 22.14 或 24+，node -v 检查。
更新 → npm update -g openclaw@latest 后重新运行 openclaw onboard。