让 ZCode 无痛使用 Gemini API —— 附带一个修复 thought_signature 400 的本地签名代理。
ZCode 通过 OpenAI 兼容格式接入 Gemini API 时,agent 一调用工具就会在第二轮请求收到 400:
Function call is missing a thought_signature in functionCall parts.
原因:Gemini 3.x 是思考模型,它每次工具调用都会附带一个 thought_signature 签名,Google 要求下次回传对话历史时把这个签名原样带回。但 ZCode 把它当成不认识的字段丢掉了——于是第一轮好好的,模型一调工具,立刻 400。
修复思路:在本地跑一个透明代理,夹在 ZCode 和 Google 之间。它把 Google 每次发来的签名缓存下来,在 ZCode 发请求时自动补回去。ZCode 一行不用改。
ZCode → http://127.0.0.1:8899/v1beta/openai (签名修复代理) → https://generativelanguage.googleapis.com
把本仓库的 skill 文件夹复制到 ZCode 的 skill 目录:
copy 本仓库\skill\* %USERPROFILE%\.agents\skills\gemini-bridge\
之后在任何对话里提到 Gemini API 报错,agent 会自动按这套方案排障。
不用 skill 也行,直接照下面的步骤手动配置。
双击 scripts/start-proxy.bat,或:
powershell -ExecutionPolicy Bypass -File scripts\gemini-proxy.ps1代理日志在 %USERPROFILE%\.zcode\gemini-proxy.log(里面能看到 Google 报错原文,排障第一现场)。想开机自启,把 start-proxy.bat 的快捷方式丢进 shell:startup。
设置 → 模型 Provider → 添加自定义:
| 配置项 | 值 | 说明 |
|---|---|---|
| 格式 | OpenAI Chat Completions | 千万别选 Responses,Google 没有那个端点,必 404 |
| 地址 | http://127.0.0.1:8899/v1beta/openai |
指向本地代理 |
| API Key | 你的 AI Studio key(AQ. 或 AIzaSy 开头) |
aistudio.google.com/apikey 获取 |
| 模型名 | gemini-3.7-flash / gemini-3.6-flash |
手动输入,别信下拉列表 |
注意:必须新对话。旧对话缓存了旧配置,改了也不生效。
| 报错 | 病因 | 药方 |
|---|---|---|
400 missing a thought_signature |
ZCode 丢了签名 | 跑本代理 |
400 Invalid reasoning_effort: max |
思考档位选了 max | 改 high(Google 只认 high/low/medium/minimal/none) |
| 404 Not Found | 选了 Responses 格式 / 模型名不对 / 地址拼错 | 用 Chat Completions + 核对模型名 |
403 project has been denied access |
项目没绑结算 | AI Studio 里给项目设置结算信息 |
| 403 auth_failed | key 错/复制不全 | curl 验证 key(见 skill 文档) |
| 503 high demand | Gemini 3.7 高峰期 | 等几分钟重试 |
完整版对照表和诊断脚本见 skill/references/error-table.md。
- 退出时会用内存配置覆盖 config.json —— provider 要在界面里建,别手改文件
- 点 X 只是缩小到托盘 —— 真重启要托盘右键退出
- 报错的 TraceID 不变说明在旧会话里打转 —— 改完配置必开新对话
- 网络能访问
generativelanguage.googleapis.com - 一个开通了 Gemini API 的 Google 账号和有效的 API key
- (Agent 工具调用场景需要思考模型时)项目已绑定结算
MIT