AI能量庄园 Agent 工具接入指南

把 Codex、Claude Code、OpenCode、OpenClaw、WorkBuddy/CodeBuddy 以及其他兼容 Agent 接入 AI能量庄园统一网关。

快速判断

一、接入前准备

1. 获取 AI能量庄园令牌

进入令牌管理：

1. 创建或选择一个调用令牌。
2. 复制令牌密钥，格式通常为 sk-...。
3. 确认令牌状态正常、未过期，并已绑定可用分组。

不要把密钥发到群聊、截图、代码仓库或公共配置文件中。

2. 获取当前可用模型名

进入模型广场：

1. 打开筛选项。
2. 在“可用令牌分组”中选择当前令牌对应的分组。
3. 从模型卡片复制完整模型名。
4. 将同一个模型名填入 Agent 的 Model、model 或 id 字段。Codex 的配置见二、Codex。

不要照搬别人的模型名。模型是否可用由当前令牌分组决定。

3. 地址和协议对应关系

地址规则：

• OpenAI、Codex、OpenCode、OpenClaw、Cursor 等通常填写带 /v1 的 Base URL。
• Claude Code 填网关根地址，不要手动追加 /v1/messages。
• 一般不要把 /chat/completions、/responses 或 /messages 完整路径填进 Base URL。
• WorkBuddy/CodeBuddy 的本地 models.json 使用 url 字段时，需要填写完整的 /v1/chat/completions 地址。

二、Codex

Codex 的模型配置集中在用户级配置文件 config.toml 里，Codex CLI、桌面版和 VS Code 插件共用这一份配置，配置一次即可复用。接入 AI能量庄园只需要改这个文件里的 3 个值，其余照抄模板。

配置文件位置：

Windows：C:\Users\你的用户名\.codex\config.toml
macOS / Linux：~/.codex/config.toml

文件不存在就直接新建。修改前建议先备份：

Windows PowerShell：

Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.bak"

macOS / Linux：

cp ~/.codex/config.toml ~/.codex/config.toml.bak

1. 完整模板

把下面内容合并进 config.toml。已有的 MCP、项目权限和其他无关配置保留，不要整文件覆盖。需要改的只有 3 个值：model、wire_api、experimental_bearer_token，其余照抄。

model = "deepseek-v4-flash"
model_provider = "aineng"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "medium"

[model_providers.aineng]
name = "AI能量庄园"
base_url = "http://hub.thinvent.com/v1"
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "sk-你的AI能量庄园密钥"

对照第 3 节表格把 model 和 wire_api 换成对应值，experimental_bearer_token 换成自己的密钥。

2. 每个字段怎么改（什么时候需要）

3. model 和 wire_api 填什么

要点：

• 模型名一律以模型广场当前令牌分组可见的为准，公司模型也一样。
• 官方模型、DeepSeek-V4、公司模型走 Responses 协议，wire_api 填 responses。
• 其他第三方模型（deepseek-chat、GLM 等）走 Chat Completions 协议，wire_api 填 chat。

4. 开始使用与验证

1. 完全退出 Codex App、Codex CLI 或 VS Code，不能只执行 Reload Window。
2. 重新启动客户端，确认能选择到要用的模型。
3. CLI 可运行 codex debug models，或用 codex -m <模型名> 指定模型（如 codex -m deepseek-v4-flash、codex -m dev-l-0.56x）。
4. 新建一个任务，确认请求进入 AI能量庄园请求日志。
5. 在请求详情中确认实际模型 ID、Provider 和扣费结果符合预期。

CLI 可能显示原始模型 ID，桌面版和插件版显示友好名称，这是界面差异；实际请求以模型 ID（slug）为准。

可选：通过 CC Switch 导入

如果已安装 CC Switch，可以在 AI能量庄园的令牌操作中选择 CC Switch 配置：

1. 打开 AI能量庄园的 令牌管理。
2. 选择当前令牌的 CC Switch 操作。
3. 应用选择 Codex。
4. API 地址填写 http://hub.thinvent.com/v1。
5. API Key 填入当前令牌密钥。
6. 主模型从模型广场当前分组复制。
7. 导入后完全退出并重新打开 Codex。

