【功能建议】自定义供应商的「自定义请求头(headers)」无界面配置入口——文档承认的连接参数,却只能手改配置文件
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 22
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
使用场景
我用 ZCode 接入一个本地网关,需要在同一网关下建两个「自定义供应商」(相同 baseURL、相同 API Key、相同模型 ID),仅靠不同的自定义请求头区分流量去向(如 X-Site: global / X-Site: domestic,网关侧按该头路由区域)。这是网关侧支持的常见做法。
但 headers 在任何界面位置都没有入口:
- 设置 → 模型配置 → 编辑自定义供应商,只有:供应商名称、Base URL、API Key、API 格式,以及模型级的上下文窗口 / 模型能力 / MFJS / 推理档位 / 最大输出 Token——没有「请求头」。
- 我最终只能手动编辑
~/.zcode/v2/provider_config.json,在config.api下写入headers才配好。
补充一个正面事实:实测在界面里编辑同一供应商并保存后,手写的 headers 不会丢失(ZCode 会完整序列化回写)。所以补这个入口应无数据迁移成本。
建议方案
在自定义供应商的「高级设置 / 高级配置」里增加「自定义请求头」键值对编辑器;或提供与 MCP 类似的「表单 / 完整配置(JSON)」切换(MCP 已有 settings.mcp.form.fullConfig),让用户能看到并编辑 api.headers 这类未暴露字段。
预期价值
headers是官方文档明确承认的连接参数(原文:~/.zcode/v2/config.json中供应商的 options 只识别apiKey、baseURL、apiKeyRequired、headers等连接参数)。同为连接参数,baseURL/apiKey有输入框,headers却只能手改文件。- 真实场景已被卡住:
- #492:OpenCode Go 要求每个请求带
x-opencode-session,厂商自己来提,约 33k 组织受影响; - #599:即便手改配置,「测试连接」按钮仍不发送该头 → 必然误报失败。
- #492:OpenCode Go 要求每个请求带
- 手改文件的用户,一旦遗漏或误删,现象是「两个供应商行为突然一致」,排查成本高。
补充材料
- 我抓包实测确认:
headers在 Anthropic(/v1/messages) 与 OpenAI 兼容(/v1/chat/completions) 两条路径上都会正常随请求发出——运行时管线完全支持,缺的只是配置入口。 - 版本:ZCode 3.12.2(Windows 11)。
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No source files or tests are named. Start by locating the custom-provider editor and compare it with the MCP settings.mcp.form.fullConfig form; then trace how api.headers is preserved in ~/.zcode/v2/provider_config.json. Done means users can view and edit custom request headers in the supplier settings without losing them when saving.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, frontend
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100