一、引言

OpenClaw Clawdbot 作为一款功能强大的 AI 对话机器人框架，其自定义中转站配置是实现低成本、高效能 AI 服务的关键技术。本教程基于 2026 年最新版本，详细介绍如何通过 api.jizhiai.top 中转站实现 Clawdbot 的完整配置，涵盖环境准备、安装配置、验证测试等全流程。

二、前置准备

2.1 环境校验

Clawdbot 运行需要特定的环境支持，Node.js 18.x 及以上版本（推荐 20.x LTS） 是必需条件。执行以下命令验证环境配置：

Plain Text
\# 检查 Node.js 版本（需≥18.0.0）

node -v

\# 检查 npm 版本（需≥9.0.0）

npm -v

若版本不符合要求，根据操作系统选择相应的安装方式：

Windows 系统：

  1. 访问 Node.js 官网 下载 LTS 版本
  1. 安装时勾选 "Add to PATH" 选项
  1. 重启命令行工具

macOS/Linux 系统：

Plain Text
\# 安装 nvm（Node 版本管理器）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

\# 安装 Node.js 20.x

nvm install 20

nvm use 20

2.2 工具准备

配置文件编辑器：推荐使用 VS Code 并安装 JSON 插件，避免使用记事本等简单文本编辑器导致的格式错误。

命令行工具：

  • Windows：使用 PowerShell（管理员模式） 或 Windows Terminal，避免 CMD 兼容性问题
  • macOS/Linux：默认终端即可

网络检查：确保能够正常访问自定义中转站域名，执行：

Plain Text
\# Windows 系统

ping api.jizhiai.top

\# macOS/Linux 系统

curl -I https://api.jizhiai.top

三、安装与基础初始化

3.1 全局安装 Clawdbot

为避免网络问题导致的下载失败，建议使用国内镜像源进行安装：

# 全局安装（指定国内镜像加速）
npm i -g clawdbot --registry=https://registry.npmmirror.com

 

安装成功验证：执行 clawdbot -v 命令，若能输出版本号则表示安装成功。

常见问题处理：

若 Windows 系统提示 "clawdbot 不是内部或外部命令"，可尝试：

  1. 检查 Node.js 是否已添加到系统环境变量（Path）
  1. 以管理员模式重启命令行工具
  1. 手动定位安装路径：C:\Users\你的用户名\AppData\Roaming\npm\node_modules\clawdbot

3.2 初始化引导

执行初始化命令：

clawdbot onboard

 

该命令会启动交互式配置引导，关键选项说明如下表：

引导选项

推荐选择

说明

Workspace 路径

默认或自定义

建议选择非中文路径，如 D:\Clawdbot\workspace

Agent 名称

main

保持默认，后续可新增多 Agent

初始模型

暂时跳过

后续通过配置文件自定义

控制台端口

18789

保持默认，若端口被占用可改为 18790 等

引导完成后，系统会自动生成基础配置文件，并输出控制台登录 Token。请务必保存该 Token，如丢失可在 ~/.clawdbot/logs/onboard.log 文件中查找。

四、修改主配置文件（clawdbot.json）

4.1 定位配置文件

配置文件的位置因操作系统而异：

系统

配置文件路径

快速打开方式

Windows

C:\Users\你的用户名.clawdbot\clawdbot.json

PowerShell：notepad $env:USERPROFILE.clawdbot\clawdbot.json

macOS/Linux

~/.clawdbot/clawdbot.json

终端：vim ~/.clawdbot/clawdbot.json

注意：将路径中的 "Administrator" 替换为你的实际用户名（如 "张三"、"User"）。

4.2 完整配置代码

以下是基于 api.jizhiai.top 中转站的完整配置代码，包含详细注释说明：