导入只是写入本机配置，仍需检查最终文件：

C:\Users\你的用户名\.codex\config.toml

CC Switch 有时导入后没有真正替换密钥（界面显示成功，但 experimental_bearer_token 仍是旧值），要以配置文件为准。重点确认 model_provider、base_url、wire_api、模型名和密钥都已更新，必要时手动修改。

5. 可选：自定义模型列表（models.json）

想让 Codex 的模型选择列表里出现自定义模型（如公司发布的模型列表，或 Codex 内置目录之外的模型）时才需要，不需要就不加。models.json 只包含模型元数据（模型 ID、显示名称等），不含密钥和 Provider 配置。

也可以使用AI能量庄园模型目录工作台勾选模型、自定义显示名称并一键生成 models.json，再按下面的方式放置并引用。该页面只处理模型元数据，不含地址、令牌或授权信息。

把 models.json 放到本地：

Windows：C:\Users\你的用户名\.codex\models.json
macOS / Linux：~/.codex/models.json

在 config.toml 顶层加一行：

model_catalog_json = "~/.codex/models.json"

model 填列表里的模型 ID，wire_api 按第 3 节表格选。

6. 常见问题

三、Claude Code（命令行版）

Claude Code 使用 Anthropic Messages 协议。AI能量庄园的 Claude 地址填写网关根地址，客户端会自动请求 /v1/messages。命令行版通过环境变量配置，桌面版在应用内配置，见四、Claude Code Desktop（桌面版）。

1. 准备

• 已安装 Claude Code。安装方式以工具当前版本为准，本文不提供安装命令。
• Node.js 18 或更高版本。
• Windows 用户安装 Git for Windows。
• 一个 AI能量庄园令牌和模型广场中的模型名。

2. 配置环境变量

先设置 3 个必变的环境变量。模型名从模型广场当前令牌分组复制，和 Codex 用同一个模型名即可。

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="http://hub.thinvent.com"
$env:ANTHROPIC_AUTH_TOKEN="sk-你的AI能量庄园密钥"
$env:ANTHROPIC_MODEL="从模型广场复制的模型名"

macOS / Linux：

export ANTHROPIC_BASE_URL="http://hub.thinvent.com"
export ANTHROPIC_AUTH_TOKEN="sk-你的AI能量庄园密钥"
export ANTHROPIC_MODEL="从模型广场复制的模型名"

可选：当前 Claude Code 版本还会调用默认档位或子 Agent 时，让它们先使用同一个可用模型：

Windows PowerShell：

$env:ANTHROPIC_DEFAULT_OPUS_MODEL=$env:ANTHROPIC_MODEL
$env:ANTHROPIC_DEFAULT_SONNET_MODEL=$env:ANTHROPIC_MODEL
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL=$env:ANTHROPIC_MODEL
$env:CLAUDE_CODE_SUBAGENT_MODEL=$env:ANTHROPIC_MODEL

macOS / Linux：

export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export CLAUDE_CODE_SUBAGENT_MODEL="$ANTHROPIC_MODEL"

注意：

• 不要同时设置 ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY，避免鉴权方式冲突。
• ANTHROPIC_BASE_URL 填网关根地址，不要拼上 /v1/messages。

3. 字段说明（环境变量）

4. 命令行版 CC Switch 配置

命令行版除了直接设环境变量，也可以用 CC Switch 管理 Claude Code 的配置。以下为命令行版通过 CC Switch 配置 Claude Code 的截图流程（界面以 CC Switch 当前版本为准）。

Claude Code 菜单和配置入口

配置页面

配置成功页面

修改配置后，Claude Code 需要重启。

5. 开始使用

进入项目目录并启动：

cd /path/to/your-project
claude

Windows PowerShell 示例：

Set-Location "C:\path\to\your-project"
claude

6. 未生效时检查

在启动 Claude Code 的同一个终端执行：

