一个网关用于 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 期望的确切格式。

为什么要通过网关主机路由编码 CLI？

当您想要以下一项或多项时，请使用网关/路由器：

1. 停止在多个工具之间杂耍密钥
2. 切换模型/提供商而无需重写工具配置
3. 通过一个地方路由流量以进行操作控制（重试/超时/审计）
4. 随着工具和提供商的发展保持工作流稳定

本指南侧重于设置 + 运营现实：什么会坏掉以及如何修复它。

决策表：直接到提供商 vs 一个网关主机

在您承诺之前，这是生产中的真正权衡。

路径 A — Codex CLI (通过 config.toml 自定义提供商)

最小步骤

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 基础 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 + 自定义基础 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"

已知陷阱：基础 URL 未生效

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

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

大多数“它没有改变”的问题来自以下之一：

1. 错误的文件位置 — Codex: ~/.codex/config.toml / Claude: ~/.claude/settings.json / Gemini: ~/.gemini/.env
2. 您编辑了文件但没有重启 — 重启终端或 CLI 进程。
3. 环境变量覆盖配置 — 特别与 Claude 认证冲突（令牌 vs 登录）相关。

快速检查：

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
• 您的基础 URL 是否与您的集成指南使用的端点格式匹配？

• 重新导出环境变量并重启您的 shell
• 重新检查配置文件位置和拼写
• 对于 Claude: /logout，然后彻底重新认证

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

429 (速率限制 / 配额 / 节流)

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

如果 429 持续存在，将其视为运营问题：突发模式、长时间流式会话或大量工具调用可能会放大该问题。

流卡住 / 长时间输出挂起

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

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

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

• 确认工具权限策略和工作目录
• 使用最小工具操作重现

超时

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

模型切换（快速）

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

下一步

如果您正在使用多个编码 CLI，减少摩擦的最快方法是标准化：

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

从专用集成指南开始（见上文简介）。

常见问题解答 (FAQ)

什么是编码 CLI 的“自定义 LLM 端点”？

自定义端点是您的 CLI 发送请求的基础 URL，而不是默认的提供商端点。在实践中，它可以是一个网关/路由器，在单个主机后面公开一个或多个模型 API。

为什么本指南针对不同工具显示不同的端点格式（/v1，尾随斜杠）？

Codex CLI 配置文件位于哪里？

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

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

它指示 CLI 在与端点对话时使用哪种 API 形状。保持其与您的集成指南一致。

Claude Code settings.json 位于哪里？

ANTHROPIC_BASE_URL 用于什么？

它设置 Claude Code 发送请求的基础 URL，允许通过自定义端点而不是默认提供商端点进行路由。

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

Gemini CLI 从哪里读取 .env？

为什么 GOOGLE_GEMINI_BASE_URL 不生效？

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

使用 Node.js 20+。

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

验证是否设置了正确的密钥变量，确认端点格式，并重启终端。对于 Claude，还要通过注销或取消设置变量来消除认证冲突。

编码 CLI 中的 429 是什么意思？

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

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

使用短提示进行测试，暂时禁用 VPN/代理，并减小仓库上下文大小。将大任务拆分为更小的提示。