WorkBuddy 接入 AI Gateway：小白完整操作指南

本文面向第一次使用 WorkBuddy、第一次配置自定义模型、第一次接触 API 的用户。请从第一步开始按顺序操作。每一步都说明在哪里操作、填写什么、正常返回、下一步和异常处理。

本文以 macOS、WorkBuddy 5.3.14 为例。示例 AI Gateway Base URL：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

如果你的 AI Gateway 不同，只需要替换 Base URL、API Key 和模型 ID。不要把真实 API Key 发到聊天、工单、截图、Git 仓库或公开网页。

本文中的模型状态是 2026-08-18 Asia/Shanghai 的实测快照，不是永久可用承诺。模型目录、租户权限和上游状态都可能变化，正式使用前应重新执行本文的实时检测。

0. 最终要完成什么

完整流程：

安装或确认 WorkBuddy ↓ 准备 Base URL 和 API Key ↓ 查询 OpenAI 协议实时模型目录 ↓ 用标准 curl 验证目标模型 ↓ 在 WorkBuddy 设置中添加自定义模型 ↓ 在 WorkBuddy 中选择模型并发送消息 ↓ 必要时用 WorkBuddy CLI 再验证一次

真正成功必须同时满足：

1. OpenAI 协议的模型目录能看到目标模型；
2. 标准

   /chat/completions

   /chat/completions
   curl 返回 HTTP 200；
3. curl 响应中有实际最终文本；
4. WorkBuddy 选择该自定义模型后能返回实际文本。

只看到模型名称、只保存配置、只出现自定义模型选项，都不能直接说明模型已经可用。

1. 准备信息

1.1 Base URL

Base URL 是 AI Gateway 的接口根地址。本示例使用：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

这个地址已经包含

/v1

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/v1>

WorkBuddy 标准 OpenAI 模式会在 Base URL 后自动补

/chat/completions

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions>

1.2 API Key

请到 AI Gateway 后台创建 API Key，并确认：

• API Key 没有过期；
• API Key 有模型调用权限；
• API Key 与 Base URL 属于同一个环境；
• 复制时没有多余空格或换行；
• 不与其他客户、项目或生产环境共用同一枚 API Key。

本文统一使用“API Key”这个名称。即使某个界面仍显示 Token，也应把 AI Gateway 提供的 API Key 填入对应密钥输入框。

1.3 模型 ID

模型 ID 是 AI Gateway 识别模型的完整字符串，例如：

openai/gpt-5.6-sol deepseek/deepseek-v4-pro qwen/qwen3.6-flash

模型 ID 必须从实时目录原样复制。下面这些写法不是同一个模型：

anthropic/claude-sonnet-4.6 anthropic/claude-sonnet-4-6

1.4 在哪里操作

本文有两类操作位置：

打开 Terminal：按

Command + Space

Terminal

终端提示符可能类似：

a123@Mac ~ %

不要复制提示符本身，只复制代码框中的命令。

2. 确认 WorkBuddy 已安装

2.1 检查应用和版本

在 Terminal 执行：

if [ -d "/Applications/WorkBuddy.app" ]; then defaults read "/Applications/WorkBuddy.app/Contents/Info" CFBundleDisplayName defaults read "/Applications/WorkBuddy.app/Contents/Info" CFBundleShortVersionString else echo "未找到 /Applications/WorkBuddy.app" fi

本机正常返回：

WorkBuddy 5.3.14

如果显示“未找到”，请先从 WorkBuddy 官网下载安装，再重新执行本节命令。

2.2 启动 WorkBuddy

可以双击应用图标，也可以在 Terminal 执行：

open -a "/Applications/WorkBuddy.app"

WorkBuddy 正常打开后，如果界面要求登录，请先按界面提示完成登录。

2.3 检查内置 CLI

WorkBuddy 应用内置

codebuddy

WORKBUDDY_CLI="/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" if [ -x "$WORKBUDDY_CLI" ]; then "$WORKBUDDY_CLI" --version else echo "当前版本未找到内置 CLI，可以继续使用图形界面" fi

返回版本号表示 CLI 可用。CLI 不是完成图形界面配置的必需条件；找不到 CLI 时仍可继续第 3 节。

2.4 是否需要 VPN