$env:ANTHROPIC_BASE_URL
$env:ANTHROPIC_AUTH_TOKEN
$env:ANTHROPIC_MODEL

应分别看到 AI能量庄园地址、当前令牌和模型名。不要把完整密钥复制到聊天或日志中。

如果仍然请求官方 Anthropic，依次检查：

1. ANTHROPIC_BASE_URL 是否设置为 http://hub.thinvent.com。
2. 是否误设置了旧的 ANTHROPIC_API_KEY。
3. 当前终端是否是在设置变量之后重新打开的。
4. IDE 或启动器是否覆盖了终端环境变量。
5. AI能量庄园日志中是否出现请求记录。
6. 模型名是否在模型广场当前令牌分组可见。

四、Claude Code Desktop（桌面版）

1. 桌面版配置（应用内）

配置需在未登录状态下进行：完全退出应用，重新打开后停在登录界面，在左上角 ☰ 菜单操作（第三方推理配置入口只在未登录时出现）。

桌面版网关地址要求 https 或本地地址，AI能量庄园只有 http，所以用 CC Switch 开启本地路由（见本节第 2 小节），由 CC Switch 转发到 AI能量庄园。

配置入口（菜单名以应用当前版本为准）：

1. 开启开发者模式：在登录界面点击左上角 ☰ 菜单 → Help → Troubleshooting → Enable Developer Mode，在弹出的确认框点 Enable，应用自动重启。已出现 Developer 菜单的跳过这步。
2. 在登录界面点击左上角 ☰ 菜单 → Developer → Configure Third-Party Inference。
3. 在配置页 Connection 区域，Inference provider 选 Gateway，然后填：

- Gateway Base URL 自动取 CC Switch 的本地路由地址（未自动填上时手动填），不要拼 /v1 或 /v1/messages

- Gateway API Key 填 AI能量庄园令牌密钥

- Auth scheme 选 bearer

1. 启动停在登录选择页时，开启 Skip login-mode chooser。
2. 点 Test connection（如有）确认连通，再点右下角 Apply locally，应用重启生效。
3. 模型名从模型广场当前令牌分组复制；模型列表没有显示时，手动填写模型名。

修改后完全退出并重新打开桌面版（不是只关闭窗口）。

配置页面截图参考（界面以你实际打开的为准）：

桌面版读取 CC Switch 的配置：地址走本地路由、密钥用 AI能量庄园令牌

设置调用的模型 ID

注意：

• 桌面版不读取 ANTHROPIC_BASE_URL，命令行版设置的环境变量对桌面版无效。
• 配置成功后 Developer 菜单会消失，这是正常的：第三方推理配置入口只在未登录的登录界面出现，配置完成进入网关模式后主界面不再显示 Developer。要改配置时，完全退出应用，重新打开后不登录，在登录界面用 ☰ 菜单重新走一遍。
• ☰ 里找不到 Developer 菜单时，最常见原因是在登录状态下找：Developer 只在未登录的登录界面出现，主界面的 ☰ 里没有它。仍找不到时，再确认开发者模式已开启、应用已重启，或当前桌面版版本不支持第三方推理（需要升级应用版本，或改用命令行版）。
• 桌面版模型列表以网关返回的模型为准，以模型广场当前令牌分组可见的模型名最可靠。
• 启动提示 Gateway was unreachable 时，先用八、接口验证的 curl 命令确认地址可达。
• 桌面版走网关时以本机会话运行，远程主机、云环境等部分功能不可用。

配置完成后，在桌面版中打开项目文件夹即可开始对话。

2. CC Switch 本地路由配置

桌面版需要 https 或本地地址，AI能量庄园只有 http，所以用 CC Switch 为桌面版开启本地路由。命令行版用 CC Switch 是直接管理配置（见三、第 4 节），这里的本地路由是桌面版专用。界面以 CC Switch 当前版本为准。

开启路由的位置、桌面版菜单位置、新增配置位置

新增配置页面

配置成功页面

设置页面为 Claude Code 开启路由

