1. 从一条报错说起：自定义模型接入为什么总在 base_url 上翻车

如果你最近在折腾 WorkBuddy 的自定义模型接入，尤其是想挂一个叫 gpt-6-astra 的模型上去，大概率会撞上这么一条报错：

cc switch local proxy failed while handling codex endpoint /responses.
provider: default; model: gpt-6-astra;
cause: 配置错误: codex provider 缺少 base_url 配置

这条报错信息量其实很大，但很多人第一眼会被 "local proxy failed" 吓到，以为是网络层或者代理层出了问题，然后开始到处查端口、查防火墙、查系统缓存目录能不能改到 D 盘。折腾半天发现根本不是那回事——真正的问题就藏在最后一句： codex provider 缺少 base_url 配置 。

我自己第一次接 gpt-6-astra 的时候也踩了这个坑。当时用的是 WorkBuddy 国际版，本地已经跑通了默认模型，心想加个自定义模型不就是填个名字、填个 key 的事，结果一提交就报这个错。后来才明白，WorkBuddy 的 provider 配置体系里， codex 这个 provider 类型和普通的 OpenAI 兼容 provider 在字段要求上是不一样的，它强制要求 base_url 显式声明，哪怕你觉得自己"已经在别的地方配过了"。

这篇内容就是围绕 WorkBuddy 自定义模型接入 gpt-6-astra 这件事，把 provider 配置、OpenAI 兼容协议、工具调用、本地代理转发这几块串起来讲清楚。适合两类人看：一类是刚装完 WorkBuddy、想接自己模型但被报错卡住的新手；另一类是已经能跑通默认模型、想进一步理解 provider 机制和工具调用链路的进阶用户。我会尽量把"为什么这么配"讲透，而不是只丢一段配置让你抄。

先说结论方向： gpt-6-astra 这类模型接入的核心，不在于模型本身多特殊，而在于你要让 WorkBuddy 相信它是一个 符合 OpenAI 兼容协议、支持工具调用、并且 base_url 明确可达 的服务端点。只要这三件事对齐，剩下的都是细节。

2. gpt-6-astra 接入前必须搞清的三个概念

在动手改配置之前，有三个概念必须先分清楚，否则你会在错误的地方反复试错。这三个概念分别是：provider 类型、OpenAI 兼容协议、以及工具调用（tool calling）的声明方式。它们分别对应"接谁""怎么说话""能干什么"。

2.1 provider 不是模型名，而是"接入方式的分类"

很多人会把 provider 理解成"模型提供商"，比如 OpenAI、Anthropic 这种。但在 WorkBuddy 的配置语境里，provider 更像是一个 接入协议的分类标签 。你写 codex ，系统就按 codex 这套规则去校验你的配置字段；你写 openai ，它就按 OpenAI 兼容那套规则走。

这就解释了为什么报错说的是"codex provider 缺少 base_url"，而不是"gpt-6-astra 缺少 base_url"。因为校验发生在 provider 层，模型名只是 provider 下面的一个字段。你把 provider 选错了，后面模型名填得再对也没用。

我一般建议的做法是： 先确定你的模型服务端点说的是哪种"方言" 。如果它暴露的是标准的 /v1/chat/completions 或者 /v1/responses ，那它大概率应该归到 OpenAI 兼容这一类；如果你用的是某个特定客户端的私有协议，才需要考虑 codex 这类专用 provider。 gpt-6-astra 这个名字听起来像是某个自定义或第三方封装的模型，接入前一定要先确认它对外暴露的接口路径。

2.2 OpenAI 兼容协议：不是"像"就行，字段要对得上

"OpenAI 兼容"这个词被用得很泛，实际上它至少包含三层含义：

• 路径兼容 ：接口路径是 /v1/chat/completions 、 /v1/models 、 /v1/responses 这类。
• 请求体兼容 ： messages 数组、 role 字段、 content 结构、 tools 声明方式一致。
• 响应体兼容 ：返回的 choices 、 message 、 tool_calls 、 finish_reason 结构一致。

很多自建或第三方端点只做到了第一层，路径对了，但请求体里 tools 的格式和 OpenAI 不一致，结果就是模型能聊天、但一调用工具就报错或者静默失败。 gpt-6-astra 如果要做工具调用，这一层必须实测。