本机在当前网络中访问示例 AI Gateway 和运行 WorkBuddy 不需要 VPN。其他网络环境如果出现超时，应先检查 DNS、HTTPS、企业防火墙和代理设置，不要直接把网络超时判断为模型不可用。

**下一步：**先理解 WorkBuddy 的协议限制，再添加模型。

3. 配置前必须理解的限制

3.1 WorkBuddy 自定义模型使用 OpenAI Chat Completions

WorkBuddy 当前自定义模型按 OpenAI Chat Completions 格式发送请求：

POST /chat/completions Authorization: Bearer API_KEY Content-Type: application/json

请求体主要使用：

{ "model": "openai/gpt-5.6-sol", "messages": [ { "role": "user", "content": "你好" } ] }

响应最终文本通常在：

choices[0].message.content

3.2 “自定义协议”不等于 Anthropic 协议

WorkBuddy 中的“自定义协议/Use Custom Protocol”只控制 URL 的处理方式：

/chat/completions

这个开关不会把请求格式从 OpenAI 切换成 Anthropic，也不会自动增加：

x-api-key: API_KEY anthropic-version: 2023-06-01

因此，即使打开“自定义协议”，WorkBuddy 仍不能直接调用只接受 Anthropic

/messages

3.3 模型名称不会自动切换协议

anthropic/claude-opus-5

anthropic/

下面两件事必须同时成立，模型才可能在 WorkBuddy 中使用：

1. 模型能通过 OpenAI

   /chat/completions

   /chat/completions
   调用；
2. WorkBuddy 使用 OpenAI 格式发送请求。

如果一个 Claude 模型只在 Anthropic

/models

/models

3.4 WorkBuddy 不会自动导入整个实时模型目录

WorkBuddy 的自定义模型列表来自本地已保存配置，不是 AI Gateway

/models

例如，AI Gateway 的 OpenAI 目录可能返回 11 个模型，但如果 WorkBuddy 只保存了一个

openai/gpt-5.6-sol

要显示更多模型，需要在 WorkBuddy 中逐个添加，或者通过正确的本地配置文件维护多个模型。

3.5 内置模型和自定义模型不是同一套来源

WorkBuddy 自带的 Hy、GLM、Kimi、DeepSeek 等模型由 WorkBuddy 产品侧提供；通过 AI Gateway 添加的模型属于“自定义模型”。

内置模型成功不代表 AI Gateway 配置成功；自定义模型失败也不代表 WorkBuddy 内置服务故障。

**下一步：**查询 AI Gateway 在 OpenAI 协议下实时提供的模型。

4. 获取实时模型目录

4.1 在当前 Terminal 安全输入 API Key

在 Terminal 执行：

read -s "WORKBUDDY_API_KEY?请输入 API Key（输入时不会显示）：" printf '\n'

输入时没有任何字符出现是正常的。粘贴 API Key 后按回车。

不要执行：

echo "$WORKBUDDY_API_KEY"

4.2 查询 OpenAI 视图

WorkBuddy 使用 OpenAI Chat Completions，因此这是必须查询的目录。在同一个 Terminal 执行：

curl -sS --max-time 30 \ 'https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/models' \ -H "Authorization: Bearer $WORKBUDDY_API_KEY" \ | jq -r '.data[]?.id'

2026-08-18 实时返回 11 个模型：

qwen/qwen3.6-flash deepseek/deepseek-v4-flash deepseek/deepseek-v4-pro openai/gpt-5.4 openai/gpt-5.5 openai/codex-auto-review openai/gpt-5.5-openai-compact openai/gpt-5.4-mini openai/gpt-5.6-sol openai/gpt-5.6-terra openai/gpt-5.6-luna

目录返回成功只说明“模型 ID 对当前 API Key 可见”，不能说明每次实际调用都会成功。

4.3 查询 Anthropic 视图作对比

这一步不是配置 WorkBuddy 的必需步骤，只用于解释为什么 OpenClaw 能看到 Claude，而 WorkBuddy 看不到。

在同一个 Terminal 执行：

curl -sS --max-time 30 \ 'https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/models' \ -H "x-api-key: $WORKBUDDY_API_KEY" \ -H 'anthropic-version: 2023-06-01' \ | jq -r '.data[]?.id'

