本文面向第一次使用 WorkBuddy、第一次配置自定义模型，或者需要通过 AI Gateway 使用第三方模型的用户。

完成本文后，你将能够：

• 安装并启动 WorkBuddy；
• 安全输入 AI Gateway 的 Base URL 和 API Key；
• 查询自己的 API Key 可以看到的模型；
• 判断模型是否具有 WorkBuddy 所需的 OpenAI Chat Completions 路由；
• 在 WorkBuddy 图形界面添加和选择自定义模型；
• 用标准

  curl

  curl
  和 WorkBuddy 实际消息确认连接；
• 判断 Claude、多协议模型和“自定义协议”开关的适用边界；
• 根据错误信息排查网络、认证、模型路由或本地配置问题。

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

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

本文的标准 OpenAI 配置路径已按 WorkBuddy 5.3.14 完成实际验证。版本号不同不一定有问题；如果按钮名称、配置路径或 CLI 参数不同，请优先使用 WorkBuddy 图形界面，并参考第 18 节的官方资料。

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

模型目录由 AI Gateway 和 API Key 的权限共同决定，可能随租户权限、路由配置和上游状态变化。本文不限定模型数量，也不把示例模型当作完整目录；配置时请以你自己的 API Key 实时查询结果为准。

先看结论：模型厂商和请求协议是两件事

同一个模型名称能否使用，取决于三个条件：模型是否对 API Key 可见、AI Gateway 是否为该协议提供路由、WorkBuddy 是否能发送和解析该协议。模型名称前的厂商前缀不会自动切换协议。

/v1

/chat/completions

/messages

x-api-key

anthropic-version

/chat/completions

/chat/completions

请把“模型目录可见”“协议请求成功”和“WorkBuddy 使用成功”理解为三个不同结果：目录用于找到模型 ID，协议请求用于确认网关路由，WorkBuddy 实际对话用于完成最终验收。本文后续步骤会按这个顺序执行。

最重要的规则是：

模型厂商 ≠ 请求协议 模型出现在目录中 ≠ 该模型已经可以调用 标准 curl 成功 ≠ WorkBuddy 已经配置完成

WorkBuddy 自定义模型的基础连接使用 OpenAI Chat Completions。即使模型同时支持 OpenAI Responses 或 Anthropic Messages，WorkBuddy 也不会根据模型名称自动切换协议。

0. 完整操作路线

第一次配置时，请按以下顺序操作：

1. 安装或确认 WorkBuddy 2. 准备 Base URL 和 API Key 3. 查询自己 API Key 的 OpenAI 模型目录 4. 从目录原样复制一个目标模型 ID 5. 用 OpenAI Chat curl 取得最终文字 6. 在 WorkBuddy 设置中添加这个模型 7. 在 WorkBuddy 中选择模型并发送真实消息 8. 需要时再添加其他模型或使用 CLI 排查

0.1 第一次使用：只完成这五个检查点

如果你的目标是尽快完成第一次对话，不需要先读完全文。请按下表依次操作；只有当前一项成功后，才进入下一项。

/models

/chat/completions

WorkBuddy连接成功

WorkBuddy连接成功

首次配置只使用下面这一组设置：

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

/models

不要在第一次配置时填写

/messages

如果任一检查点失败，请停止在当前检查点，并根据返回的 HTTP 状态码查看第 13 节。反复重装 WorkBuddy 通常不能解决 API Key、模型 ID、协议或上游路由问题。

真正成功必须同时满足：

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

   /chat/completions

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

只看到模型名称、只保存配置、只出现自定义模型选项，都不能直接说明模型已经可用。完成第 7 步后，已经具备基础文本对话能力；工具调用、图片输入、推理模式和其他高级能力的适用范围见第 12 节。

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 识别模型的完整字符串，常见格式是：

厂商名/模型名

本文后续使用

YOUR_MODEL_ID

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

厂商名/模型名-4.6 厂商名/模型名-4-6

1.4 在哪里操作

本文有两类操作位置：

打开 Terminal：按

Command + Space

Terminal

终端提示符可能类似：

user@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 官网下载安装，再重新执行本节命令。

WorkBuddy 官方要求 macOS 12 或更高版本。下载安装包前，在 Terminal 执行：

uname -m

根据返回值选择安装包：

