Clawdbot 自定义中转站文档配置教程

# OpenClaw / Clawdbot 自定义中转站配置教程

> 中转平台地址：`https://api.zaimod.com`  
> 支持协议：OpenAI（Chat Completions）、Anthropic（Messages）、Google（Gemini）  
> 适用端：Windows / macOS / Linux（需 Node.js 环境）

本篇用一个中转站同时接入 GPT、Claude、Gemini 三类模型：先装 CLI 并初始化，再改两个 JSON 文件（一个管模型，一个管密钥），最后用 `doctor` 体检、`gateway` 启动。

---

## 一、准备工作

### 1.1 环境与命令名

| 项目      | 说明                                                                          |
| ------- | --------------------------------------------------------------------------- |
| Node.js | 已安装 Node.js 环境（建议 20 LTS 及以上）                                               |
| 安装包     | `clawdbot`（npm 全局包）                                                         |
| 命令名     | 安装后命令为 `clawdbot`；**Windows 原生环境下如果提示 `openclaw` 不是可识别命令，请统一使用 `clawdbot`** |
| API Key | 在 `https://api.zaimod.com` 控制台创建                                             |

### 1.2 三个 provider 的地址结尾不同（关键）

中转站对三种协议提供的路径不同，**`baseUrl` 的结尾也因此不同，不能统一加 `/v1`**：

| provider           | baseUrl                        | 实际请求路径                                   | 协议                      |
| ------------------ | ------------------------------ | ---------------------------------------- | ----------------------- |
| `api-proxy-gpt`    | `https://api.zaimod.com/v1`     | `/v1/chat/completions`                   | OpenAI Chat Completions |
| `api-proxy-claude` | `https://api.zaimod.com`        | `/v1/messages`（客户端自动拼接）                  | Anthropic Messages      |
| `api-proxy-google` | `https://api.zaimod.com/v1beta` | `/v1beta/models/{model}:generateContent` | Google Gemini           |

> 这是本篇最容易配错的地方：Claude 那一段**故意不带 `/v1`**，因为 `anthropic-messages` 模式会自动补上；如果照抄 GPT 的写法给它加上 `/v1`，就会变成 `/v1/v1/messages` 而报 404。

---

## 二、安装与初始化

### 2.1 全局安装

```bash
npm i -g clawdbot
```

### 2.2 执行引导

根据提示完成基础设置（选择默认模型、工作目录等）：

```bash
clawdbot onboard
```

> 若提示该子命令不存在，改用 `clawdbot onboarding`（不同版本子命令名略有差异，两种都试一下）。  
> 引导结束后终端会输出一个 **访问 Token**，请记下，第五步登录控制台要用。

引导完成后，配置目录 `~/.clawdbot` 会自动生成：

| 系统            | 配置目录                         |
| ------------- | ---------------------------- |
| Windows       | `C:\Users\<你的用户名>\.clawdbot` |
| macOS / Linux | `~/.clawdbot`                |

---

## 三、修改主配置文件 `clawdbot.json`

文件路径：

- Windows：`C:\Users\<你的用户名>\.clawdbot\clawdbot.json`
- macOS / Linux：`~/.clawdbot/clawdbot.json`

把其中的 `agents`、`auth`、`models` 三部分改为下面的内容（其余字段保持原样，不要整体覆盖）：

```json
{
  "agents": {
    "defaults": {
      "workspace": "C:\\Users\\你的用户名\\clawd",
      "models": {
        "api-proxy-gpt/gpt-4o": { "alias": "GPT-4o" },
        "api-proxy-claude/claude-sonnet-4-5-20250929": { "alias": "Claude Sonnet 4.5" },
        "api-proxy-google/gemini-3-pro-preview": { "alias": "Gemini 3 Pro" }
      },
      "model": {
        "primary": "api-proxy-claude/claude-sonnet-4-5-20250929"
      }
    }
  },
  "auth": {
    "profiles": {
      "api-proxy-gpt:default": { "provider": "api-proxy-gpt", "mode": "api_key" },
      "api-proxy-claude:default": { "provider": "api-proxy-claude", "mode": "api_key" },
      "api-proxy-google:default": { "provider": "api-proxy-google", "mode": "api_key" }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "api-proxy-gpt": {
        "baseUrl": "https://api.zaimod.com/v1",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-4o", "name": "GPT-4o", "contextWindow": 128000, "maxTokens": 8192 }
        ]
      },
      "api-proxy-claude": {
        "baseUrl": "https://api.zaimod.com",
        "api": "anthropic-messages",
        "models": [
          { "id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5", "contextWindow": 200000, "maxTokens": 8192 }
        ]
      },
      "api-proxy-google": {
        "baseUrl": "https://api.zaimod.com/v1beta",
        "api": "google-generative-ai",
        "models": [
          { "id": "gemini-3-pro-preview", "name": "Gemini 3 Pro", "contextWindow": 2000000, "maxTokens": 8192 }
        ]
      }
    }
  }
}
```

