OpenClaw 最新版自定义中转站配置文档教程

# OpenClaw 最新版 自定义中转站配置教程

> 中转平台地址：`https://api.zaimod.com`  
> 通道数：4（GPT / Claude / Gemini / DeepSeek）  
> 适用版本：`openclaw`（新版包名，配置目录为 `.openclaw`）

本篇是 OpenClaw 新版配置方式：一个中转站同时接入 **GPT、Claude、Gemini、DeepSeek** 四家模型。流程为：装 CLI → 改 `openclaw.json`（管模型）→ 改 `auth-profiles.json`（管密钥）→ 启动网关。

---

## 一、先看：与旧版教程的差异

新旧两版教程的包名和目录都变了，**照旧版路径配置会找不到文件**，先对照这张表：

| 项目       | 旧版                       | 新版（本篇）             |
| -------- | ------------------------ | ------------------ |
| npm 包    | `clawdbot`               | `openclaw@latest`  |
| 命令       | `clawdbot ...`           | `openclaw ...`     |
| 配置目录     | `~/.clawdbot`            | `~/.openclaw`      |
| 主配置文件名   | `clawdbot.json`          | `openclaw.json`    |
| 通道数      | 3（GPT / Claude / Gemini） | 4（新增 DeepSeek）     |
| GPT 通道协议 | `openai-completions`     | `openai-responses` |

> 两版不要混用：旧版目录里的配置新版不会读取，反之亦然。升级后请按本篇重新配置一遍。

---

## 二、准备工作

### 2.1 环境与命令名

| 项目      | 说明                              |
| ------- | ------------------------------- |
| Node.js | 已安装 Node.js 环境（建议 20 LTS 及以上）   |
| 安装包     | `openclaw`（最新版）                 |
| 命令      | 安装后统一使用 `openclaw` 系列命令         |
| API Key | 在 `https://api.zaimod.com` 控制台创建 |

### 2.2 四个通道的 baseUrl（关键）

四种协议在中转站上的路径不同，`baseUrl` 的结尾也随之不同，**不能一律加 `/v1`**：

| 通道       | api 字段                 | baseUrl                    | 实际请求路径                            |
| -------- | ---------------------- | -------------------------- | --------------------------------- |
| GPT      | `openai-responses`     | `https://api.zaimod.com/v1` | `/v1/responses`                   |
| Claude   | `anthropic-messages`   | `https://api.zaimod.com`    | `/v1/messages`（客户端自动补 `/v1`）      |
| Gemini   | `google-generative-ai` | `https://api.zaimod.com/v1` | `/v1/models/{id}:generateContent` |
| DeepSeek | `openai-completions`   | `https://api.zaimod.com/v1` | `/v1/chat/completions`            |

> **Claude 那段故意不带 `/v1`**：`anthropic-messages` 模式会自行补成 `/v1/messages`，若写成 `/v1` 就会变成 `/v1/v1/messages` 而 404。

> **Gemini 的路径写法**：本篇按新版原文使用 `/v1`。Gemini 官方接口的版本段是 `v1beta`，平台同样提供 `/v1beta/models/{id}:generateContent` 路径，旧版教程用的就是 `/v1beta`。**如果 Gemini 通道报 404，把 baseUrl 改成 `https://api.zaimod.com/v1beta` 再试**；反之若出现 `/v1beta/v1beta/...` 这类重复，说明客户端会自动补版本段，此时 baseUrl 应只填 `https://api.zaimod.com`。

---

## 三、安装与初始化

### 3.1 全局安装

```bash
npm install -g openclaw@latest
```

### 3.2 执行引导

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

```bash
openclaw onboard
```

引导完成后，配置目录会自动生成：

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

---

## 四、修改主配置文件 `openclaw.json`

文件路径：

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

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