arm64

x86_64

官方安装指南：

<https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Installation-Mac-Guide>

下载

.dmg

Applications

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

是否需要 VPN 取决于所在网络。先完成第 4.1 节，再执行第 4.2 节的目录查询：能够获得 HTTP 响应，就说明请求已经到达服务端；HTTP 200 并返回模型 ID 时不需要 VPN。

如果出现连接超时、域名无法解析或 TLS 连接失败，应依次检查：

1. 浏览器能否访问互联网；
2. 企业网络是否限制外部 HTTPS；
3. DNS、系统代理或防火墙设置；
4. 组织是否要求使用指定的 VPN 或代理。

只有网络连接失败时才需要考虑 VPN；HTTP 400、401、403、429 或 502 都表示请求已经到达服务端，不属于 VPN 问题。

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

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

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

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

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

请求体主要使用：

{ "model": "YOUR_MODEL_ID", "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 模型名称不会自动切换协议

模型 ID 中的

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 目录可能返回多个模型，但如果 WorkBuddy 只保存了一个自定义模型，下拉框通常只显示这一条自定义模型。

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

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

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

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

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

4. 获取实时模型目录

4.1 在当前 Terminal 安全输入连接信息

本节命令使用

jq

if command -v jq >/dev/null 2>&1; then jq --version elif command -v brew >/dev/null 2>&1; then echo "未找到 jq，请执行：brew install jq" else echo "未找到 jq 和 Homebrew，请先访问 https://brew.sh/zh-cn/ 安装 Homebrew" fi

如果输出“未找到 jq”，且电脑已安装 Homebrew，在 Terminal 执行：

brew install jq

安装完成后重新执行上面的检查。Homebrew 下载失败属于本机网络或软件源问题，不代表 AI Gateway 或模型不可用；此时可先切换网络，必要时使用企业允许的 VPN/代理，再重试安装。

在 Terminal 执行：

export WORKBUDDY_BASE_URL='https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1' WORKBUDDY_BASE_URL="${WORKBUDDY_BASE_URL%/}" read -s "WORKBUDDY_API_KEY?请粘贴 AI Gateway API Key，然后按回车：" echo

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

只检查变量是否存在，不显示 API Key：

if [ -n "$WORKBUDDY_API_KEY" ]; then echo 'API Key 已载入当前 Terminal' else echo 'API Key 为空，请重新输入' fi

正常返回：

API Key 已载入当前 Terminal

不要执行：

echo "$WORKBUDDY_API_KEY"

4.2 查询 OpenAI 视图

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

curl -sS -o /tmp/workbuddy-models-openai.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$WORKBUDDY_BASE_URL/models" \ -H "Authorization: Bearer $WORKBUDDY_API_KEY"

返回含义：

/v1

/v1

HTTP 200 后执行：

jq -r ' if (.data | type) == "array" then .data[].id else .error.message // .message // "没有读取到模型目录" end ' /tmp/workbuddy-models-openai.json

如果不是 HTTP 200，查看脱敏错误内容：

jq ' if .error then {error: .error} else {message: .message, code: .code} end ' /tmp/workbuddy-models-openai.json

正常情况下，每行显示一个模型 ID，例如：

厂商名/模型名

实际数量和名称由当前 API Key 决定。请从返回结果中原样复制准备使用的模型 ID，不要删除厂商前缀，也不要修改点号、连字符或版本号。目录返回成功只说明该模型 ID 对当前 API Key 可见，还需要通过第 5 节验证实际调用。

如果已经收到 200、401、403、404、429 或 5xx，说明域名能够访问，通常不是 VPN 问题。只有域名解析失败、连接超时或网络策略拦截时，才需要检查代理或 VPN。

4.3 仅在排查 Claude 或多协议模型时：查询 Anthropic 视图

这一步不是配置 WorkBuddy 的必需步骤。第一次配置、只使用 OpenAI Chat 模型，或者第 5.2 节已经成功时，请跳过本节。只有需要排查 Claude 或同时支持多个协议的模型时，才使用本节检查 Anthropic 客户端可以看到哪些模型，以及为什么它可能与 WorkBuddy 的列表不同。

在同一个 Terminal 执行：

curl -sS -o /tmp/workbuddy-models-anthropic.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$WORKBUDDY_BASE_URL/models" \ -H "x-api-key: $WORKBUDDY_API_KEY" \ -H 'anthropic-version: 2023-06-01'

HTTP 200 后执行：

jq -r ' if (.data | type) == "array" then .data[].id else .error.message // .message // "没有读取到 Anthropic 模型目录" end ' /tmp/workbuddy-models-anthropic.json

如果返回了 Claude、DeepSeek、Qwen 或其他模型，只能说明这些模型在 Anthropic 协议视图中可见。它们是否也能用于 WorkBuddy，仍要回到第 4.2 节的 OpenAI 目录，并通过 OpenAI Chat Completions 测试。

/models

/messages

/chat/completions

4.4 为什么同一个

/models

/models

返回不同列表

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

Authorization: Bearer API_KEY → OpenAI 视图 → WorkBuddy 使用这个视图 x-api-key: API_KEY anthropic-version: 2023-06-01 → Anthropic 视图 → 支持 Anthropic Messages 的客户端使用这个视图

因此，同一个

/models

4.5 继续使用当前 Terminal

第 5 节还会使用

WORKBUDDY_BASE_URL

WORKBUDDY_API_KEY

**下一步：**从 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 变量，请重新执行第 4.1 节，不要只重新输入 API Key 而遗漏 Base URL。

先输入准备配置的模型 ID：

read "WORKBUDDY_MODEL_ID?请输入 OpenAI 目录中的模型 ID："

模型 ID 必须来自第 4.2 节的 OpenAI 目录。然后执行：

curl -sS -o /tmp/workbuddy-test-chat.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$WORKBUDDY_BASE_URL/chat/completions" \ -H "Authorization: Bearer $WORKBUDDY_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$WORKBUDDY_MODEL_ID" \ '{ model: $model, messages: [{role: "user", content: "请只回复：WorkBuddy连接成功"}], max_tokens: 512, stream: false }')"

提取最终文字或错误信息：

jq -r ' .choices[0].message.content // .error.message // .message // "HTTP 已返回，但没有找到最终文字" ' /tmp/workbuddy-test-chat.json

成功时应看到：

HTTP 200 WorkBuddy连接成功

只有 HTTP 200 和最终文字同时出现，才能继续配置 WorkBuddy。HTTP 200 但没有最终文字时，按照第 5.6 节处理。

5.3 厂商、模型与协议的关系

AI Gateway 可以为不同厂商模型提供不同协议入口。厂商名称说明模型来源，协议决定请求和响应格式；两者不是一回事。

/chat/completions

/chat/completions

/chat/completions

/chat/completions

这里的“可能提供”表示 AI Gateway 可以按不同方式暴露模型，不表示每一枚 API Key 都拥有相同协议和模型。最终结果始终以实时目录和标准请求为准。

5.4 WorkBuddy 使用哪些协议

POST /v1/chat/completions

POST /v1/responses

POST /v1/messages

因此，为 WorkBuddy 选模型时只需要遵循这条判断路径：

OpenAI /models 中可见 ↓ OpenAI /chat/completions 返回 HTTP 200 和最终文本 ↓ 添加到 WorkBuddy ↓ WorkBuddy 实际对话成功

5.5 仅在排查 Claude 或多协议模型时：验证 Anthropic Messages

这一步只用于确认 AI Gateway 的 Anthropic 路由，不用于配置 WorkBuddy。第一次配置 WorkBuddy 时请跳过本节；只有需要判断某个 Claude、DeepSeek、Qwen 或其他模型是否同时具有 Anthropic Messages 路由时才执行。

先输入 Anthropic 目录中原样复制的模型 ID：

read "ANTHROPIC_MODEL_ID?请输入 Anthropic 目录中的模型 ID："

然后执行：

curl -sS -o /tmp/workbuddy-test-anthropic.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$WORKBUDDY_BASE_URL/messages" \ -H "x-api-key: $WORKBUDDY_API_KEY" \ -H 'anthropic-version: 2023-06-01' \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$ANTHROPIC_MODEL_ID" \ '{ model: $model, max_tokens: 512, messages: [{role: "user", content: "请只回复：Anthropic连接成功"}] }')"