配置完成后，回到上面的桌面版小节：桌面版会自动读取 CC Switch 的配置并填好 Gateway Base URL；如果没有读取到，重启桌面版即可。

五、OpenCode

OpenCode 通过 OpenAI Chat Completions 协议与模型交互，Base URL 填写带 /v1 的网关地址。

1. 安装或升级

建议先升级到工具当前版本，再启动：

opencode upgrade
opencode

2. 方式一：使用 Provider 连接

在 OpenCode 输入：

/connect

然后：

1. 选择 Other。
2. Provider ID 填 aineng。
3. 输入 AI能量庄园 API Key。
4. 选择或配置模型广场中的模型名。
5. 执行 /models，选择 aineng/模型名。

3. 方式二：手动写入项目配置

如果 /connect 中没有合适的自定义 Provider，在项目目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aineng": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AI能量庄园",
      "options": {
        "baseURL": "http://hub.thinvent.com/v1"
      },
      "models": {
        "模型名": {
          "name": "AI能量庄园模型"
        }
      }
    }
  }
}

将 模型名 换成模型广场中的实际模型名。API Key 通过 /connect 写入，不要直接提交到项目配置。

4. 开始使用与验证

重启 OpenCode，执行 /models 并选择 aineng/模型名，发起一次对话，确认请求进入 AI能量庄园请求日志。Provider 不显示时，检查 opencode.json 是否在当前项目目录。

5. 常见问题

六、OpenClaw

OpenClaw 通过 OpenAI Chat Completions 协议与模型交互，配置中使用 openai-completions，不是 Codex 使用的 Responses 协议。

1. 安装和进入配置流程

如果尚未安装，先按 OpenClaw 当前安装方式完成安装。已安装用户可以重新进入配置流程：

openclaw onboard --install-daemon

也可以在配置完成后使用：

openclaw dashboard
openclaw tui
openclaw terminal

2. 设置密钥变量

Windows PowerShell：

$env:AINENG_API_KEY="sk-你的AI能量庄园密钥"

macOS / Linux：

export AINENG_API_KEY="sk-你的AI能量庄园密钥"

3. 配置 AI能量庄园 Provider

在 OpenClaw 的模型配置中合并以下内容：

{
  "models": {
    "mode": "merge",
    "providers": {
      "aineng": {
        "baseUrl": "http://hub.thinvent.com/v1",
        "apiKey": "${AINENG_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "模型名",
            "name": "AI能量庄园模型",
            "input": ["text", "image"]
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "aineng/模型名"
      }
    }
  }
}

将 模型名 换成模型广场中的实际模型名。OpenClaw 这里使用 openai-completions，不是 Codex 使用的 Responses 协议。

4. 字段说明

5. 开始使用

重启 OpenClaw，在 Web UI、TUI 或终端中选择 aineng/模型名。如果使用守护进程，修改配置后也要重启对应服务。

七、国产 Agent 与其他工具

这些工具大多只提供 OpenAI 兼容配置，核心是把 Base URL、API Key、Model 三个值填对。

1. WorkBuddy / CodeBuddy

WorkBuddy/CodeBuddy 支持通过本地模型文件添加 OpenAI 兼容模型。

先完成以下准备：

1. 安装并登录 WorkBuddy/CodeBuddy。
2. 至少打开一次项目目录，让工具创建配置目录。
3. 准备 AI能量庄园 API Key 和模型广场模型名。

用户级配置文件：

C:\Users\你的用户名\.codebuddy\models.json

项目级配置文件：

你的项目目录\.codebuddy\models.json

设置环境变量：

$env:AINENG_API_KEY="sk-你的AI能量庄园密钥"

写入模型配置：

{
  "models": [
    {
      "id": "模型名",
      "name": "AI能量庄园模型",
      "vendor": "AI能量庄园",
      "url": "http://hub.thinvent.com/v1/chat/completions",
      "apiKey": "${AINENG_API_KEY}",
      "maxInputTokens": 128000,
      "maxOutputTokens": 8192,
      "supportsToolCall": true,
      "supportsImages": false
    }
  ],
  "availableModels": ["模型名"]
}