我踩过的一个典型坑是：端点接受 tools 字段，但返回的 tool_calls 里 function.arguments 是空字符串而不是 JSON 字符串，导致 WorkBuddy 解析工具调用参数时直接抛异常。这种问题不会在配置阶段暴露，只有真正触发工具调用才会现形。

2.3 工具调用声明：模型"会不会"和"被不被允许"是两回事

工具调用能不能用，取决于两件事：模型本身支持不支持 function calling，以及你的 provider 配置里有没有把工具调用能力打开。前者是模型能力，后者是配置开关。

在 WorkBuddy 里，自定义模型如果没显式声明支持工具调用，系统可能默认按纯文本模型处理，这时候你给它挂 skill、挂 MCP 工具，它也不会去调。所以配置里通常需要类似 supports_tools: true 或者 capabilities: ["tools"] 这样的字段（具体字段名以你所用版本为准，不同版本命名有差异）。

提示：不要假设"模型支持工具调用"就等于"配置里自动开启"。这两步是分开的，很多人卡在第二步。

把这三个概念理清之后，你会发现那条 base_url 报错其实只是冰山一角。真正决定接入成败的，是 provider 类型、协议兼容性、工具调用声明这三件事是否同时对齐。

3. 手把手配置：让 gpt-6-astra 在 WorkBuddy 里跑起来

这一节是实操部分。我会按"先最小可跑通，再逐步加能力"的顺序来写，这样即使中间出错，你也能快速定位是哪一步引入的问题。

3.1 最小配置：先把 base_url 补齐

回到那条报错。修复它的第一步非常直接——在 codex provider 的配置块里补上 base_url 。一个最小可用的配置结构大概长这样（字段名请以你本地版本的 schema 为准，这里给的是通用形态）：

providers:
  default:
    type: codex
    base_url: "https://your-endpoint.example.com/v1"
    api_key: "sk-xxxxxxxx"
    model: "gpt-6-astra"

这里有几个细节值得说：

• base_url 要写到版本号那一层，比如 /v1 ，不要写到 /v1/chat/completions 。多写一段路径是新手最常见的错误之一，会导致拼接出 /v1/chat/completions/chat/completions 这种畸形路径。
• api_key 如果端点不需要鉴权，有些版本允许留空，但建议还是填一个占位符，避免某些校验逻辑因为字段缺失而报错。
• model 字段填 gpt-6-astra ，注意大小写和连字符要和端点侧完全一致，有些端点对模型名是大小写敏感的。

补完 base_url 之后，先别急着测工具调用，先用最简单的对话测一下连通性。如果这一步都过不了，后面全是白搭。

3.2 验证连通性：用 curl 先绕过 WorkBuddy

我的习惯是，在 WorkBuddy 里配置之前，先用 curl 直接打端点，确认服务本身是通的。这样能把"端点问题"和"WorkBuddy 配置问题"彻底分开。

curl -X POST "https://your-endpoint.example.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -d '{
    "model": "gpt-6-astra",
    "messages": [{"role": "user", "content": "ping"}]
  }'

如果这条命令返回了正常的 choices 结构，说明端点和 key 都没问题，问题一定在 WorkBuddy 的配置层。如果这条命令就失败了，那先解决端点问题，别在 WorkBuddy 里瞎折腾。

实测下来，这一步能省掉至少一半的排查时间。很多人一上来就在 WorkBuddy 里改配置、重启、看日志，循环好几轮，其实端点本身就是挂的。

3.3 打开工具调用：从"能聊天"到"能干活"

连通性通过之后，下一步是让 gpt-6-astra 支持工具调用。这一步的配置通常是在 provider 或 model 层级加能力声明。常见写法有两种，取决于你的版本：

providers:
  default:
    type: codex
    base_url: "https://your-endpoint.example.com/v1"
    api_key: "sk-xxxxxxxx"
    model: "gpt-6-astra"
    capabilities:
      - tools
      - streaming

或者：

    supports_tools: true
    supports_streaming: true

配好之后，用一个带工具的请求测一下。最简单的测试是给它一个"查天气"的假工具，看它会不会返回 tool_calls 。如果返回了，说明工具调用链路通了；如果它只是用自然语言回复"我无法查天气"，说明工具声明没生效，或者端点没把 tools 字段透传给模型。