提取最终文字或错误信息：

jq -r ' ([.content[]? | select(.type == "text") | .text] | join("\n")) as $text | if ($text | length) > 0 then $text else .error.message // .message // "HTTP 已返回，但没有找到最终文字" end ' /tmp/workbuddy-test-anthropic.json

成功时应看到 HTTP 200 和

Anthropic连接成功

/chat/completions

5.6 HTTP 200 但没有最终文本

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

max_tokens

content

排查时建议：

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

5.7 完成测试后清除敏感变量

rm -f \ /tmp/workbuddy-models-openai.json \ /tmp/workbuddy-models-anthropic.json \ /tmp/workbuddy-test-chat.json \ /tmp/workbuddy-test-anthropic.json unset WORKBUDDY_API_KEY unset WORKBUDDY_BASE_URL unset WORKBUDDY_MODEL_ID unset ANTHROPIC_MODEL_ID

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

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

6.1 打开模型设置

在 WorkBuddy 图形界面操作：

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

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

进入正确页面后，应当能看到与下面含义相同的字段。字段顺序可能不同，不要求界面与示意完全一致：

┌──────────────────────────────────────────────┐ │ 添加自定义模型 │ ├──────────────────────────────────────────────┤ │ URL / Base URL [ ] │ │ API Key [••••••••••••••••••••] │ │ 模型 ID / 模型名 [ ] │ │ 自定义协议 [关闭] │ │ 工具调用 [关闭] │ │ 图片输入 [关闭] │ │ 推理模式 [关闭] │ │ [保存/添加] │ └──────────────────────────────────────────────┘