{
  "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": {
      // 鉴权配置关联（对应 auth-profiles.json 中的配置）
      "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", // 模型模式：merge（合并自定义+默认）
    "providers": {
      // GPT 系列中转站配置
      "api-proxy-gpt": {
        "baseUrl": "https://api.jizhiai.top/v1", // 中转站 API 地址
        "api": "openai-completions", // 接口类型（OpenAI 兼容）
        "models": [
          {
            "id": "gpt-4o", // 模型 ID（需与中转站一致）
            "name": "GPT-4o", // 模型名称
            "contextWindow": 128000, // 上下文窗口大小
            "maxTokens": 8192 // 最大输出 Token 数
          }
        ]
      },
      // Claude 系列中转站配置
      "api-proxy-claude": {
        "baseUrl": "https://api.jizhiai.top", // Claude 接口无需 /v1 后缀
        "api": "anthropic-messages", // 接口类型（Anthropic 兼容）
        "models": [
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "contextWindow": 200000,
            "maxTokens": 8192
          ]
        ]
      },
      // Gemini 系列中转站配置
      "api-proxy-google": {
        "baseUrl": "https://api.jizhiai.top/v1beta", // Gemini 接口后缀
        "api": "google-generative-ai", // 接口类型（Google 兼容）
        "models": [
          {
            "id": "gemini-3-pro-preview",
            "name": "Gemini 3 Pro",
            "contextWindow": 2000000, // Gemini 上下文更大
            "maxTokens": 8192
          ]
        ]
      }
    }
  },
  // 新增：日志配置（便于排查问题）
  "logging": {
    "level": "info",
    "file": "C:\\Users\\你的用户名\\.clawdbot\\logs\\clawdbot.log"
  },
  // 新增：网关配置（端口、跨域）
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "cors": true // 允许跨域访问（控制台需要）
  }
}

 

4.3 配置自定义说明

若需要使用其他中转站（如自建或第三方服务），只需修改以下核心参数：

  1. baseUrl：替换为实际的中转站 API 地址（如 https://your-proxy.com/v1）
  1. models[0].id：替换为中转站提供的模型 ID（需完全一致）
  1. contextWindow/maxTokens：按中转站实际参数填写（不影响使用，但建议准确）

五、配置鉴权文件（auth-profiles.json）

5.1 定位鉴权文件

鉴权文件位于：

C:\Users\你的用户名\.clawdbot\agents\main\agent\auth-profiles.json

 

5.2 完整鉴权配置

以下是完整的鉴权配置代码，需要将 sk-your-unique-xxx-key-here 替换为从 api.jizhiai.top 获取的真实 API Key：

{
  "version": 1,
  "profiles": {
    // GPT 鉴权（替换为你的真实 API Key）
    "api-proxy-gpt:default": {
      "type": "api_key", // 鉴权类型（固定为 api_key）
      "provider": "api-proxy-gpt", // 与主配置文件对应
      "key": "sk-your-unique-gpt-key-here" // 中转站获取的 GPT API Key
    },
    // Claude 鉴权
    "api-proxy-claude:default": {
      "type": "api_key",
      "provider": "api-proxy-claude",
      "key": "sk-your-unique-claude-key-here" // 中转站获取的 Claude API Key
    },
    // Gemini 鉴权
    "api-proxy-google:default": {
      "type": "api_key",
      "provider": "api-proxy-google",
      "key": "sk-your-unique-google-key-here" // 中转站获取的 Gemini API Key
    }
  },
  "lastGood": {
    // 最后可用的鉴权配置（自动更新，无需手动改）
    "api-proxy-gpt": "api-proxy-gpt:default",
    "api-proxy-claude": "api-proxy-claude:default",
    "api-proxy-google": "api-proxy-google:default"
  }
}

 

5.3 鉴权注意事项

  1. API Key 安全：API Key 需严格保密，不要分享或提交到代码仓库
  1. 自定义 Header：若中转站要求添加自定义 Header（如 X-Proxy-Id），可在鉴权文件中新增 headers 字段：
"api-proxy-gpt:default": {
  "type": "api_key",
  "provider": "api-proxy-gpt",
  "key": "your-key",
  "headers": {
    "X-Proxy-Id": "your-proxy-id", // 中转站自定义 Header
    "User-Agent": "Clawdbot/1.0"
  }
}

 

六、检查与启动

6.1 健康检查

配置完成后，使用以下命令进行健康检查：

Plain Text
clawdbot doctor

正常情况下会输出：

Plain Text
✅ All checks passed!

常见错误及解决方法：

错误提示

解决方法

JSON parse error