注意：有些端点会"吞掉" tools 字段，也就是你传了但它不转发给底层模型。这种情况下无论你怎么配 WorkBuddy 都没用，得从端点侧解决。

3.4 配置校验清单：提交前逐项过一遍

为了避免反复重启，我整理了一个提交前的校验清单，按顺序过一遍基本能排除大部分低级错误：

检查项	正确做法	常见错误
base_url 层级	写到 /v1	写到 /v1/chat/completions
provider 类型	与端点协议匹配	端点兼容 OpenAI 却选了 codex
模型名	与端点侧完全一致	大小写、连字符不一致
api_key	填有效值或占位符	字段整个缺失
工具能力	显式声明	假设自动开启
路径拼接	确认无重复段	出现双 /chat/completions

这张表看着简单，但每一条我都真实见过有人踩。尤其是路径拼接那条，报错信息往往很隐晦，不会直接告诉你路径重复了。

4. 工具调用链路排查：从请求发出到结果回填

配置跑通只是开始，真正复杂的是工具调用出问题时的排查。这一节我把整条链路拆开讲，让你知道每一步可能在哪里断。

4.1 链路全景：一次工具调用到底经过了什么

一次完整的工具调用，大致经过这几个环节：

1. WorkBuddy 把用户输入 + 工具声明打包成请求，发给 provider。
2. provider 把请求转发给 gpt-6-astra 端点。
3. 端点把请求转给底层模型。
4. 模型决定调用某个工具，返回 tool_calls 。
5. 端点把 tool_calls 原样返回给 WorkBuddy。
6. WorkBuddy 解析 tool_calls ，执行对应工具。
7. WorkBuddy 把工具执行结果作为 tool 角色消息，再次发给模型。
8. 模型基于工具结果生成最终回复。

这八步里，任何一步的字段格式不对，都会导致链路断裂。而断裂的表现往往不是明确的报错，而是"模型好像没看到工具"或者"工具执行了但模型不理会结果"。

4.2 断点定位：三种典型症状对应的问题层

我把常见的工具调用故障归成三类，每类对应不同的排查方向：

• 症状一：模型完全不调用工具，只用自然语言回复。 大概率是工具声明没传到模型。检查 WorkBuddy 配置里工具能力是否开启，再用抓包或日志确认请求体里确实带了 tools 字段。

• 症状二：模型返回了 tool_calls，但 WorkBuddy 报解析错误。 这是响应体格式问题。重点看 tool_calls[].function.arguments 是不是合法的 JSON 字符串。有些端点返回的是对象而不是字符串，WorkBuddy 解析时会挂。

• 症状三：工具执行了，但模型最终回复里没用到结果。 这是第二轮请求的问题。检查 WorkBuddy 回填的 tool 消息里 tool_call_id 是否和模型返回的 id 对得上。对不上，模型就认为这个结果和它的调用无关。

这三类症状覆盖了我遇到过的绝大多数工具调用问题。定位时先判断属于哪一类，再往对应层深挖，比盲目看日志高效得多。

4.3 用日志把请求体"照"出来

排查工具调用，最有效的手段是把实际发出的请求体完整打出来。WorkBuddy 一般有 debug 日志级别，打开之后能看到请求和响应的原始内容。

重点看三样东西：

• 请求里的 tools 数组结构是否符合 OpenAI 规范。
• 响应里的 finish_reason 是不是 tool_calls 。
• 第二轮请求里 messages 是否包含正确的 tool 角色消息。

我自己的经验是，把这三样东西对照着看，90% 的工具调用问题都能定位。剩下 10% 通常是端点侧的兼容性 bug，那就得换端点或者等端点修。

提示：日志里如果看到 arguments 是空字符串 "" ，基本可以判定是端点没正确序列化参数，这不是 WorkBuddy 的问题。

5. 那些配置文档不会告诉你的实操细节

前面讲的是"正确路径"，这一节讲的是"路上那些坑"。这些内容在官方文档里基本找不到，但每一个都能让你多花一两个小时。

5.1 系统缓存目录和配置目录不是一回事