如果当前页面没有 URL、API Key 或模型 ID 字段，说明还没有进入“自定义 API/Custom”模型配置页面，请返回上一层重新选择。

6.2 首次配置和日常使用：标准 OpenAI 模式

这是本文已完成实际验证的配置方式，也是首次配置时唯一需要执行的方式。

填写：

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

YOUR_MODEL_ID

首次保存时，工具调用、图片输入和推理模式全部保持关闭。基础文本对话成功并不代表这些高级能力已经可用；开启条件见第 12 节。

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

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

6.3 备用：界面明确要求完整 API URL 时

如果第 6.2 节已经可以保存并正常对话，请跳过本节，不要更改为完整 URL 模式。

只有当前 WorkBuddy 界面明确要求“完整 API URL”，或者标准模式的错误日志明确显示 WorkBuddy 没有补全

/chat/completions

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

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

这里的“自定义协议”只是让 WorkBuddy 直接使用完整 URL，不会把请求转换为 Anthropic Messages，也不能用于填写

/messages

两种模式只能选择一种：

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 保存配置

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

正常现象：

• 自定义模型出现在模型列表；
• 模型名称显示为你刚才填写的完整模型 ID；
• 可以在对话模型下拉框中选中；
• API Key 输入框可能只显示圆点或星号。

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

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

WorkBuddy 不会根据

/models

需要更多模型时，对第 4.2 节 OpenAI 目录中的目标模型逐个执行第 5.2 节 curl。只有返回 HTTP 200 和最终文本的模型，才继续重复第 6 节添加步骤。目录中的模型数量、名称和可用状态可能随 API Key 变化，因此不要直接复制其他用户的模型列表。

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

7. 在 WorkBuddy 中实际使用模型

7.1 打开一个项目

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

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

7.2 选择自定义模型

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

YOUR_MODEL_ID

这里要选择第 6 节实际保存的模型 ID；如果界面真的显示字面值

YOUR_MODEL_ID

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

7.3 发送最小测试消息

输入：

请只回复：WorkBuddy连接成功

正常返回：

WorkBuddy连接成功

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：

YOUR_MODEL_ID

CLI 模型 ID：

custom-local:YOUR_MODEL_ID

custom-local:

8.2 检查 CLI 是否识别模型

在 Terminal 执行：

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

如果输出中包含类似下面的条目，说明 CLI 已经识别到自定义模型：

custom-local:YOUR_MODEL_ID

部分版本的

--help

8.3 发送最小 CLI 请求

先输入图形界面中已经保存的完整模型 ID：

read "WORKBUDDY_MODEL_ID?请输入已保存的自定义模型 ID："

然后在同一个 Terminal 执行：