检查配置文件格式（逗号、花括号是否缺失）

File not found

确认配置文件路径正确，文件已创建

Port 18789 in use

修改 gateway.port 为 18790（主配置文件）

API Key invalid

核对 API Key 是否正确，中转站是否已激活

6.2 启动 Gateway 服务

根据使用场景选择启动方式：

前台启动（便于查看日志）：

Plain Text
clawdbot gateway

后台启动：

  • Windows：start cmd /k "clawdbot gateway"
  • macOS/Linux：nohup clawdbot gateway > ~/.clawdbot/logs/gateway.log 2>&1 &

启动成功标志：控制台输出 Gateway running on ``http://127.0.0.1:18789。

6.3 控制台登录与验证

  1. 打开浏览器访问：http://127.0.0.1:18789/
  1. 输入 clawdbot onboard 输出的 Token 进行登录
  1. 验证自定义模型：
  • 进入 "Models" 页面，应能看到 GPT-4o、Claude Sonnet 4.5、Gemini 3 Pro
  • 新建对话，选择模型发送消息，能正常回复即表示配置成功

七、进阶优化

7.1 多中转站配置

若需要同时使用多个中转站以提高服务稳定性或实现负载均衡，可在 models.providers 中新增配置：

Plain Text
"api-proxy-gpt-2": {

"baseUrl": "https://another-proxy.com/v1",

"api": "openai-completions",

"models": \[

  {

    "id": "gpt-4o",

    "name": "GPT-4o（备用）",

    "contextWindow": 128000,

    "maxTokens": 8192

  }

]

}

7.2 自动重启服务（Windows）

为确保服务的高可用性，可创建批处理文件实现自动重启：

创建 start-clawdbot.bat 文件，内容如下：

Plain Text
@echo off

:restart

clawdbot gateway

echo Service crashed, restarting in 5 seconds...

timeout /t 5 /nobreak > nul

goto restart

7.3 日志排查

当服务出现异常时，可通过以下日志文件进行问题定位：

  1. 启动日志：~/.clawdbot/logs/gateway.log
  1. 鉴权日志：~/.clawdbot/logs/auth.log
  1. 模型调用日志：~/.clawdbot/logs/models.log

八、常见问题 FAQ

Q：修改配置后不生效？

A：配置文件修改后需要 重启 Gateway 服务（执行 clawdbot gateway）才能生效，因为配置文件只有在服务启动时才会加载。

Q：控制台登录提示 Token 无效？

A：执行 clawdbot onboard --reset 重新生成 Token，但此操作会 重置基础配置，需要重新填写所有配置信息。

Q：模型调用提示 "Connection timeout"？

A：检查网络连接是否正常，确保能够访问 api.jizhiai.top，关闭防火墙或代理软件后重试。

Q：macOS/Linux 系统权限不足？

A：执行 sudo chmod -R 755 ~/.clawdbot 赋予目录适当权限。

九、总结

通过本教程的详细步骤，我们完成了基于 api.jizhiai.top 中转站的 OpenClaw Clawdbot 完整配置。配置成功的核心要点包括：

  1. 环境配置正确：确保 Node.js 版本符合要求，网络连接正常
  1. 配置文件格式正确：JSON 格式合法，无语法错误
  1. API Key 有效：从 api.jizhiai.top 获取的密钥正确无误
  1. 端口配置合理：避免端口冲突，建议使用默认的 18789 端口

clawdbot doctor 是排错的首选工具，能够快速定位配置、端口、鉴权等基础问题。通过控制台验证是最终的配置确认环节，能够正常调用模型并获得回复即表示配置成功。

若需要切换中转站或模型，只需修改 baseUrl、model.id 和 API Key 三个核心参数，无需重新安装整个系统。这种灵活的配置方式大大提高了系统的可维护性和可扩展性。

# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

systemd 托管 Agent 服务的三大陷阱与观测实践

avatar 龙虾开发者社区
cover

WorkBuddy 身份主键设计：为何你的 Agent 总认错人？

avatar 龙虾开发者社区
cover

Agent 日志解析乱码危机：GBK 与 UTF-8 混编时的沙箱防御策略

avatar 龙虾开发者社区