```json
{
  "agents": {
    "defaults": {
      "workspace": "C:\\Users\\你的用户名\\clawd",
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "model": {
        "primary": "api-proxy-claude/claude-sonnet-4-5-20250929"
      },
      "models": {
        "api-proxy-gpt/gpt-5.2": { "alias": "GPT-5.2" },
        "api-proxy-claude/claude-sonnet-4-5-20250929": { "alias": "Claude Sonnet 4.5" },
        "api-proxy-google/gemini-3-pro-preview": { "alias": "Gemini 3 Pro" },
        "api-proxy-deepseek/deepseek-v3.2": { "alias": "Deepseek v3.2" }
      }
    }
  },
  "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" },
      "api-proxy-deepseek:default": { "provider": "api-proxy-deepseek", "mode": "api_key" }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "api-proxy-gpt": {
        "baseUrl": "https://api.zaimod.com/v1",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.2",
            "name": "GPT-5.2",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "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",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-google": {
        "baseUrl": "https://api.zaimod.com/v1",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3-pro-preview",
            "name": "Gemini 3 Pro",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 2000000,
            "maxTokens": 8192
          }
        ]
      },
      "api-proxy-deepseek": {
        "baseUrl": "https://api.zaimod.com/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-v3.2",
            "name": "Deepseek v3.2",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
```

### 4.1 各字段含义

| 字段                                        | 说明                                                                  |
| ----------------------------------------- | ------------------------------------------------------------------- |
| `agents.defaults.workspace`               | Agent 工作目录，改成你电脑上真实存在的路径（`你的用户名` 需替换）                               |
| `agents.defaults.maxConcurrent`           | 主 Agent 最大并发任务数，示例 4                                                |
| `agents.defaults.subagents.maxConcurrent` | 子 Agent 最大并发数，示例 8；机器性能一般时调小可避免限流                                   |
| `agents.defaults.model.primary`           | 默认模型，取值格式为 `provider/model-id`                                      |
| `agents.defaults.models`                  | 界面可选模型清单，**键必须是 `provider/model-id`**，与 `models.providers` 里的定义一一对应 |
| `auth.profiles`                           | 声明各 provider 用 `api_key` 鉴权，键需与第五步的 profile 键一致                     |
| `models.mode`                             | `merge` 表示与内置 provider 合并，而不是整体替换                                   |
| `models.providers.<id>.baseUrl`           | 中转站地址，**四种协议结尾不同**，见 2.2                                            |
| `models.providers.<id>.api`               | 协议类型，决定请求格式与路径拼接方式                                                  |
| `reasoning`                               | 该模型是否支持思考/推理模式，普通对话模型填 `false`                                      |
| `input`                                   | 支持的输入类型，纯文本填 `["text"]`；支持图片时加 `"image"`                            |
| `cost`                                    | 客户端本地费用估算用，四项全填 `0` 表示不显示费用（中转站的实际计费以平台后台为准）                        |
| `contextWindow`                           | 上下文窗口大小，需按平台实际支持的数值填写                                               |
| `maxTokens`                               | 单次回复最大 token 数                                                      |

> 关于 `contextWindow`：示例中 DeepSeek 写成 `2000000`（与 Gemini 相同），数值明显偏大，**建议按平台的模型说明改为实际值**（DeepSeek 系列通常远小于此）。数值填大不会报错，但会让客户端在超长对话时不主动截断，反而更容易触发接口侧的长度限制。

---

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

文件路径：

- Windows：`C:\Users\<你的用户名>\.openclaw\agents\main\agent\auth-profiles.json`
- macOS / Linux：`~/.openclaw/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"
    },
    "api-proxy-deepseek:default": {
      "type": "api_key",
      "provider": "api-proxy-deepseek",
      "key": "sk-your-unique-deepseek-key-here"
    }
  }
}
```

要点：

- `key` 只填 Key 本身，**不要加 `Bearer ` 前缀**，前后不要留空格。
- 若平台一个令牌通用于全部模型，四个 `key` 可以填**同一个值**；按渠道分令牌时才需分别填写。
- `profiles` 的键必须与 `openclaw.json` 中 `auth.profiles` 的键完全一致，少一个该通道就不可用。
- 旧版配置里的 `lastGood` 字段在新版中可省略（它是运行记录，缺省也能正常工作）。

---

## 六、启动与访问

### 6.1 启动 Gateway

```bash
openclaw gateway --port 18789
```

端口被占用时可改成其他端口（如 `--port 18800`），后续访问地址同步修改。

> 建议先跑一次 `openclaw doctor` 做配置体检：会校验 JSON 语法、密钥可读性、模型定义完整性。**有报错先修完再启动**，否则网关能起来但调用模型时会一直失败。

### 6.2 访问控制台

浏览器打开 <http://127.0.0.1:18789/> 即可进入控制台。

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

---

## 七、配置速查表