WORKBUDDY_CLI="/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy" "$WORKBUDDY_CLI" \ -p '请只回复：WorkBuddy连接成功' \ --model "custom-local:$WORKBUDDY_MODEL_ID" \ --tools '' \ --output-format text \ --max-turns 1 \ --no-session-persistence

参数含义：

-p

--model

--tools ''

--output-format text

--max-turns 1

--no-session-persistence

正常返回：

WorkBuddy连接成功

8.4 如何理解 CLI 结果

WorkBuddy连接成功

custom-local:

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 和能力标记。

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

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

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

部分 WorkBuddy 桌面版本使用：

~/.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 修改前备份

在 Terminal 执行。命令只会备份当前实际存在的文件：

for models_file in \ "$HOME/.workbuddy/models.json" \ "$HOME/.codebuddy/models.json"; do if [ -f "$models_file" ]; then backup_file="$models_file.backup-$(date +%Y%m%d-%H%M%S)" cp "$models_file" "$backup_file" echo "已备份：$backup_file" fi done

列出最近备份：

find "$HOME/.workbuddy" "$HOME/.codebuddy" \ -maxdepth 1 \ -type f \ -name 'models.json.backup-*' \ -print 2>/dev/null \ | sort \ | tail -10

9.5 WorkBuddy 顶层数组格式示例

如果现有

~/.workbuddy/models.json