2026-08-18 实时返回：

qwen/qwen3.6-flash deepseek/deepseek-v4-flash deepseek/deepseek-v4-pro anthropic/claude-sonnet-4.6 anthropic/claude-haiku-4.5 anthropic/claude-sonnet-5 anthropic/claude-opus-4.8 anthropic/claude-opus-5

4.4 为什么同一个

/models

/models

返回不同列表

AI Gateway 会根据认证头和协议视图返回不同模型：

Authorization: Bearer API_KEY → OpenAI 视图 → WorkBuddy 使用这个视图 x-api-key: API_KEY anthropic-version: 2023-06-01 → Anthropic 视图 → OpenClaw 的 Anthropic provider 可以使用

这不是模型目录漏数据，而是两个协议的路由和上游候选不同。

4.5 清除 Terminal 中的 API Key

所有 curl 测试完成后执行：

unset WORKBUDDY_API_KEY

如果下一节还要继续测试，请暂时不要清除；完成第 5 节后再执行。

**下一步：**从 OpenAI 目录复制目标模型 ID，用标准 curl 验证实际调用。

5. 用标准 curl 验证目标模型

5.1 为什么必须先 curl

curl 可以把问题分成两类：

curl 失败 → 优先检查 AI Gateway、API Key、模型、协议或上游 curl 成功，WorkBuddy 失败 → 优先检查 WorkBuddy URL、模型 ID、本地配置和响应解析

如果 curl 失败，不要先反复删除和重装 WorkBuddy。

5.2 测试 OpenAI Chat Completions

如果当前 Terminal 已经清除了 API Key，重新执行：

read -s "WORKBUDDY_API_KEY?请输入 API Key（输入时不会显示）：" printf '\n'

然后执行：

curl -sS --max-time 60 \ 'https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions' \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $WORKBUDDY_API_KEY" \ --data '{ "model": "openai/gpt-5.6-sol", "messages": [ { "role": "user", "content": "请只回复：WorkBuddy Gateway OK" } ], "max_tokens": 256 }' \ -w '\nHTTP %{http_code}\n'

正常成功应同时看到：

HTTP 200 WorkBuddy Gateway OK

如果只有 HTTP 200，但没有最终文字，仍不能判定成功。

5.3 2026-08-18 实测快照

下面是同一 API Key、同一 OpenAI

/chat/completions

qwen/qwen3.6-flash

deepseek/deepseek-v4-flash

deepseek/deepseek-v4-pro

openai/gpt-5.4

openai/gpt-5.5

openai/codex-auto-review

openai/gpt-5.5-openai-compact

openai/gpt-5.4-mini

openai/gpt-5.6-sol

openai/gpt-5.6-terra

openai/gpt-5.6-luna

这张表只代表检测时刻。官网或客户文档应展示“最近检测时间”，不要把一次成功写成永久稳定。

5.4 HTTP 200 但没有最终文本

Qwen、DeepSeek 或其他推理模型可能先输出思考内容。

max_tokens

content

排查时建议：

第一次测试：max_tokens = 256 仍无最终文本：提高到 1024 成功标准：choices[0].message.content 中有最终文字

5.5 完成测试后清除 API Key

unset WORKBUDDY_API_KEY

**下一步：**至少确认一个目标模型 curl 成功后，再进入 WorkBuddy 图形界面保存配置。

6. 在 WorkBuddy 图形界面添加模型

6.1 打开模型设置

在 WorkBuddy 图形界面操作：

打开 WorkBuddy ↓ 进入“设置” ↓ 打开“模型”或“模型配置” ↓ 点击“添加模型” ↓ 选择“自定义 API”或“Custom”

不同版本的按钮位置或中文名称可能略有差异，但核心字段都是 URL、API Key 和模型名/模型 ID。

6.2 推荐填写方式：标准 OpenAI 模式

填写：

https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1

openai/gpt-5.6-sol

标准模式下，WorkBuddy 会自动请求：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions>

6.3 完整 URL 模式

如果当前 WorkBuddy 界面明确要求“完整 API URL”，填写：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions>

同时打开“自定义协议/Use Custom Protocol”，让 WorkBuddy 直接请求这个完整地址。