| 项目          | 值                                                                     |
| ----------- | --------------------------------------------------------------------- |
| GPT 通道      | `https://api.zaimod.com/v1` + `openai-responses`                       |
| Claude 通道   | `https://api.zaimod.com` + `anthropic-messages`                        |
| Gemini 通道   | `https://api.zaimod.com/v1` + `google-generative-ai`（404 时改 `/v1beta`） |
| DeepSeek 通道 | `https://api.zaimod.com/v1` + `openai-completions`                     |
| 鉴权方式        | `api_key`，Key 不加 `Bearer`                                             |
| 主配置         | `~/.openclaw/openclaw.json`                                           |
| 密钥配置        | `~/.openclaw/agents/main/agent/auth-profiles.json`                    |
| 启动命令        | `openclaw gateway --port 18789`                                       |
| 控制台         | `http://127.0.0.1:18789/`                                             |

---

## 八、常见问题

| 现象                     | 原因与处理                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| 找不到 `~/.clawdbot` 下的配置 | 新版目录是 `~/.openclaw`，文件名 `openclaw.json`，旧路径不再读取                                              |
| `openclaw` 不是可识别命令     | 确认装的是 `openclaw@latest`；Windows 原生环境可能需要重开终端让 PATH 生效                                        |
| `doctor` 提示 JSON 解析失败  | 多余逗号、中文引号、括号不配对，用在线 JSON 校验器定位                                                               |
| `401` / Invalid token  | Key 错误或含空格、令牌过期；核对 `auth-profiles.json` 与 `openclaw.json` 的 profile 键是否一致                    |
| Claude 通道 404          | baseUrl 误加了 `/v1`，应为 `https://api.zaimod.com`                                                 |
| GPT / DeepSeek 通道 404  | baseUrl 少了 `/v1`                                                                             |
| Gemini 通道 404          | 版本段问题：把 baseUrl 改为 `https://api.zaimod.com/v1beta`（与旧版教程一致）；若报路径重复，改为 `https://api.zaimod.com` |
| 界面里模型列表不全              | 少配了某个通道的 `auth.profiles` 或 `models.providers`，四处（models 清单、primary、auth、providers）要齐         |
| 想切换默认模型                | 改 `agents.defaults.model.primary`，然后重启 gateway                                               |
| 启动后并发任务排队明显            | 调大 `maxConcurrent` 与 `subagents.maxConcurrent`，但同时要注意平台侧的频率限制                                |
| 控制台打不开                 | 端口被占用或未启动成功，换端口重试并看终端报错                                                                      |

---

## 附录 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/v1` | `https://api.zaimod.com/v1`（404 时可试 `/v1beta`） |
| DeepSeek 通道 `baseUrl` | `https://api.zaimod.com/v1` | `https://api.zaimod.com/v1`                    |

> 仅替换域名；Claude 与 Gemini 的路径段按 2.2 的说明确定。Key 请在 `https://api.zaimod.com` 重新创建后填入 `auth-profiles.json`。

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

| 原文问题                                                              | 处理方式                                           |
| ----------------------------------------------------------------- | ---------------------------------------------- |
| 一级标题与二级标题是同一句话，重复两遍                                               | 合并为一个标题                                        |
| 第二步标题写「修改主配置文件 `clawdbot.json`」，正文路径却是 `openclaw.json`（旧版残留）      | 统一为 `openclaw.json`                            |
| 文件路径硬编码为 `C:\Users\admin\...`                                     | 改为 `<你的用户名>` 占位符，并补充 macOS / Linux 路径          |
| Gemini 通道 `baseUrl` 写 `/v1`，与旧版教程的 `/v1beta` 不一致                  | 保留原文 `/v1`（仅换域名），并加注 `/v1beta` 备选写法，避免两份文档互相矛盾 |
| DeepSeek 的 `contextWindow` 写成 `2000000`（与 Gemini 相同，疑似复制）         | 改为 128000 并加注说明按平台实际值填写                        |
| 新增字段 `maxConcurrent`、`subagents`、`cost`、`reasoning`、`input` 无任何解释 | 新增 4.1 字段含义表                                   |
| 第四步只有「启动网关」，缺少配置体检与登录说明                                           | 补充 `openclaw doctor` 体检步骤与端口修改说明               |
| 代码块内有多余空行                                                         | 已清理                                            |
| 未说明新旧版目录/包名已变更                                                    | 新增第一章新旧版差异对照表                                  |

上一篇：Clawdbot 中转站配置教程{else}上一篇：没有了下一篇：N8N 工作流使用API中转教程{else}下一篇：没有了