AgentGate 实战：用统一配置骨架把 Codex、Claude Code、Gemini CLI 接入本地 AI 网关

1. 为什么需要 AgentGate 这类本地 AI 网关如果你同时开着 Codex、Claude Code、Gemini CLI 三个终端窗口写代码大概率遇到过这种局面Codex 走 OpenAI Responses APIClaude Code 走 Anthropic Messages APIGemini CLI 又是另一套请求格式三份配置文件散落在不同目录改一个 base_url 要翻半天文档。更麻烦的是你想让 Codex 用 DeepSeek、让 Claude Code 试试 Kimi就得分别去适配协议差异工具调用、流式响应、reasoning 字段这些细节一处理不好就报错。AgentGate 解决的就是这个问题。它是一个本地优先的 AI 模型请求网关把 Codex、Claude Code、Gemini CLI、OpenCode、AtomCode 这些 AI 编程客户端的请求统一收进本机入口http://127.0.0.1:9090再按你的配置路由到上游模型服务商。它做的不是简单 HTTP 转发而是协议转换、模型映射、故障转移、请求日志和成本统计这一整套事情。这篇内容聚焦一件事怎么用一套统一的配置骨架把 Codex、Claude Code、Gemini CLI 三个工具同时接到本地网关并且让它们共用同一个 API 通道。适合已经在日常使用这些 CLI 工具、想统一管理模型入口的开发者。下面给出的settings.json、config.toml骨架可以直接复制逐项验证动作也会一并说明。2. TaoToken 前置统一 Key 与 API 通道AgentGate 负责本地网关和协议转换但上游模型服务商总得有个统一的接入点。我这边用的是 TaoToken 作为统一 API 通道一个 Key 就能覆盖多个模型服务商省去在 AgentGate 里逐个填不同厂商 Key 的麻烦。TaoToken 的定位是统一模型 API 通道官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 端点是https://taotoken.net/api。你需要在控制台创建一个 API Key后面 AgentGate 的 Provider 配置里会用到。具体操作路径是这样先打开控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole在 API Keys 页面生成一个 Key复制保存好。这个 Key 就是 AgentGate 里配置 Provider 时填的凭证。如果你还没决定用哪些模型可以先去模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chat试几个模型确认哪个适合你的编码场景再回来配 AgentGate。这里有个细节要注意AgentGate 的 Provider 配置里base URL 填https://taotoken.net/api协议类型选 OpenAI 兼容或 Anthropic 兼容取决于你要接的客户端走哪套协议。TaoToken 作为统一通道上游具体路由到哪个模型由你在请求里的 model 字段决定。3. 可复制配置settings.json 与 config.toml 骨架这一节是核心给出三个工具接入本地网关的配置文件骨架。AgentGate 默认网关地址是http://127.0.0.1:9090所有客户端都指向这个入口。3.1 Codex 的 config.toml 骨架Codex 默认走 OpenAI Responses API配置文件通常在~/.codex/config.toml。接入 AgentGate 后把 base URL 指向本地网关的 responses 端点# ~/.codex/config.toml model deepseek-chat model_provider agentgate [model_providers.agentgate] name AgentGate Local base_url http://127.0.0.1:9090/v1 wire_api responses env_key AGENTGATE_API_KEY [model_providers.agentgate.headers] X-AgentGate-Client codex关键参数说明wire_api responses告诉 Codex 继续用 Responses 协议发请求AgentGate 在本地把它转成上游能理解的格式。env_key指向环境变量你需要在 shell 里 export 一个AGENTGATE_API_KEY值填 TaoToken 的 Key。model字段写你想用的模型名AgentGate 会根据这个做模型映射。3.2 Claude Code 的 settings.json 骨架Claude Code 走 Anthropic Messages API配置文件在~/.claude/settings.json。接入本地网关的骨架{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:9090, ANTHROPIC_API_KEY: your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_SMALL_FAST_MODEL: claude-haiku-3-5-20241022 }, permissions: { allow: [] } }这里ANTHROPIC_BASE_URL指向 AgentGate 根地址不带/v1因为 Claude Code 自己会拼/v1/messages。ANTHROPIC_API_KEY填 TaoToken 的 Key。如果你想让 Claude Code 用非 Anthropic 的模型在 AgentGate 里配好模型映射把ANTHROPIC_MODEL写成一个虚拟模型名由网关转发到实际 Provider。3.3 Gemini CLI 的配置骨架Gemini CLI 的配置方式略有不同它读取环境变量和~/.gemini/settings.json。骨架如下{ apiEndpoint: http://127.0.0.1:9090/v1beta, apiKey: your-taotoken-key, model: gemini-2.5-pro, generationConfig: { temperature: 0.7, maxOutputTokens: 8192 } }Gemini CLI 走的是 Gemini 风格接口AgentGate 内部会把它转成 Chat Completions 或 Anthropic Messages。apiEndpoint指向本地网关的/v1beta路径apiKey同样填 TaoToken 的 Key。三个工具的配置骨架放在一起对照工具配置文件协议本地端点Codex~/.codex/config.tomlResponses APIhttp://127.0.0.1:9090/v1Claude Code~/.claude/settings.jsonAnthropic Messageshttp://127.0.0.1:9090Gemini CLI~/.gemini/settings.jsonGemini 风格http://127.0.0.1:9090/v1beta注意三个工具的 API Key 都填同一个 TaoToken Key这样上游通道统一AgentGate 的日志里也能按客户端区分请求来源。4. 验证请求与成功结果配置写完不代表通了得逐项验证。我习惯按「网关启动 → 单客户端连通 → 多客户端并发」的顺序来。4.1 确认 AgentGate 网关已启动先确认本地网关在监听 9090 端口curl -s http://127.0.0.1:9090/health正常返回类似{status:ok,version:x.x.x}。如果连不上检查 AgentGate 桌面端或agentgate-serve是否在运行端口有没有被占用。4.2 验证 Codex 连通性在终端直接跑一条 Codex 请求观察是否走本地网关codex exec 用一句话解释什么是本地 AI 网关如果配置正确AgentGate 的日志页面会看到一条来自codex客户端的请求记录路由到你在 config.toml 里指定的模型。返回内容正常说明 Responses 协议转换链路通了。4.3 验证 Claude Code 连通性Claude Code 用非交互模式发一条测试claude -p 输出当前目录的文件列表 --output-format json返回 JSON 里如果有正常的result字段说明 Anthropic Messages 协议链路通了。去 AgentGate 日志确认请求来源标记为claude-code模型映射符合预期。4.4 验证 Gemini CLI 连通性Gemini CLI 的测试命令gemini -p 写一个 Python 快速排序函数返回代码正常说明 Gemini 风格请求被 AgentGate 正确转换。日志里应该能看到gemini-cli来源的请求。4.5 多客户端并发自检三个都单独通了之后开三个终端同时发请求观察 AgentGate 日志里是否三条请求都正确路由、没有串协议。这一步能暴露模型映射冲突或 Provider 限流问题。如果某个客户端报错日志里会显示上游返回的具体错误码和错误信息比客户端自己的报错清楚得多。5. 本篇常见错排查配置过程中踩过的坑集中在几个地方逐个说。报错一Connection refused或ECONNREFUSED 127.0.0.1:9090网关没启动或者端口不对。AgentGate 默认 9090但如果你改过端口三个客户端的配置都要同步改。另外注意localhost:1420是开发 UI 端口不是网关端点别填错。报错二401 Unauthorized或invalid api keyTaoToken 的 Key 没填对或者环境变量没生效。Codex 用的是env_key指向的环境变量检查echo $AGENTGATE_API_KEY有没有值。Claude Code 和 Gemini CLI 是直接写在配置文件里的注意别有多余空格或换行。报错三model not found或unsupported modelAgentGate 里的模型映射没配好。客户端请求的模型名和上游 Provider 实际支持的模型名不一致。去 AgentGate 的 Provider 配置里检查模型映射表确认虚拟模型名指向了正确的上游模型。报错四协议转换后工具调用失败Codex 的 function calling 或 Claude Code 的 tool use 在转换后格式不对。这类问题通常出在 AgentGate 的协议转换层检查是不是把 Responses 的 tool 格式转成了 Chat Completions 不兼容的结构。可以看 AgentGate 日志里请求经过转换后的实际 payload。报错五流式响应中断或 SSE 首帧报错上游 Provider 限流或超时。AgentGate 支持故障转移在 Provider 配置里开启 fallback配一个备用 Provider。日志里会记录是否触发了故障转移以及切换到了哪个 Provider。报错六Gemini CLI 返回 404apiEndpoint路径拼错了。Gemini CLI 会在你填的 endpoint 后面拼具体路径所以填http://127.0.0.1:9090/v1beta而不是http://127.0.0.1:9090。多一个或少一个/v1beta都会 404。排查的通用思路先看 AgentGate 日志里请求有没有进来再看路由到了哪个 Provider最后看上游返回什么。这三步能定位绝大多数问题。6. 长期使用与接入文档三个工具都跑通之后日常使用基本不用再动配置。AgentGate 的客户端配置应用和历史回滚功能让你在换模型或换 Provider 时不用手动改三份文件。如果你后面要加 OpenCode 或 AtomCode也是同样的套路指向本地网关配好协议类型验证连通。需要长期编码或跑 Agent 任务的话可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_plan配合 AgentGate 的故障转移长任务跑到一半遇到 Provider 抖动也能自动切换。接入过程中如果遇到协议转换或 Key 配置的问题接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc里有各协议的端点说明和参数对照。API Keys 管理在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keys需要轮换 Key 或查看用量时去那里操作。实测下来这套配置骨架最省事的地方在于三个工具的配置文件各写一次之后换模型只改 AgentGate 里的映射客户端完全不用动。踩过的坑基本都在协议路径和 Key 环境变量上对照第 5 节的排查清单能快速定位。