### 3.1 各字段含义

| 字段                               | 说明                                                                     |
| -------------------------------- | ---------------------------------------------------------------------- |
| `agents.defaults.workspace`      | Agent 的工作目录，改成你电脑上真实存在的路径（示例中的 `你的用户名` 需替换）                            |
| `agents.defaults.models`         | 界面上可选的模型清单，**键必须写成 `provider/model-id`**，与下面 `models.providers` 里的定义对应 |
| `agents.defaults.model.primary`  | 默认使用的模型，取值同样为 `provider/model-id`                                      |
| `auth.profiles`                  | 声明各 provider 使用 `api_key` 方式鉴权，名称需与第四步的 profile 键一致                    |
| `models.mode`                    | `merge` 表示与内置 provider 合并，而不是整体替换内置列表                                  |
| `models.providers.<id>.baseUrl`  | 中转站地址，**三种协议结尾不同**，见 1.2                                               |
| `models.providers.<id>.api`      | 协议类型，决定请求体的格式与路径拼接方式                                                   |
| `models.providers.<id>.models[]` | 该 provider 下可用的模型；`contextWindow`、`maxTokens` 可按需调整                    |

> 换模型时注意：`models[]` 里的 `id` 必须是中转站实际支持的模型名；`agents.defaults.models` 的键与 `model.primary` 都要同步改，否则界面选不到或启动报错。

---

## 四、配置鉴权文件 `auth-profiles.json`

文件路径：

- Windows：`C:\Users\<你的用户名>\.clawdbot\agents\main\agent\auth-profiles.json`
- macOS / Linux：`~/.clawdbot/agents/main/agent/auth-profiles.json`

在此处填入你从中转站获取的真实 API Key：

```json
{
  "version": 1,
  "profiles": {
    "api-proxy-gpt:default": {
      "type": "api_key",
      "provider": "api-proxy-gpt",
      "key": "sk-your-unique-gpt-key-here"
    },
    "api-proxy-claude:default": {
      "type": "api_key",
      "provider": "api-proxy-claude",
      "key": "sk-your-unique-claude-key-here"
    },
    "api-proxy-google:default": {
      "type": "api_key",
      "provider": "api-proxy-google",
      "key": "sk-your-unique-google-key-here"
    }
  },
  "lastGood": {
    "api-proxy-gpt": "api-proxy-gpt:default",
    "api-proxy-claude": "api-proxy-claude:default",
    "api-proxy-google": "api-proxy-google:default"
  }
}
```

要点：

- `key` 只填 Key 本身，**不要加 `Bearer ` 前缀**，也不要带引号外的空格。
- 如果平台的一个令牌通用于全部模型，三个 `key` 可以填**同一个值**；只有在按渠道分令牌时才需要分别填写。
- `profiles` 的键（如 `api-proxy-gpt:default`）必须与 `clawdbot.json` 中 `auth.profiles` 的键完全一致。
- `lastGood` 记录各 provider 上次成功的 profile，一般保持默认即可。

---

## 五、检查并启动

### 5.1 运行健康检查

```bash
clawdbot doctor
```

体检会检查配置格式、密钥是否可读、模型定义是否完整。**有报错先修完再启动**，否则网关能起到但调用模型时会一直失败。

### 5.2 启动 Gateway 服务

```bash
clawdbot gateway
```

**改过任何 JSON 配置后都要重启 gateway**，配置不会热加载。

### 5.3 访问控制台

浏览器打开 <http://127.0.0.1:18789/>，使用 `clawdbot onboard` 结尾输出的 **Token** 登录，即可开始使用。

---

## 六、配置速查表

