把 FaceSolo 接进你的开发工具

📋 模型 id 从哪来、填在哪：在配置向导里选好模型后，下面这段会自动填成你选的那个，粘进第 2 步 + Add Custom Model 的输入框——Cursor 这里没有字段名，那个框里填的一整串就是模型 id。换模型时，第 5 步「只留你第 2 步加的那个」也要跟着换成同一个 id。
⚠️ 地址结尾必须是 /v1——Cursor 会自己往后拼 /chat/completions。
⚠️ 加模型和填密钥都在 Models 页的最下面：顺序是 模型开关长列表 → + Add Custom Model → 折叠的 API Keys。只看第一屏会以为这版没有自定义 key 功能。
⚠️ 第 5 步「关掉 Cursor 自带模型」不能省：那条校验请求用哪个模型由 Cursor 自己挑，它在你已启用的模型里按 OpenAI 那几个常见名字做子串匹配 —— 挑中的一定是个不带斜杠的裸名，而我们只认 厂商/型号，于是被拒。只要还开着任一内置模型，它就会挑中那个不带斜杠的名字发过来，而我们要求模型 id 形如 厂商/型号，于是被拒、密钥存不进去。
⚠️ 模型 id 必须带斜杠前缀：Cursor 按前缀决定用哪把密钥——claude- 开头找 Anthropic 槽、gemini- 开头找 Google 槽，带斜杠的才走 OpenAI 槽。写成不带斜杠的裸型号会让它去找一个空槽，结果是静默地不带凭据发出去，走 Cursor 自己的计费——你既看不到报错，也省不到钱。

能用到什么程度：Chat 面板问答、在对话里生成代码都正常。Agent / Composer / Tab / 以及把代码 Apply 进文件用不了——Cursor 明确说这几项依赖它自家的专有模型、不能记到 API key 上，请求根本不会发到我们这里。要在编辑器里用完整智能体能力，请用 Claude Code 或 Codex CLI。

🔧 出问题怎么判：
• 「The model you chose is not available」 → 请求多半没发出去。先查 Use OpenAI API key 开关是否打开，再查 Base URL 结尾有没有 /v1。
• 「User Provided API Key Rate Limit Exceeded」 → 未必真是限流，Cursor 会把连续失败也显示成这句。直接联系我们即可——我们能查到那把密钥最近一次调用打的是哪个端点、被拒原因是什么。
• 报错里出现字段名 / schema / model_not_found / 401 / 403 → 请求已经到我们这里，把原文发我们。

💰 成本提醒（不是故障）：Cursor 每一轮都会把系统提示、工具定义、工作区信息全量重发，一句短问题的输入量也在两万 token 以上。在 Cursor 里的花费主要由输入决定，跟你问得长不长几乎无关，估算预算时请按这个量级算。