两种模式只能选择一种：

https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1

https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions

不要配置成：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions/chat/completions>

6.4 保存配置

点击“保存”“添加”或“确认”。保存后等待几秒。

正常现象：

• 自定义模型出现在模型列表；
• 模型名称显示为

  openai/gpt-5.6-sol

  openai/gpt-5.6-sol
  ；
• 可以在对话模型下拉框中选中；
• API Key 输入框可能只显示圆点或星号。

保存成功只表示本地配置已写入，仍要进行第 7 节实际对话测试。

6.5 为什么只出现一个自定义模型

WorkBuddy 不会根据

/models

openai/gpt-5.6-sol

需要更多模型时，重复本节步骤，为每个模型单独添加：

qwen/qwen3.6-flash deepseek/deepseek-v4-flash deepseek/deepseek-v4-pro openai/gpt-5.4-mini openai/codex-auto-review

添加前应重新执行第 5 节 curl，不能只根据目录名称批量宣布可用。

**下一步：**在 WorkBuddy 中选中自定义模型并发送第一条消息。

7. 在 WorkBuddy 中实际使用模型

7.1 打开一个项目

部分 WorkBuddy Agent 功能需要先打开项目文件夹。如果没有现成项目，可以选择一个空文件夹。

如果界面提示“请先打开文件夹”或类似内容，这不是模型调用失败。

7.2 选择自定义模型

在对话或任务界面的模型下拉框中，找到“自定义模型”分组，选择：

openai/gpt-5.6-sol

不要选择同名的内置 Auto 模式来代替自定义模型测试。

7.3 发送最小测试消息

输入：

请只回复：WorkBuddy Gateway OK

正常返回：

WorkBuddy Gateway OK

7.4 如何判断成功

成功必须同时满足：

1. 当前选中的确是自定义模型；
2. 没有自动回退到 WorkBuddy 内置模型；
3. 界面返回实际文本；
4. 没有显示 400、401、502 或模型不存在错误。

如果第一次返回 502，可以短重试 2 至 3 次；如果之后成功，应记录为“存在波动”，不能记录为“稳定成功”。

**下一步：**需要进一步排除界面因素时，使用第 8 节 WorkBuddy CLI 验证。

8. 用 WorkBuddy 自身 CLI 验证

8.1 CLI 使用的是同一份自定义模型配置

WorkBuddy CLI 可以直接选择图形界面保存的自定义模型。CLI 中需要给自定义模型 ID 增加

custom-local:

图形界面模型 ID：

openai/gpt-5.6-sol

CLI 模型 ID：

custom-local:openai/gpt-5.6-sol

custom-local:

openai/gpt-5.6-sol

8.2 检查 CLI 是否识别模型

在 Terminal 执行：

WORKBUDDY_CLI="/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" "$WORKBUDDY_CLI" --help | sed -n '/--model/,+1p'

正常输出中应包含类似：

custom-local:openai/gpt-5.6-sol

如果没有出现，说明模型尚未被 WorkBuddy 本地配置加载。返回第 6 节检查是否保存成功。

8.3 发送最小 CLI 请求

在 Terminal 执行：

WORKBUDDY_CLI="/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" "$WORKBUDDY_CLI" \ -p '请只回复：WorkBuddy Gateway OK' \ --model 'custom-local:openai/gpt-5.6-sol' \ --tools '' \ --output-format text \ --max-turns 1 \ --no-session-persistence

参数含义：

-p

--model

--tools ''

--output-format text

--max-turns 1

--no-session-persistence

正常返回：

WorkBuddy Gateway OK

8.4 当前 WorkBuddy CLI 实测结果

2026-08-18、WorkBuddy 5.3.14、

openai/gpt-5.6-sol

第 1 次：HTTP 502 Upstream failed 第 2 次：HTTP 502 Upstream failed 第 3 次：WorkBuddy Gateway OK

这说明 WorkBuddy 配置和协议最终能够成功，但上游存在波动。官网应写成“已成功调用，检测期间出现 502 波动”，不能只保留第三次成功结果。

8.5 curl 成功但 CLI 失败

按顺序检查：

1. CLI 是否选中

   custom-local:

   custom-local:
   开头的正确模型；
