ZCode AI 自定义 API 设置

ZCode 可以把兼容 Anthropic 或 OpenAI 协议的服务添加为 Custom Provider。本页按照 ZCode 官方 Connect Models → Custom Providers (Anthropic / OpenAI Compatible) 的实际操作顺序，将 TokenHub 配置为 OpenAI-compatible Provider，Base URL 填 https://us-api.tokenhub.com/v1。

打开模型设置

首次启动且没有可用模型时，选择 Use API Key。已进入 ZCode 时，点击输入框中的模型名称，选择 Manage Models，进入 Settings → Model Settings。

添加 TokenHub Custom Provider

按照官方 Custom Provider 的 7 步流程操作：

1. 打开 Settings → Model Settings。
2. 在左侧 Provider 列表底部点击 Add Provider。
3. Provider 名称填写 TokenHub。
4. 选择 OpenAI-compatible，并在 Base URL 下拉框中选择自定义地址或手动输入 https://us-api.tokenhub.com/v1。
5. 在 API Key 字段填入 TokenHub API Key。
6. 点击 Add Model，输入 TokenHub 模型广场中真实存在的 Model ID；需要多个模型时逐个添加。
7. 保存设置并打开 Provider 的 Enable 开关，随后确认需要使用的模型也处于启用状态。

官方流程不会自动替你判断第三方模型 ID。若列表没有自动返回模型，仍应使用 Add Model 手动添加准确 ID。

不要把 Anthropic 与 OpenAI 协议配置混在同一个 Provider 中。使用 Anthropic Messages 时应新建独立 Provider，并填写该协议对应的根地址。

配置单个模型的 Advanced 设置

在 Settings → Model Providers 中打开刚添加的模型并展开 Advanced：

• Max output tokens：通常留空，让模型服务返回其支持值；只有确认目标模型的限制时才手动填写。
• Context window：Custom Provider 模型可以编辑，保存后的值只对新会话生效。填写值必须来自 TokenHub 模型规格，不能照抄其他模型。
• Thinking effort：可见档位由模型和协议决定。OpenAI-compatible 请求会使用 reasoning_effort；第三方部署不一定接受 ZCode 显示的所有档位，遇到 400 参数错误时应降低档位或关闭该选项。
• 自定义请求参数：ZCode 当前不会把手写进本地 Provider options 的任意参数自动加入请求体，不要依赖修改 ~/.zcode/v2/config.json 注入额外推理或图片参数。

图片输入如何判断

ZCode 会结合 Provider、Model ID、模型目录能力和当前协议判断图片是否发送：

• 显示支持时，图片会保留并传给模型服务。
• 显示不支持时，ZCode 会移除图片并改为文本提示。
• 能力未知时，ZCode 不会提前拦截，最终由 TokenHub 模型端决定是否接受，请求仍可能失败。

同一个模型通过不同 Provider 或协议接入时，图片判定可能不同。首次验证请先使用纯文本；只有 TokenHub 模型页明确支持图片输入时再测试图片。

选择模型并验证

1. 回到聊天输入框中的模型选择器。
2. 选择刚添加的 TokenHub Provider 和模型。
3. 发送一条短指令，例如“解释当前文件，不要修改”。
4. 在 TokenHub 请求日志中确认请求走向 /v1/chat/completions，并核对 Model ID、状态码和用量。
5. 普通文本响应稳定后，再分别测试编辑、工具调用、长上下文和图片输入。

这与官方 Verify The Setup 的建议一致：先选中新渠道并发送短测试指令，确认模型稳定返回后再开始实际任务。

ZCode 内置 HTTP Proxy 的范围

如果在 ZCode Settings 中配置 HTTP Proxy，它会覆盖模型 API、MCP、WebFetch、终端子进程、插件市场和应用内页面加载，但不会覆盖桌面账号登录、Wiki 生成、Web Remote Control WebSocket 或 SSH 远程连接。ZCode 默认也不会让所有流量都读取系统 HTTP_PROXY / HTTPS_PROXY；修改应用内 Proxy 后需要重启 ZCode。

排错

• 模型不显示：检查 Provider 和模型是否都已启用。
• 404：确认 Endpoint 没有重复附加 /chat/completions。
• 请求格式不匹配：核对 Provider 选择的是 OpenAI-compatible 还是 Anthropic。
• 能回答但不能改代码：所选模型可能没有可靠的原生工具调用。
• Thinking effort 返回 400：第三方部署可能不接受当前档位，降低档位或关闭后重试。
• 图片请求失败：使用规范 Model ID，并确认当前 Provider、协议和 TokenHub 模型都支持图片输入。
• 修改 Proxy 后仍未生效：重启 ZCode，并确认该流量属于 ZCode 内置 Proxy 的覆盖范围。

官方资料

• ZCode：Connect Models