一个网关搞定 3 大编程 CLI（2026）：配置与故障排查 — Gemini CLI、Codex CLI、Claude Code

如果你每天都在使用编程 CLI，配置的繁琐就是实实在在的成本：多个 API 密钥、不同的配置格式、认证冲突，还有经典的 401/429/流式传输卡住循环。

想要最快的路径？使用专门的集成指南（推荐）：

• Claude CLI / Claude Code
• Codex CLI
• Gemini CLI

从这里开始（最快配置）

选择你的工具，按照文章开头的专门指南操作。

速查：5 分钟清单（选择你的工具）

注意： 不同 CLI 可能需要略微不同的端点格式（如 /v1 或末尾斜杠）。请按照各工具的指南使用正确格式。

为什么要通过网关接入编程 CLI？

当你需要以下一项或多项功能时，使用网关/路由器：

1. 不再管理多个密钥 —— 多个工具共用一个密钥
2. 切换模型/服务商 —— 无需重写工具配置
3. 统一流量路由 —— 便于操作控制（重试/超时/审计）
4. 保持工作流稳定 —— 工具和服务商变化时不受影响

本指南专注于配置 + 实际运维：什么会出问题，如何修复。

决策表：直连服务商 vs 统一网关

在做决定之前，这是生产环境中的真实权衡。

路径 A — Codex CLI（通过 config.toml 自定义 provider）

最简步骤

1. 安装：

   npm install -g @openai/codex

2. 设置 API 密钥：

   export OPENAI_API_KEY="YOUR_EVOLINK_KEY"

3. 创建/编辑配置 ~/.codex/config.toml

4. 验证：

   codex "Who are you"

最简 config.toml 示例

model = "gpt-5.2"
model_provider = "evolink"

[model_providers.evolink]
name = "EvoLink API"
base_url = "https://api.evolink.ai/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

路径 B — Claude Code / Claude CLI（settings.json + Anthropic base URL）

最简步骤

1. 安装：

   npm install -g @anthropic-ai/claude-code

2. 编辑 ~/.claude/settings.json

3. 验证：

   claude "Who are you"

最简 settings.json 示例

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_EVOLINK_KEY",
    "ANTHROPIC_BASE_URL": "https://api.evolink.ai",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "permissions": { "allow": [], "deny": [] }
}

认证冲突说明（常见坑）

如果你之前使用订阅流程登录过，同时又设置了 API 密钥/令牌，行为可能不一致。如果你看到警告或意外的认证行为：

• 运行 claude /logout 并重新干净地认证，和/或
• 取消设置冲突的 Anthropic 环境变量，然后重启终端

路径 C — Gemini CLI（.env + 自定义 base URL）

前提条件

检查：

node -v

最简步骤

1. 安装：

   npm install -g @google/gemini-cli

2. 创建/编辑 ~/.gemini/.env

3. 验证：

   gemini "Who are you"

最简 .env 示例

GOOGLE_GEMINI_BASE_URL="https://api.evolink.ai/"
GEMINI_API_KEY="YOUR_EVOLINK_KEY"
GEMINI_MODEL="gemini-2.5-pro"

已知问题：base URL 不生效

• 重启终端会话
• 确认 .env 文件路径正确
• 检查 CLI 认证模式和缓存的会话
• 用最简提示词重新运行，隔离配置问题和提示词/运行时问题

为什么配置更改不生效（优先级检查清单）

大多数"没有生效"的问题来自以下原因之一：

1. 文件位置错误
   • Codex：~/.codex/config.toml
   • Claude：~/.claude/settings.json
   • Gemini：~/.gemini/.env
2. 编辑了文件但没有重启
   • 重启终端或 CLI 进程。
3. 环境变量覆盖了配置
   • 对于 Claude 认证冲突尤其相关（token vs login）。

快速检查：

env | grep -E "OPENAI_API_KEY|ANTHROPIC_|GEMINI_|GOOGLE_GEMINI_BASE_URL"

故障排查速查表（401/403/429/流式传输/工具调用/超时）

401 / 403（认证错误）

• 你的密钥是否设置在工具读取的变量中？
  • Codex：OPENAI_API_KEY
  • Claude：ANTHROPIC_AUTH_TOKEN
  • Gemini：GEMINI_API_KEY
• 你的 base URL 是否与集成指南中的端点格式匹配？

• 重新导出环境变量并重启 shell
• 重新检查配置文件位置和拼写
• 对于 Claude：/logout，然后重新干净地认证

需要新密钥来解决 401/403？创建/管理 API 密钥 →

429（速率限制/配额/节流）

• 减少并发（避免多个并行运行）
• 在大型任务之间添加小延迟
• 使用指数退避重试（最好由网关/路由器处理）

如果 429 持续出现，将其视为运维问题：突发模式、长时间流式会话或频繁的工具调用都可能加剧问题。

流式传输卡住/长输出挂起

• 尝试简短提示词验证连接性
• 临时禁用 VPN/代理以隔离网络问题
• 在干净目录中重新运行（避免大型仓库上下文）

工具调用失败（agent 尝试运行命令/文件）

• 权限策略阻止执行
• 工具环境缺少依赖（git、ripgrep、构建工具）
• 路径/沙箱限制

• 确认工具权限策略和工作目录
• 用最简工具操作复现问题

超时

• 将任务拆分为更小的提示词
• 减少仓库上下文大小
• 首次测试避免非常长的流式会话

模型切换（快速）

• Codex CLI：更新 ~/.codex/config.toml 中的 model = "..."
• Claude Code：使用 /model（如果你的版本支持）
• Gemini CLI：使用 /model 或更新 .env 中的 GEMINI_MODEL

下一步

如果你使用多个编程 CLI，减少摩擦的最快方式是标准化：

• 单一网关主机
• 每个工具可预测的配置模板
• 可重复的故障排查手册

从专门的集成指南开始（见文章开头）。

常见问题

什么是编程 CLI 的"自定义 LLM 端点"？

自定义端点是你的 CLI 发送请求的 base URL，而不是默认的服务商端点。实际上，它可以是一个网关/路由器，在单一主机后面暴露一个或多个模型 API。

为什么这个指南为不同工具显示不同的端点格式（/v1、末尾斜杠）？

Codex CLI 配置文件在哪里？

如何在 Codex CLI 中设置自定义 base_url？

Codex 配置中的 wire_api = "responses" 是什么意思？

它指示 CLI 与端点通信时使用的 API 格式。保持与集成指南一致。

Claude Code 的 settings.json 在哪里？

ANTHROPIC_BASE_URL 用来做什么？

它设置 Claude Code 发送请求的 base URL，使其能够通过自定义端点路由，而不是默认的服务商端点。

为什么 Claude Code 会警告认证冲突？

Gemini CLI 从哪里读取 .env？

为什么 GOOGLE_GEMINI_BASE_URL 不生效？

Gemini CLI 应该使用什么 Node.js 版本？

使用 Node.js 20+。

使用自定义端点时如何快速修复 401/403？

验证正确的密钥变量已设置，确认端点格式，并重启终端。对于 Claude，还需要通过登出或取消设置变量来移除认证冲突。

429 在编程 CLI 中是什么意思？

通常表示速率限制或配额节流。减少并发，添加延迟，并使用指数退避重试。

我的 CLI 流式输出然后挂起——应该先尝试什么？

用简短提示词测试，临时禁用 VPN/代理，减少仓库上下文大小。将大型任务拆分为更小的提示词。