[

[ { "id": "YOUR_MODEL_ID", "name": "YOUR_MODEL_ID", "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
  。

如果电脑上已经有能正常使用的

models.json

id

name

url

apiKey

useCustomProtocol

手动使用示例时，必须把所有

YOUR_MODEL_ID

PASTE_YOUR_API_KEY_HERE

9.6 完整 URL 的数组格式

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

[ { "id": "YOUR_MODEL_ID", "name": "YOUR_MODEL_ID", "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": "YOUR_MODEL_ID", "name": "YOUR_MODEL_ID", "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": [ "YOUR_MODEL_ID" ] }

这个对象格式主要对应

~/.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。

模型 ID 必须来自你自己的 OpenAI 目录查询结果，并且每个模型都要单独通过第 5.2 节。不要从文档、截图或其他用户的配置中批量复制模型 ID，因为不同 API Key 的模型范围可能不同。

10.2 添加前先逐个探活

一个模型成功不代表同目录其他模型成功。排查多个模型时，建议为每个模型记录：

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

10.3 切换模型

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

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

11. 请求协议和配置边界

11.1 三种协议不能混用

/chat/completions

/responses

/messages

Authorization: Bearer

Authorization: Bearer

x-api-key

anthropic-version

messages

input

messages

system

max_tokens

max_output_tokens

max_tokens

choices[].message.content

output[].content[].text

content[]

type=text

只修改 URL 或模型名称，不能把一种协议变成另一种协议。端点、认证头、请求体、流式事件、响应结构和工具调用格式必须一起匹配。

11.2 先确认 Claude 出现在哪个协议目录

Claude 的原生接口通常使用 Anthropic Messages：

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

WorkBuddy 当前自定义模型使用 OpenAI Chat Completions：

POST /chat/completions Authorization: Bearer API_KEY

因此，Claude 或其他模型能否用于 WorkBuddy，不由模型名称决定，而由它是否具有 OpenAI Chat 兼容路由决定：

/messages

/chat/completions

/chat/completions

11.3 为什么完整

/messages

/messages

URL 不能切换协议

WorkBuddy 的“自定义协议/Use Custom Protocol”名称容易引起误解。这个开关只决定 URL 是否由 WorkBuddy 自动补全，不会自动完成下面这些转换：

• 把 OpenAI

  messages

  messages
  请求体转换为 Anthropic Messages 请求体；
• 增加

  anthropic-version

  anthropic-version
  ；
• 把 OpenAI system 消息转换为 Anthropic 顶层

  system

  system
  ；
• 把 Anthropic

  content[]

  content[]
  响应转换为 OpenAI

  choices[]

  choices[]
  ；
• 转换流式事件、工具调用和工具结果。

因此不要使用下面的组合尝试开启 Anthropic 协议：

URL：https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/messages 模型：Anthropic 目录中的 Claude 模型 ID 自定义协议：开启

这个组合只会让 WorkBuddy 请求

/messages

11.4 在 WorkBuddy 中使用 Claude 的正确条件

如果需要在 WorkBuddy 中使用 Claude，请先确认 AI Gateway 是否提供“OpenAI Chat Completions 兼容的 Claude 映射”。确认方法与其他模型完全相同：

1. 使用

   Authorization: Bearer API_KEY

   Authorization: Bearer API_KEY
   查询 OpenAI

   /models

   /models
   ；
2. 从返回结果中复制对应模型 ID；
3. 使用该 ID 请求

   /chat/completions

   /chat/completions
   ；
4. 确认 HTTP 200 且

   choices[0].message.content

   choices[0].message.content
   有最终文字；
5. 按第 6 节使用标准模式配置。

如果 AI Gateway 只提供 Anthropic Messages，请改用原生支持 Anthropic provider 的客户端。不要把 Anthropic 目录中的模型 ID 直接复制到 WorkBuddy。

11.5 DeepSeek、Qwen 等多协议模型

部分模型可能同时出现在 OpenAI 和 Anthropic 目录。它们在不同客户端中可以使用不同协议，但 WorkBuddy 不会根据模型名称自动选择协议。

在 WorkBuddy 中始终使用：

OpenAI 目录中的模型 ID Base URL：https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1 自定义协议：关闭 验证端点：/chat/completions

Anthropic 目录中的成功结果只说明该模型还可供 Anthropic 客户端使用，不会改变 WorkBuddy 的配置方式。

11.6 目录、curl 和 WorkBuddy 分别说明什么

/models

/chat/completions

一个阶段成功不能替代下一阶段。目录成功但 curl 失败时，应排查协议、权限或上游路由；curl 成功但 WorkBuddy 失败时，应排查 URL 模式、模型 ID 和本地配置加载。

12. WorkBuddy 能力边界

12.1 完成基础配置后可以做什么

按照第 4 至第 7 节完成验证，表示下面这条链路已经工作：

WorkBuddy → OpenAI Chat Completions 请求 → AI Gateway → 目标模型 → 返回文本结果

这足以确认基础文本对话可以使用，但不能自动说明工具调用、图片输入或其他高级能力也可用。

12.2 高级能力需要分别验证

tools

tool_calls

12.3 能力开关只是声明

本地配置中的：

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

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

正确流程：

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

12.4 如何判断当前支持状态

/models

如果某个模型只达到“目录可见”，请继续执行 curl；如果 curl 成功但 WorkBuddy 失败，请检查 WorkBuddy 配置；如果偶尔成功、偶尔 502，应先按上游波动处理，不能把单次成功当作稳定状态。

WorkBuddy 任务还可能读取项目文件、运行工具或访问连接器。模型连接成功不等于应该开放全部本机权限。启用这些能力前，请同时检查项目范围、工具权限、默认权限与安全沙箱，以及连接器中可访问的数据。

13. 常见问题排查

13.1 API Key 粘贴时没有字符

正常。第 4.1 节使用

read -s

echo

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

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

/models

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

13.3 看不到 Claude

原因：当前 API Key 的 Claude 可能只出现在 Anthropic 协议视图中，而 WorkBuddy 自定义模型使用 OpenAI Chat Completions。

处理：按照第 11.4 节检查 AI Gateway 是否提供 OpenAI Chat 兼容的 Claude 映射。如果没有，请使用支持 Anthropic provider 的客户端。

13.4 curl 显示 HTTP 000 或连接超时

HTTP 000

处理：

1. 确认浏览器可以正常访问互联网；
2. 执行

   nslookup cn-shanghai-alicloud-aimesh.api.clickzetta.com

   nslookup cn-shanghai-alicloud-aimesh.api.clickzetta.com
   检查域名解析；
3. 检查系统代理和企业防火墙；
4. 如果组织要求使用 VPN 或代理，连接后重新测试；
5. 网络恢复后重新执行第 4.2 节。

13.5 HTTP 400，路径是

/v1

/v1

原因：请求没有到

/chat/completions

处理：

• 标准模式填写 Base URL 到

  /v1

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

  /v1/chat/completions

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

13.6 HTTP 404 或路径重复

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

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

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

13.7 HTTP 401 或 403

可能原因：

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

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

13.8 HTTP 400 No upstream candidates

可能原因：

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

排查顺序：

1. 重新查询 OpenAI

   /models

   /models
   ；
2. 原样复制模型 ID；
3. 用第 5 节 curl；
4. 确认没有把仅在 Anthropic 目录可见的 Claude 模型直接加入 WorkBuddy；
5. 联系 AI Gateway 管理员检查租户路由。

13.9 HTTP 429 Too Many Requests

表示请求频率、并发数、账户额度或上游限额受到限制。

处理：

1. 降低请求频率和并发；
2. 等待错误响应或响应头中指定的重试时间；
3. 检查 AI Gateway 账户额度和限流策略；
4. 不要立即进行高频连续重试。

13.10 HTTP 502 Upstream failed

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

处理：

1. 间隔几秒重试 2 至 3 次；
2. 换一个已验证模型；
3. 记录 request ID 和检测时间；
4. 联系 AI Gateway 管理员检查上游；
5. curl 恢复为 HTTP 200 并返回最终文本后，再继续 WorkBuddy 配置。

13.11 HTTP 200 但没有文字

处理：

1. 把

   max_tokens

   max_tokens
   从 512 提高到 1024；仍无最终文本时再提高到 4096；
2. 检查

   choices[0].message.content

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

   reasoning_content

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

13.12 CLI 提示模型不存在

CLI 自定义模型必须加：

custom-local:

正确示例：

custom-local:YOUR_MODEL_ID

请把

YOUR_MODEL_ID

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

13.13 保存后模型不出现

按顺序处理：

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

   availableModels

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

13.14 没有打开项目

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

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

13.15 curl 成功，但 WorkBuddy 失败

说明 AI Gateway 的基础模型路由已经可用，问题更可能出在 WorkBuddy 本地配置或模型选择。按顺序检查：

1. 当前选择的是“自定义模型”分组中的目标模型，不是同名内置模型；
2. 标准模式的 URL 是

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

   https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1
   ；
3. 标准模式下“自定义协议”保持关闭；
4. WorkBuddy 中的模型 ID 与 curl 使用的 ID 完全一致；
5. 暂时关闭工具调用、图片和推理模式，只测试纯文本；
6. 按照第 9.8 节重新加载 WorkBuddy；
7. 需要进一步定位时，使用第 8 节 CLI 测试同一个模型。

13.16 配置写错后恢复

列出备份：

find "$HOME/.workbuddy" "$HOME/.codebuddy" \ -maxdepth 1 \ -type f \ -name 'models.json.backup-*' \ -print 2>/dev/null \ | sort \ | tail -10

如果当前使用

~/.workbuddy/models.json

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

如果当前使用

~/.codebuddy/models.json

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

只执行与当前配置路径匹配的一条命令。不要原样输入“实际时间”，应替换为上一个命令列出的准确文件名。恢复后按照第 9.8 节重新加载 WorkBuddy。

13.17 联系客户支持前准备这些信息

如果按照本节仍无法解决，请通过官方私密支持渠道提交下面的信息。内容越完整，越容易判断问题发生在本地配置、AI Gateway 还是上游模型：

问题发生时间：YYYY-MM-DD HH:MM（请注明时区） WorkBuddy 版本： macOS 版本： 配置方式：标准 Base URL / 备用完整 URL Base URL：https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1 模型 ID： OpenAI /models HTTP 状态码： OpenAI /chat/completions HTTP 状态码： WorkBuddy 图形界面错误摘要： WorkBuddy CLI 是否复现：是 / 否 / 未测试 是否偶发成功：是 / 否 脱敏 request ID（如有）： 已经执行的排查步骤：

可以在 Terminal 获取版本信息：

defaults read "/Applications/WorkBuddy.app/Contents/Info" CFBundleShortVersionString sw_vers -productVersion

提交前必须删除或遮盖：

• API Key、

  Authorization

  Authorization
  和

  x-api-key

  x-api-key
  的值；
• 完整

  models.json

  models.json
  ；
• 对话内容、项目代码、文件路径和个人信息；
• 与问题无关的完整日志。

request ID 可以帮助官方支持人员定位同一次请求，但只应通过可信的私密支持渠道提交，不要发布到公开网页、群聊或截图中。不要为了复现问题而公开、重复打印或重新发送 API Key。

14. 查看日志时保护 API Key

14.1 日志位置

优先在 WorkBuddy 图形界面中操作：

顶部菜单“帮助” ↓ 打开日志文件夹

这是最不受版本和文件名变化影响的方式。

macOS 上常见的 WorkBuddy 日志位置是：

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

不同版本的日志文件名可能不同。查看现有日志文件：

find "$HOME/Library/Logs/WorkBuddy" \ -maxdepth 1 \ -type f \ -print 2>/dev/null

如果目录存在，可以查看最近错误：

for log_file in "$HOME/Library/Logs/WorkBuddy"/*.log(N); do if [ -f "$log_file" ]; then echo "日志：$log_file" rg -i \ 'error|failed|model|completion|401|403|400|404|429|502' \ "$log_file" \ | tail -100 fi done

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. 配置完成后会看到什么

16.1 模型设置页

保存成功后，自定义模型会出现在 WorkBuddy 的模型列表中。模型数量取决于你手动添加了多少条配置，不等于 AI Gateway

/models

16.2 对话或任务页面

在模型选择器中选中自定义模型后，发送消息会经由以下路径处理：

你的输入 ↓ WorkBuddy 自定义模型 ↓ <https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions> ↓ AI Gateway 路由到目标模型 ↓ WorkBuddy 显示模型返回的结果

16.3 费用和内容处理

自定义模型的调用额度和费用由你的 AI Gateway 账户承担。发送给自定义模型的提示词、项目上下文和附件可能被传输到所配置的 AI Gateway 及其上游模型，请在使用前确认组织的数据安全和合规要求。

16.4 成功配置不代表所有功能都已开启

基础文本对话成功后，可以正常开始使用文本任务。工具调用、图片、推理模式、长上下文等能力应按照第 12 节分别验证，再决定是否开启对应选项。

17. 完成检查清单

完成 WorkBuddy 配置前逐项确认。第一组是基础文本对话的必选项；第二组只在使用相应功能或遇到相应问题时检查。

基础配置必选： [ ] /Applications/WorkBuddy.app 存在并能启动 [ ] curl 和 jq 可以执行 [ ] WorkBuddy 版本检查能够返回版本号 [ ] WorkBuddy 已登录并能打开项目 [ ] Base URL 为 https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1 [ ] API Key 已输入且没有公开 [ ] 使用 OpenAI Chat Completions 协议 [ ] 标准模式下“自定义协议”保持关闭 [ ] OpenAI /models 能看到目标模型 [ ] 模型 ID 从 OpenAI 目录原样复制 [ ] 已理解第 5.3、5.4 节的厂商和协议边界 [ ] curl 请求最终到达 /gateway/v1/chat/completions [ ] curl 返回 HTTP 200 [ ] choices[0].message.content 有最终文本 [ ] WorkBuddy 自定义模型已保存 [ ] WorkBuddy 下拉框已选中正确自定义模型 [ ] 图形界面实际消息返回预期文本 [ ] 工具调用、流式和多模态未验证时保持对应能力关闭 [ ] 没有把仅在 Anthropic 目录可见的模型直接加入 WorkBuddy [ ] models.json 权限已限制，API Key 未进入 Git 按需检查： [ ] 如使用 CLI，CLI 也返回预期文本 [ ] 如使用备用完整 URL，地址到 /chat/completions 且“自定义协议”已开启 [ ] 如果出现 502，已在恢复后重新完成 curl 和 WorkBuddy 验证 [ ] 如需 Claude 或多协议模型，已分别确认其 OpenAI 和 Anthropic 协议结果 [ ] 如需工具调用、图片或推理模式，已分别完成端到端能力验证

“基础配置必选”全部完成后，表示 WorkBuddy 已经通过 AI Gateway 完成基础文本模型配置，可以开始使用。“按需检查”不适用于当前场景时可以留空，不影响基础文本对话验收。

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

18. 官方参考

• WorkBuddy 官网：https://www.workbuddy.cn/
• WorkBuddy Mac 安装指南：https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Installation-Mac-Guide
• WorkBuddy 模型配置：https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Model
• WorkBuddy 常见问题：https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/FAQ
• CodeBuddy

  models.json

  models.json
  配置指南：https://www.workbuddy.cn/docs/ide/Features/models

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

~/.codebuddy/models.json

~/.workbuddy/models.json