2. WorkBuddy 本地 URL 是否正确；
3. WorkBuddy 是否读取了最新配置；
4. 是否为瞬时 502；
5. 图形界面和 CLI 是否使用同一个 WorkBuddy 数据目录；
6. 是否错误地把 Anthropic 模型加入 OpenAI 自定义配置。

9. 本地配置文件说明

9.1 小白用户优先使用图形界面

WorkBuddy 官方已经支持在设置页添加、编辑和删除自定义模型。图形界面会自动保存 API Key、URL 和能力标记。

除非界面无法打开或需要批量维护模型，不建议小白直接修改 JSON。

9.2 为什么会看到两个配置路径

不同 WorkBuddy/CodeBuddy 版本和产品形态可能使用不同位置：

~/.workbuddy/models.json ~/.codebuddy/models.json

本机 WorkBuddy 5.3.14 实际使用：

~/.workbuddy/models.json

官方 CodeBuddy

models.json

用户级：~/.codebuddy/models.json 项目级：<项目目录>/.codebuddy/models.json

不要只根据网上示例猜路径，应先检查本机实际存在的文件。

9.3 安全查看配置，不显示 API Key

在 Terminal 执行：

for file in "$HOME/.workbuddy/models.json" "$HOME/.codebuddy/models.json"; do if [ -f "$file" ]; then echo "找到：$file" jq ' if type == "array" then map(.apiKey = "<hidden>") elif .models then .models |= map(.apiKey = "<hidden>") else . end ' "$file" fi done

正常返回只应显示：

"apiKey": "<hidden>"

不要直接执行

cat ~/.workbuddy/models.json

9.4 修改前备份

确认本机实际使用

~/.workbuddy/models.json

cp \ "$HOME/.workbuddy/models.json" \ "$HOME/.workbuddy/models.json.backup-$(date +%Y%m%d-%H%M%S)"

列出最近备份：

ls -lt "$HOME/.workbuddy"/models.json.backup-* 2>/dev/null | sed -n '1,5p'

9.5 本机 WorkBuddy 5.3.14 的数组格式

本机图形界面生成的是顶层数组。标准 OpenAI 模式示例：

[ { "id": "openai/gpt-5.6-sol", "name": "openai/gpt-5.6-sol", "vendor": "Custom", "url": "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1", "apiKey": "PASTE_YOUR_API_KEY_HERE", "supportsToolCall": false, "supportsImages": false, "supportsReasoning": false, "useCustomProtocol": false } ]

其中：

• url

  url
  填到

  /v1

  /v1
  ；

• useCustomProtocol

  useCustomProtocol
  为

  false

  false
  ；
• WorkBuddy 自动补

  /chat/completions

  /chat/completions
  ；

• supportsToolCall

  supportsToolCall
  等字段只是客户端能力声明，不是自动检测结果；
• 未完成能力测试时应设置为

  false

  false
  。

9.6 完整 URL 的数组格式

如果必须直接使用完整 URL：

[ { "id": "openai/gpt-5.6-sol", "name": "openai/gpt-5.6-sol", "vendor": "Custom", "url": "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions", "apiKey": "PASTE_YOUR_API_KEY_HERE", "supportsToolCall": false, "supportsImages": false, "supportsReasoning": false, "useCustomProtocol": true } ]

9.7 不要混用两种 JSON 结构

CodeBuddy 官方文档中的另一种结构是：

{ "models": [ { "id": "openai/gpt-5.6-sol", "name": "openai/gpt-5.6-sol", "vendor": "Custom", "url": "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions", "apiKey": "PASTE_YOUR_API_KEY_HERE", "supportsToolCall": false, "supportsImages": false } ], "availableModels": [ "openai/gpt-5.6-sol" ] }

这个对象格式主要对应

~/.codebuddy/models.json

~/.workbuddy/models.json

9.8 配置重新加载

官方文档说明模型文件支持热重载，但不同 WorkBuddy 桌面版本可能有缓存。如果保存后模型未出现：

1. 等待 2 至 3 秒；
2. 切换到其他设置页再返回模型页；
3. 完全退出 WorkBuddy；
4. 重新打开应用。

Terminal 重启方式：