| 项目                | 值                                                                    |
| ----------------- | -------------------------------------------------------------------- |
| GPT 通道 baseUrl    | `https://api.zaimod.com/v1`                                           |
| Claude 通道 baseUrl | `https://api.zaimod.com`（不带 `/v1`）                                    |
| Gemini 通道 baseUrl | `https://api.zaimod.com/v1beta`                                       |
| 协议字段              | `openai-completions` / `anthropic-messages` / `google-generative-ai` |
| 鉴权方式              | `api_key`，Key 不加 `Bearer`                                            |
| 主配置               | `~/.clawdbot/clawdbot.json`                                          |
| 密钥配置              | `~/.clawdbot/agents/main/agent/auth-profiles.json`                   |
| 控制台               | `http://127.0.0.1:18789/`                                            |

---

## 七、常见问题

| 现象                         | 原因与处理                                                                             |
| -------------------------- | --------------------------------------------------------------------------------- |
| `openclaw` 不是可识别命令         | Windows 原生环境请统一使用 `clawdbot`                                                      |
| `clawdbot onboard` 报子命令不存在 | 改用 `clawdbot onboarding`                                                          |
| `doctor` 提示配置解析失败          | JSON 语法错误：多余的逗号、中文引号、缺大括号。可用在线 JSON 校验器检查                                         |
| `401` / Invalid token      | Key 填错、含空格，或令牌已过期；确认 `auth-profiles.json` 与 `clawdbot.json` 中的 profile 键一致        |
| Claude 通道 404              | baseUrl 误加了 `/v1`，应为 `https://api.zaimod.com`（客户端会自动补 `/v1/messages`）              |
| GPT / Gemini 通道 404        | baseUrl 少了后缀：GPT 需 `/v1`，Gemini 需 `/v1beta`                                       |
| 界面里看不到模型                   | `agents.defaults.models` 的键未按 `provider/model-id` 书写，或 `models.providers` 里没有对应模型 |
| 改了配置没生效                    | 未重启 `clawdbot gateway`                                                            |
| 控制台登录失败                    | Token 用的是过期会话的，重新执行 `clawdbot onboard` 获取，或检查是否复制完整                               |
| 网关启动但对话一直转圈                | 先用 `clawdbot doctor` 看通道探测结果，多半是 baseUrl 或模型名不匹配                                  |

---

## 附录 A：接口地址变更对照

| 位置                  | 原地址                             | 现地址                            |
| ------------------- | ------------------------------- | ------------------------------ |
| GPT 通道 `baseUrl`    | `https://api.zaimod.com/v1`     | `https://api.zaimod.com/v1`     |
| Claude 通道 `baseUrl` | `https://api.zaimod.com`        | `https://api.zaimod.com`        |
| Gemini 通道 `baseUrl` | `https://api.zaimod.com/v1beta` | `https://api.zaimod.com/v1beta` |

> 三个通道的路径后缀保持原样，仅替换域名部分。Key 请在 `https://api.zaimod.com` 重新创建后填入 `auth-profiles.json`。

## 附录 B：本次整理修正的原文问题

| 原文问题                                                 | 处理方式                                    |
| ---------------------------------------------------- | --------------------------------------- |
| 一级标题与二级标题内容重复（同一句标题写了两遍）                             | 合并为一个标题                                 |
| 标题中单词间出现双空格（`OpenClaw  Clawdbot`）                    | 统一为单空格                                  |
| 文件路径硬编码为 `C:\Users\Administrator\...`                | 改为 `<你的用户名>` 占位符，并补充 macOS / Linux 对应路径 |
| 前文命令为 `clawdbot onboard`，文末却提到 `clawdbot onboarding` | 保留两种写法并说明差异，避免照抄报错                      |
| 代码块内有多余空行，且 JSON 示例缺少字段说明                            | 清理空行，新增字段含义表与三通道地址对照表                   |
| 未提示三种协议 baseUrl 结尾不同                                 | 新增 1.2 节专门说明，并在 FAQ 中列出对应 404 场景        |
| 未说明配置修改后需重启 gateway                                  | 在 5.2 与 FAQ 中补充                         |

上一篇：Codex 配置API接入教程{else}上一篇：没有了下一篇：OpenClaw 最自定义中转站配置教程{else}下一篇：没有了