注意：

• url 是完整接口地址，需要包含 /v1/chat/completions。
• id、availableModels 和 model 必须使用同一个实际模型名。
• 文件保存为 UTF-8 无 BOM，部分桌面版本读取带 BOM 的 JSON 会失败。
• 完全退出并重启 WorkBuddy/CodeBuddy，再在模型选择器中选择 AI能量庄园模型。
• 如果界面把 ${AINENG_API_KEY} 当作普通文字显示，可从已设置环境变量的终端启动工具；仍不生效时，只在本机配置文件中填入真实密钥，绝不要提交该文件。

2. Trae、豆包 MarsCode、通义灵码、百度 Comate

只有工具版本提供“自定义模型”“自定义 Base URL”或“OpenAI 兼容接口”时，才能使用下面的配置：

如果工具只有官方账号登录，或者不允许修改接口地址，就不能直接接入 AI能量庄园。

3. Cursor、Cline、Roo Code、Windsurf、CodeGeeX、Kimi Code

按 OpenAI 兼容方式填写：

Base URL: http://hub.thinvent.com/v1
API Key: sk-你的AI能量庄园密钥
Model: 从模型广场复制的模型名

若工具要求填写完整 Endpoint，使用：

http://hub.thinvent.com/v1/chat/completions

不要把同一条完整 Endpoint 再拼进已经带 /v1 的 Base URL。

4. Hermes、Reasonix

Hermes、Reasonix 等工具可能提供内置厂商选项，但内置的 DeepSeek 选项通常会指向 DeepSeek 官方地址。

只有在工具当前版本提供以下能力时，才能改接 AI能量庄园：

• 自定义 Base URL。
• 自定义 OpenAI 兼容 Provider。
• 自定义 API Key 和 Model。

如果只有“选择 DeepSeek”而没有自定义地址，不能只替换 API Key 来接入 AI能量庄园。

5. Dify、Coze 等平台型 Agent

Dify Agent、Dify Chatflow、Coze Agent 属于平台侧配置，不是普通用户本机 Agent 配置。由管理员在平台的模型供应商或渠道设置中填写：

Base URL: http://hub.thinvent.com/v1
API Key: AI能量庄园令牌密钥
Model: 模型广场当前令牌分组可见的模型名

八、接口验证

1. 查看令牌可见模型

curl http://hub.thinvent.com/v1/models \
  -H "Authorization: Bearer sk-你的AI能量庄园密钥"

2. 验证 Chat Completions

curl http://hub.thinvent.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的AI能量庄园密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从模型广场复制的模型名",
    "messages": [{"role": "user", "content": "请回复：连接成功"}],
    "stream": false
  }'

3. 验证 Responses（Codex 使用）

curl http://hub.thinvent.com/v1/responses \
  -H "Authorization: Bearer sk-你的AI能量庄园密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从模型广场复制的模型名",
    "input": "请回复：连接成功",
    "store": false
  }'

4. 验证 Anthropic Messages（Claude Code 使用）

curl http://hub.thinvent.com/v1/messages \
  -H "x-api-key: sk-你的AI能量庄园密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "从模型广场复制的模型名",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "请回复：连接成功"}]
  }'

5. 后台验收

请求成功后，进入 AI能量庄园日志确认：

• HTTP 状态为成功。
• 用户和令牌识别正确。
• 分组和模型与模型广场选择一致。
• 输入、输出、Token 用量和扣费记录已产生。
• Codex、Claude Code 等工具没有绕过网关请求官方接口。

九、常见问题

十、密钥和网络安全

• API Key 只放在本机环境变量或本机配置文件中，不要提交到 Git。
• 不同项目、不同工具建议使用不同令牌，便于限额、日志和问题追踪。
• 怀疑密钥泄露时，立即在 令牌管理 禁用旧令牌并重新创建。
• HTTP 仅适合可信内网或 VPN；公网使用前应切换 HTTPS。
• 不要把 AI能量庄园令牌和上游厂商 Key、Dify/Coze Key 混用。