osascript -e 'tell application "WorkBuddy" to quit' 2>/dev/null || true open -a "/Applications/WorkBuddy.app"

9.9 限制配置文件权限

chmod 600 "$HOME/.workbuddy/models.json"

如果实际使用的是

~/.codebuddy/models.json

chmod 600 "$HOME/.codebuddy/models.json"

10. 添加和切换多个模型

10.1 推荐在界面逐个添加

对每个模型重复第 6 节操作，使用相同 Base URL 和 API Key，只修改模型 ID。

例如：

qwen/qwen3.6-flash

deepseek/deepseek-v4-flash

deepseek/deepseek-v4-pro

openai/gpt-5.4-mini

openai/codex-auto-review

openai/gpt-5.6-sol

10.2 添加前先逐个探活

一个模型成功不代表同目录其他模型成功。至少为每个模型记录：

模型 ID 协议 HTTP 状态 是否有最终文本 检测时间 API Key/租户范围

10.3 切换模型

在 WorkBuddy 对话界面的模型下拉框选择目标自定义模型，再发送最小消息。

模型切换不会自动切换协议。所有通过本指南添加的模型仍走 OpenAI Chat Completions。

11. Claude 模型为什么不能直接配置

11.1 AI Gateway 有 Claude，不等于 WorkBuddy 能直接调用

当前 Anthropic 目录可以看到：

anthropic/claude-haiku-4.5 anthropic/claude-opus-4.8 anthropic/claude-opus-5 anthropic/claude-sonnet-4.6 anthropic/claude-sonnet-5

这些模型通过 Anthropic Messages 调用：

POST /messages x-api-key: API_KEY anthropic-version: 2023-06-01

WorkBuddy 自定义模型使用：

POST /chat/completions Authorization: Bearer API_KEY

端点、认证头、请求体和响应体都不同。

11.2 直接填写 Claude ID 为什么会失败

如果把：

anthropic/claude-opus-5

直接填入 WorkBuddy，WorkBuddy 仍会把它发送到

/chat/completions

HTTP 400 No upstream candidates

11.3 “自定义协议”也不能解决

把完整 URL 改成

/messages

因此不建议这样配置：

URL：https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/messages 模型：anthropic/claude-opus-5 自定义协议：开启

11.4 哪些情况下未来可以在 WorkBuddy 使用 Claude

满足任一条件后才可能支持：

1. WorkBuddy 官方增加 Anthropic Messages provider；
2. AI Gateway 把 Claude 映射成 OpenAI Chat Completions 兼容模型，并在 OpenAI

   /models

   /models
   中返回对应 ID；
3. 使用经过完整验证的 OpenAI → Anthropic 协议转换层。

协议转换层还必须正确处理：

• system prompt；
• 流式 SSE；

• tool_calls

  tool_calls
  与

  tool_use

  tool_use
  ；
• 工具结果回传；
• thinking/reasoning；
• token 用量字段；
• 错误码和重试。

只转换 URL 或字段名称不足以保证 Agent 功能正确。

11.5 当前建议

WorkBuddy → 使用 OpenAI Chat Completions 模型 OpenClaw → 使用 Anthropic Messages Claude 模型

12. WorkBuddy 当前能力边界

12.1 本次已验证

本次验证覆盖：

• macOS WorkBuddy 5.3.14；
• OpenAI Chat Completions；
• 非流式纯文本；
• WorkBuddy CLI 实际请求；

• openai/gpt-5.6-sol

  openai/gpt-5.6-sol
  最终成功；
• Qwen、DeepSeek 和部分 OpenAI 模型的标准 curl；
• 502 波动和重试行为。

12.2 本次没有完成可用承诺

以下能力不能由纯文本成功直接推断：

• 流式 SSE；
• 工具调用；
• 多轮工具结果回传；
• 图片、PDF、音频输入；
• JSON Schema 或结构化输出；
• 超长上下文；
• Prompt Cache；
• reasoning/extended thinking；
• 自动重试和故障转移；
• 并发和限流；
• 项目级

  models.json

  models.json
  覆盖；
• Claude 的 Anthropic Messages。

12.3 能力开关只是声明

本地配置中的：

"supportsToolCall": true "supportsImages": true "supportsReasoning": true