📋 模型 id 从哪来、填在哪：在配置向导里选好模型后，下面这段会自动填成你选的那个，填进上面第 3 步那个 模型 ID 字段（三个字段里的最后一个，前两个是 Base URL 与 API Key），必须带 厂商/ 前缀。
⚠️ 这三个字段在你那版 WorkBuddy 里叫什么，以它自己的界面为准：我们只核对到「它走 OpenAI 兼容协议」这一层，没有逐字段核对过它的菜单路径、配置文件位置或环境变量名。找不到对应输入框时，去「OpenAI 兼容 / 自定义模型 / 第三方模型」那一类设置里找这三样东西。
你这把密钥实际能用的清单以 GET /v1/models 为准（它还会按你的档位与密钥白名单过滤；有充值余额时不限档位）。
⚠️ 若它要求单独声明「是否支持工具调用」：由配置向导按你选的模型自动填好（它按你的密钥实测得出，不是照抄示例），别一律 true。若它是每轮发工具定义的 agent 型客户端，模型还有子集限制——anthropic/* 都支持工具调用，其余厂商要在我们的实测白名单内。

📋 模型 id 从哪来、填在哪：在配置向导里选好模型后，下面这段会自动填成你选的那个。插件版填 models.json 里 models[].id（同一项的 name 只是下拉里显示的名字，随便起）；命令行版填环境变量 CODEBUDDY_MODEL，或每次启动用 --model 指定。
插件版
⚠️ url 要写完整路径，以 /chat/completions 结尾（与 Cursor 只填到 /v1 不同，别抄混）。
⚠️ 后三个字段别省：maxOutputTokens 填再大也没事——余额够时网关按你填的数发给上游（最多到这个模型的窗口减去本轮输入），余额不够时最多按 16000 发、边生成边续扣；个别较老的模型上游只接受更小的输出上限（低到 4096），网关会按上游报错里宣告的上限自动钳位、重试一次（报错格式认不出时 400 会原样返回）；maxInputTokens 不写的话客户端会按 12.8 万 token 装满请求体；supportsToolCall 由配置向导按你选的模型自动填好（它按你的密钥实测得出，不是照抄示例），别一律 true —— 对不支持的模型开了它，工具调用会失败。

命令行版
⚠️ 能用哪些模型有子集限制：它每一轮都会把整套工具定义发过来，所以模型必须支持工具调用——anthropic/* 都支持工具调用；其余厂商要在我们的实测白名单内（有真实往返证据才放行）；只走 OpenAI Responses 协议的那批（o 系列、pro 系列等）目前工具调用是关着的。不在范围内的模型会在第一句话就吃 400（Tool calling is not enabled…），不是跑到第二轮才失败。配置向导会把这一条按你选的模型直接算好，不用你自己判。（CLI 是纯 agent，每轮都发工具，所以这条对它是硬限制；插件版只在你用 agent 功能时才撞到。）
⚠️ CODEBUDDY_BASE_URL 结尾必须是 /v1——CLI 只会往后拼 /chat/completions。只填到域名会打到 https://chat.facesolo.com/chat/completions，那个路径不存在，你看到的是 404。
⚠️ 必须指定模型：不设 CODEBUDDY_MODEL 也不加 --model 时，CLI 会发它自己的默认名 default-model，我们这边不认识，直接被拒。
⚠️ 它走的是 OpenAI 协议（/v1/chat/completions），不是 Anthropic 协议——别套用 Claude Code 那套 ANTHROPIC_BASE_URL 的写法。
💰 CLI 每轮会带上二十多个内置工具定义，一次简单问答的输入量在两万 token 以上，与 Cursor 同量级；按这个量级估预算。

📋 模型 id 从哪来、填在哪：在配置向导里选好模型后，下面这段会自动填成你选的那个，跟在启动命令的 --model 参数后面（~/.claude/settings.json 的 env 段里没有模型字段，那里只放地址与密钥；模型只在命令行指定）。
⚠️ 这里的地址不带 /v1——Claude Code 会自己拼 /v1/messages。它只在进程启动时读一次环境变量，改完要重开终端。
⚠️ 能用哪些模型有子集限制：它每一轮都会把整套工具定义发过来，所以模型必须支持工具调用——anthropic/* 都支持工具调用；其余厂商要在我们的实测白名单内（有真实往返证据才放行）；只走 OpenAI Responses 协议的那批（o 系列、pro 系列等）目前工具调用是关着的。不在范围内的模型会在第一句话就吃 400（Tool calling is not enabled…），不是跑到第二轮才失败。配置向导会把这一条按你选的模型直接算好，不用你自己判。
⚠️ 另外，只走 Responses 协议的那批模型（o 系列 / pro 系列等）对 Claude Code 仍然用不了——不是端点的问题（2026-08-25 起 /v1/messages 已经收它们，纯聊天正常），而是它们的工具调用还关着，而 Claude Code 每一轮都发工具定义。要用这批模型请换成不带工具的客户端（例如 VS Code 的普通对话）。

关于额度：Claude Code 是智能体，每次调用都要把整套工具定义和上下文一起发过来，实测一次约合几十次普通问答的消耗。按当前额度，连续使用大致是 Pro Lite 每 5 小时约 6 次、Pro 约 29 次、Pro Max 约 146 次（5 小时窗口按每次实扣累加，最后一次只要放得下输入就能开跑）；一个月总量分别约 125 / 625 / 3,125 次。重度使用建议 Pro 以上，或先充值——充值余额不受时段额度限制。每次的实际消耗在用量看板里按密钥看得见。

📋 模型 id 从哪来、填在哪：在配置向导里选好模型后，下面这段会自动填成你选的那个，填进 ~/.codex/config.toml 顶部那个 model 键（model_provider 那行是供应商名，不用动）。
⚠️ wire_api 必须是 responses，地址填到 /v1 为止——Codex 会自己往后拼路径。
ℹ️ 启动时那句 Model metadata … not found, defaulting to fallback metadata 是正常的：Codex 只认得它自己目录里的模型名，看到带厂商前缀的 id 就会提示。这条去不掉，也不影响使用（2026-08-26 实测照常作答）。
真正受影响的是「Codex 以为这个模型的上下文有多大」——所以上面那行 model_context_window 请填你选的那个模型的真实上限（配置向导会直接算好填给你，也可自己看 GET /v1/ide-models 的 max_input_tokens）。不填它就拿一个猜的数：要么过早压缩上下文（多花钱重写摘要），要么装太满撞上输入闸。（注意 model_max_output_tokens 不是合法字段，写了会被 --strict-config 直接拒。）
能用哪些模型：不限于 anthropic/，但不是表里任意一个都行——Codex 每轮都会带上工具定义（shell、apply_patch），所以模型必须支持工具调用：
· anthropic/*：原生透传，都支持工具调用；
· 其余厂商：走转换层，需在我们的实测白名单内（有真实往返证据才放行）；
· 只走 Responses 协议的那批（OpenAI 的 o 系列 / pro 系列等）：目前工具调用是关着的——它们第二轮的工具结果回喂形状我们还没取到证据，硬放行会让 agent 每轮重调同一个工具、每轮照常计费而永远不给答案，所以宁可当场拒绝。
挑之前用 GET /v1/models 看该模型的 supports_tools，是 true 的才填进 model 键。

关于额度：和 Claude Code 一样，Codex 每次调用都会把整套工具定义和上下文发过来，比普通问答费得多；重度使用建议 Pro 以上或先充值。

📋 模型 id 从哪来、填在哪：在配置向导里选好模型后，下面这段会自动填成你选的那个，填进 chatLanguageModels.json 里 models 数组每一项的 id（同一项的 name 只是模型下拉里显示的名字，随便起）。
上面的 models 数组给了两个位置；想用更多模型，就照这个格式继续往里加，每一项换成不同的 model id。⚠️ 上面 toolCalling / vision 写的 true 是占位值，不是通用值：这两个布尔必须按你实际填的那个模型来（向导会直接算好填给你），一律填 true 会让 agent 跑到第二轮才炸。
· 清单去哪拿：用配置向导（它按你这把密钥当场算，并直接把 toolCalling / vision 填好），或自己请求 GET https://chat.facesolo.com/v1/models。
· ⚠️ 密钥绝不能直接写进 chatLanguageModels.json（2026-08-26 真机 A/B/A 实测确认）：apiKey 必须保持 VS Code 自动写入的 ${input:chat.lm.secret.…} 形态——那是指向系统钥匙串的引用。手工换成明文密钥后，哪怕密钥完全正确（同一把在 Claude Code 里能用），VS Code 也会报 Invalid API key，而报错里看不出是这个原因。只在弹框里粘密钥；这个文件里只改 models 数组。
· toolCalling 填什么：由配置向导按你选的模型自动填好（它按你的密钥实测得出，不是照抄示例），别一律填 true。填错的后果不是列表难看，是 agent 跑到第二轮才 400（tools_unsupported_model）—— 而那时第一轮的钱已经扣了。
· 只走 OpenAI Responses 协议的那批（o 系列 / pro 系列等）现在能用了：这条端点此前对它们整面拒绝，2026-08-25 已解除，本机逐个实测过，在 VS Code 里对话正常。但它们的工具调用仍然是关着的，所以只能当纯聊天模型用——toolCalling 填 false，agent 模式请换别的模型。
· 这批模型答得慢是正常的：它们要先想再答，实测首次响应可到一分钟，冷启动更久。界面上长时间没动静不是断了——我们会持续发心跳保住连接。

⚠️ 每个值都有原因，别乱改：
· id 必须带 厂商/ 前缀（如 anthropic/…、google/…）——我们的模型目录键就是 厂商/型号，写裸 id 会 404。
· vision 怎么填：这条端点已经接内联图片（贴截图可用），但要看模型——用 GET /v1/models 看它的 supports_vision，是 false 的请填 false，否则贴图会被 400 拒。（这个字段是目录标注、不是逐个实测的，我们的图片门也照它执行：标 false 就是我们这边不收图，不代表那个模型本身看不懂图。）
· maxOutputTokens 填 16000 就好，填更大也没事：余额够时网关按你填的数发给上游（最多到这个模型的窗口减去本轮输入），余额不够时最多按 16000 发、边生成边续扣；个别较老的模型上游只接受更小的输出上限（低到 4096），网关会按上游报错里宣告的上限自动钳位、重试一次（报错格式认不出时 400 会原样返回）。
· thinking 填 false：我们发给上游的 max_tokens 可能比你填的小（余额不够时最多 16000，余额够时也不超过这个模型的窗口减去本轮输入），而扩展给的思考预算是按它自己的上限算的，两者会打架。（网关侧也会自动夹取，但客户端不发它更省事。）
· maxInputTokens 填 45000：这是我们总长闸换算过来的安全值。
另外三个扩展的实际情况（都查过官方文档与源码，如实写）：
· Cline / Roo Code：它们的 Anthropic 供应商是固定下拉框，只能选裸 Anthropic 模型名，改不了成 anthropic/…，所以对不上我们的目录。Roo Code 官方明说只支持原生工具调用、没有降级路径。
· Continue：Chat / Edit 可用，Agent 不可用——它的能力探测不能被覆盖（官方原文：只能加能力，不能关）。
🔎 报错 Invalid API key：这是我们回的 401，说明端点与协议都对，问题在密钥串本身。最常见的三种是「占位符没替换」「粘贴时带了引号或首尾空格」「这把已经吊销了」。把密钥从密钥页重新复制一遍即可，配置其余部分不用动。