热词里有人问"WorkBuddy 系统缓存目录能改到 D 盘吗"。这个问题本身没错，但要先分清缓存目录和配置目录。缓存目录改了不影响你的 provider 配置，配置目录改了才可能影响模型接入。

我见过有人为了省 C 盘空间把整个数据目录迁到 D 盘，结果配置路径变了，WorkBuddy 读不到原来的 provider 配置，表现就是"模型突然不见了"。所以迁移目录之前，先确认配置文件的实际位置，迁完之后检查配置是否还能被正确加载。

5.2 跨对话记忆和自定义指令会影响工具调用行为

WorkBuddy 有跨对话记忆 skill 和自定义指令功能。这两个东西在纯聊天场景下很好用，但在工具调用场景下可能引入干扰。

举个例子：如果你的自定义指令里写了"回答尽量简洁，不要调用外部工具"，那模型可能就会抑制工具调用。这种冲突不会报错，只会让你觉得"工具怎么不生效"。排查工具调用问题时，建议先把自定义指令和记忆 skill 临时关掉，排除干扰后再逐个加回来。

5.3 本地代理失败不一定是代理的问题

回到最开始那条 "local proxy failed"。很多人看到 proxy 就去查代理设置，其实这条报错的根因是配置校验失败，代理只是恰好在这一层被触发。WorkBuddy 的本地代理负责在客户端和 provider 之间转发请求，配置不合法时，代理在转发前就失败了，于是报出这个看起来像网络问题的错误。

判断方法很简单：如果报错里带了 "配置错误" 字样，那基本就是配置问题，别去查网络。如果报错是超时、连接拒绝这类，才需要看网络和代理。

5.4 模型名里的连字符和版本号要格外小心

gpt-6-astra 这种名字带连字符和版本号的模型名，最容易出的问题是复制粘贴时混入了不可见字符，或者端点侧实际注册的名字和文档写的不一致。我建议配置完之后，先用 /v1/models 接口拉一下端点支持的模型列表，确认 gpt-6-astra 确实在里面，且拼写完全一致。

这一步花不了一分钟，但能避免大量"配置看起来都对就是不通"的玄学问题。

6. 从能跑到好用：接入之后的优化方向

配置跑通、工具调用正常之后，还有几个方向可以让这套接入更稳、更好用。这部分偏进阶，但投入产出比很高。

6.1 给工具调用加超时和重试

工具调用涉及多轮请求，任何一轮超时都会导致整个流程失败。建议在 provider 配置里显式设置超时时间，并针对可重试的错误（比如 5xx）配置重试。超时时间不要设太短，工具调用本身比普通对话慢，设太短会频繁误判失败。

我一般会把超时设在 60 秒以上，重试次数设 2 到 3 次。这样偶发的网络抖动不会直接让工具调用失败。

6.2 用流式输出改善工具调用的体验

工具调用场景下，用户等待时间比普通对话长。开启流式输出（streaming）能让模型在生成最终回复时逐步吐字，体感上快很多。但要注意，流式模式下 tool_calls 的返回方式和非流式不同，是分片返回的，WorkBuddy 需要能正确拼接这些分片。如果你的版本对流式工具调用支持不完善，可以先关掉流式，稳定优先。

6.3 把常用配置固化成模板

如果你经常切换不同的自定义模型，建议把 provider 配置固化成模板，切换时只改 base_url 和 model 两个字段。这样能减少每次重新配置时引入的错误。模板里把 capabilities 、超时、重试这些通用项都写好，切换模型时不用重复填。

6.4 定期检查端点侧的模型更新

自定义模型的端点侧可能会更新模型版本、调整接口行为。建议定期用 curl 跑一遍连通性和工具调用测试，确认行为没有变化。尤其是工具调用的响应格式，端点侧一次不经意的改动就可能让 WorkBuddy 的解析失效。

我个人在实际操作中的体会是，自定义模型接入这件事，配置本身不难，难的是把"配置问题"和"端点问题"分开。一旦你养成了先用 curl 验证端点、再看 WorkBuddy 配置的习惯，排查效率会有质的提升。 gpt-6-astra 这类模型接入的核心，说到底就是让 base_url、协议兼容性、工具调用声明这三件事同时对齐，剩下的都是围绕这三点的细节打磨。