只是告诉 WorkBuddy 在界面中开放相应能力，不会自动证明 AI Gateway 和模型真正支持。

正确流程：

先用标准请求验证能力 ↓ 确认模型和网关响应格式正确 ↓ 再打开 WorkBuddy 能力开关

12.4 目录可见、调用成功和稳定可用是三个状态

/models

openai/gpt-5.6-sol

13. 常见问题排查

13.1 WorkBuddy 只显示一个自定义模型

原因：WorkBuddy 显示本地已保存模型，不会自动导入

/models

处理：返回第 6 节，逐个添加需要的模型。

13.2 看不到 Claude

原因：Claude 当前只在 Anthropic 协议视图中，WorkBuddy 自定义模型只使用 OpenAI Chat Completions。

处理：使用 OpenClaw Anthropic provider，或等待 WorkBuddy/AI Gateway 提供 OpenAI 兼容 Claude 映射。

13.3 HTTP 400，路径是

/v1

/v1

原因：请求没有到

/chat/completions

处理：

• 标准模式填写 Base URL 到

  /v1

  /v1
  ，关闭自定义协议；
• 完整 URL 模式填写到

  /v1/chat/completions

  /v1/chat/completions
  ，开启自定义协议。

13.4 HTTP 404 或路径重复

检查错误信息中是否出现：

/chat/completions/chat/completions /v1/v1/chat/completions

如果重复，按第 6.3 节只保留一种 URL 模式。

13.5 HTTP 401 或 403

可能原因：

• API Key 错误；
• API Key 过期；
• API Key 与 Base URL 不属于同一环境；
• API Key 没有模型权限；
• 复制时带入空格或换行。

处理：在 AI Gateway 后台轮换 API Key，重新在 WorkBuddy 中粘贴。

13.6 HTTP 400 No upstream candidates

可能原因：

• 模型 ID 写错；
• 点号写成连字符；
• 模型只存在于 Anthropic 视图；
• 当前 API Key 没有该模型权限；
• 当前协议没有上游候选。

排查顺序：

1. 重新查询 OpenAI

   /models

   /models
   ；
2. 原样复制模型 ID；
3. 用第 5 节 curl；
4. 确认没有把 Claude 加入 OpenAI WorkBuddy 配置；
5. 联系 AI Gateway 管理员检查租户路由。

13.7 HTTP 502 Upstream failed

表示 AI Gateway 已经接到请求，但上游模型调用失败。

处理：

1. 间隔几秒重试 2 至 3 次；
2. 换一个已验证模型；
3. 记录 request ID 和检测时间；
4. 联系 AI Gateway 管理员检查上游；
5. 不要把目录可见写成可用。

13.8 HTTP 200 但没有文字

处理：

1. 把

   max_tokens

   max_tokens
   提高到 256、1024 或 4096；
2. 检查

   choices[0].message.content

   choices[0].message.content
   ；
3. 检查是否只有

   reasoning_content

   reasoning_content
   ；
4. 关闭工具调用后重新做纯文本测试；
5. 确认响应确实是 OpenAI Chat 格式。

13.9 CLI 提示模型不存在

CLI 自定义模型必须加：

custom-local:

正确示例：

custom-local:openai/gpt-5.6-sol

如果仍不存在，检查 WorkBuddy 是否已经加载本地模型配置。

13.10 保存后模型不出现

按顺序处理：

1. 等待 2 至 3 秒；
2. 检查模型 ID 是否为空；
3. 检查 JSON 格式；
4. 检查

   availableModels

   availableModels
   是否过滤了该模型；
5. 完全退出并重开 WorkBuddy；
6. 查看第 14 节日志。

13.11 没有打开项目

WorkBuddy 某些 Agent 功能需要项目上下文。先打开一个文件夹，再发送模型测试消息。

这类提示不是 AI Gateway 请求失败。

13.12 配置写错后恢复

列出备份：

ls -lt "$HOME/.workbuddy"/models.json.backup-* 2>/dev/null | sed -n '1,5p'

确认目标文件名后恢复：

cp \ "$HOME/.workbuddy/models.json.backup-实际时间" \ "$HOME/.workbuddy/models.json"

把“实际时间”替换为上一个命令显示的完整备份文件名。

14. 查看日志时保护 API Key

14.1 日志位置

本机 WorkBuddy 日志通常位于：

~/Library/Logs/WorkBuddy/main.log ~/Library/Logs/WorkBuddy/renderer.log

查看最近错误：

rg -i \ 'error|failed|model|completion|401|403|400|404|502' \ "$HOME/Library/Logs/WorkBuddy/main.log" \ | tail -100

14.2 分享日志前先脱敏

日志可能包含：

• API Key；
• Authorization 请求头；
• 本机路径；
• 用户 ID；
• request ID；
• 对话内容；
• 第三方连接器凭据。

不要直接把完整日志上传工单或发到群聊。分享前至少删除：

Authorization Bearer 后面的值 x-api-key apiKey token secret password 个人目录和对话内容

15. API Key 和配置安全

15.1 API Key 保存在本地

WorkBuddy 官方说明，自定义模型的 API Key 会保存到本地模型配置文件中。因此本地账户、文件备份和日志都应按敏感数据处理。

15.2 必须遵守的安全规则

• 不把

  models.json

  models.json
  上传 Git；
• 不把完整配置截图；
• 不在命令行执行

  echo "$WORKBUDDY_API_KEY"

  echo "$WORKBUDDY_API_KEY"
  ；
• 不在文档中填写真实 API Key；
• API Key 泄露后立即撤销和轮换；
• 不同客户、项目和环境使用不同 API Key；
• 离职、设备报废或停止使用时清理本地 API Key；
• 定期检查 AI Gateway 调用量和费用。

15.3 检查文件是否被 Git 跟踪

如果在项目目录中使用项目级配置，执行：

git status --short git ls-files | rg 'models\.json$' || true

发现含真实 API Key 的文件被跟踪时，应先从 Git 历史和远端仓库处理中删除，并立即轮换 API Key。只在最新提交中删除文件不一定能清除历史泄露。

16. AI Gateway 运营方发布模型的规则

对外不要只发布“模型列表”。至少按协议记录：

openai/gpt-5.6-sol

/models

建议状态名称：

目录可见 curl 已验证 WorkBuddy 已验证 存在波动 当前不可用 协议不支持 能力未验证

不要把下面这些状态合并成一个“支持”：

纯文本支持 流式支持 工具调用支持 图片支持 长上下文支持 Claude/Anthropic 支持

17. 最终成功清单

宣布 WorkBuddy 接入完成前逐项确认：

[ ] /Applications/WorkBuddy.app 存在并能启动 [ ] WorkBuddy 已登录并能打开项目 [ ] Base URL 为 https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1 [ ] API Key 已输入且没有公开 [ ] 使用 OpenAI Chat Completions 协议 [ ] OpenAI /models 能看到目标模型 [ ] 模型 ID 从 OpenAI 目录原样复制 [ ] curl 请求最终到达 /gateway/v1/chat/completions [ ] curl 返回 HTTP 200 [ ] choices[0].message.content 有最终文本 [ ] WorkBuddy 自定义模型已保存 [ ] WorkBuddy 下拉框已选中正确自定义模型 [ ] 图形界面实际消息返回预期文本 [ ] 或 WorkBuddy CLI 返回预期文本 [ ] 已记录 502 等波动，不把一次成功写成稳定成功 [ ] 工具调用、流式和多模态未验证时没有对外承诺 [ ] 没有把 Anthropic Claude 直接加入 OpenAI WorkBuddy 配置 [ ] models.json 权限已限制，API Key 未进入 Git

全部完成后，才可以称为 WorkBuddy 已经通过 AI Gateway 配置并实际使用成功。

如果只有目录查询成功，不能称为模型可用；如果 curl 成功但 WorkBuddy 失败，应优先检查 URL 模式、本地模型 ID、配置加载和 WorkBuddy 日志；如果 curl 和 WorkBuddy 都间歇性 502，应记录为上游波动。

18. 官方参考

WorkBuddy 官方模型配置：

<https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model>

CodeBuddy 官方

models.json

<https://www.workbuddy.cn/docs/ide/Features/models>

使用官方文档时仍需注意版本差异：官方 CodeBuddy 文档中的

~/.codebuddy/models.json

~/.workbuddy/models.json