Codex CLI 接入

    创建 Gate.AI API 密钥

    1. 打开 gate.ai → 控制台 → API 密钥，创建并复制 sk-v1-… 开头的 Key
    2. 确认账户有余额

    网络连通性验证

    将 GATEAI_API_KEY 替换为您的密钥：

    bash
    1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"

    OpenAI 兼容端点（Codex / 标准 API）：

    bash
    1curl -s -o /dev/null -w "%{http_code}" \2  -H "Authorization: Bearer $GATEAI_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{"model":"openai/gpt-5.2","input":"hi","max_output_tokens":16}' \5  https://api.gate.ai/openai/v1/responses
    • 返回 200：网关连通，可继续安装与配置
    • 返回 401：密钥无效或已过期，请检查控制台
    • 连接超时：检查本地网络或 DNS；确认未误用 https://api.gate.ai/v1

    安装 Codex CLI

    bash
    1npm install -g @openai/codex

    或使用

    bash
    1curl -fsSL https://chatgpt.com/codex/install.sh | sh

    若已装 Homebrew

    bash
    1brew install --cask codex

    验证：codex --version

    若 npm 安装失败

    通常是因为访问 registry.npmjs.org 超时或不稳定，与 Gate.AI 网关无关。可按需选用以下方式：

    方式 A：单次安装临时指定镜像（推荐先试）

    bash
    1npm install -g @openai/codex --registry=https://registry.npmmirror.com2npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

    方式 B：全局永久切换镜像

    bash
    1# 设为 npmmirror（原淘宝 npm 镜像，国内常用）2npm config set registry https://registry.npmmirror.com34# 验证当前镜像5npm config get registry67# 然后重新安装8npm install -g @openai/codex9npm install -g @anthropic-ai/claude-code

    方式 C：仅当前终端会话临时生效

    bash
    1export NPM_CONFIG_REGISTRY=https://registry.npmmirror.com2npm install -g @openai/codex
    现象处理
    ETIMEDOUT / ECONNRESET使用方式 A 或 B 切换镜像后重试
    EACCES 权限错误配置 npm 全局目录：mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global，并将 export PATH=~/.npm-global/bin:$PATH 写入 ~/.zshrc
    command not found: claude / codex安装成功但 PATH 未生效：重启终端，或检查 npm config get prefix 下的 bin 是否在 PATH 中

    配置模型

    将下文所有 sk-v1-你的密钥 替换为您的真实 Key。配置完成后无需重复执行，除非更换 Key 或模型。

    bash
    1mkdir -p ~/.codex23cat > ~/.codex/config.toml <<'EOF'4model_provider = "gateai"5model = "openai/gpt-5.2"67[model_providers.gateai]8name = "Gate.AI"9base_url = "https://api.gate.ai/openai/v1"10env_key = "GATEAI_API_KEY"11wire_api = "responses"12requires_openai_auth = false13EOF1415grep -q 'GATEAI_API_KEY=' ~/.zshrc 2>/dev/null || cat >> ~/.zshrc <<'EOF'1617# Gate.AI for Codex CLI18export GATEAI_API_KEY="sk-v1-你的密钥"19EOF2021source ~/.zshrc

    Codex 网关相关配置必须写在用户级 ~/.codex/config.toml；项目目录下的 .codex/config.toml 无法覆盖这些项。

    验证接入是否成功

    进入项目目录，启动 CLI，即可在终端内进行 AI 辅助编程。

    使用 codex

    bash
    1codex

    若返回正常回复且无 401 / 404，即表示已通过 Gate.AI 路由成功。

    进阶配置

    配置参考

    字段说明示例
    model_providerProvider 名称"gateai"
    modelGate.AI 模型 ID"openai/gpt-5.2"
    base_urlGate OpenAI 兼容端点https://api.gate.ai/openai/v1
    env_keyAPI Key 环境变量名"GATEAI_API_KEY"
    wire_apiCodex 协议类型"responses"
    requires_openai_authGate Key 非 OpenAI 官方格式时false
    model_reasoning_effort推理强度（可选）"low" / "medium" / "high"

    备选配置方式

    内置 OpenAI Provider（方式 A 鉴权失败时尝试）

    toml
    1model = "openai/gpt-5.2"2openai_base_url = "https://api.gate.ai/openai/v1"

    环境变量：export OPENAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"

    命令行临时覆盖

    bash
    1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"2codex --config openai_base_url='"https://api.gate.ai/openai/v1"' --config model='"openai/gpt-5.2"'

    切换模型

    修改 ~/.codex/config.toml 中的 model，或：codex --model openai/gpt-5.2

    恢复直连 OpenAI 官方（可选）

    删除 ~/.codex/config.toml 中的 Gate 相关配置，并取消 GATEAI_API_KEY 环境变量。

    故障排除

    Base URL 常见错误

    bash
    1# ❌ 错误（缺 /openai 前缀，404）2https://api.gate.ai/v13https://api.gate.ai/v1/chat/completions45# ❌ 错误（Codex 配置项不要写完整 API 路径）6https://api.gate.ai/openai/v1/messages7https://api.gate.ai/openai/messages89# ✅ 正确10https://api.gate.ai/openai/v1          # Codex CLI11https://api.gate.ai/anthropic/v1/messages  # curl 验 Key（Anthropic）12https://api.gate.ai/openai/v1/responses    # curl 验 Key（Codex）
    • /openai/v1/chat/completions 可用，但 Codex 必须走 Responses API；若报 404 on /responses，检查 wire_api = "responses"，不是改 URL。
    • /openai/v1/models 不校验 Key（无效 Key 也可能 200）；验 Key 请用上面两个 curl 地址。

    现象速查表

    现象错误类型处理建议
    401 / 鉴权失败鉴权错误检查 Key 是否正确、是否过期；Codex 确认 requires_openai_auth = false
    404 on URL路径错误Claude → https://api.gate.ai/anthropic；Codex → https://api.gate.ai/openai/v1。勿用 https://api.gate.ai/v1/...
    404 on /responses协议错误Base URL 可能对，但未走 Responses API。检查 ~/.codex/config.toml：wire_api = "responses"，base_url = "https://api.gate.ai/openai/v1"
    curl /models 返回 200 但 CLI 仍 401验 Key 方法错误/openai/v1/models 不校验 Key。改用 /openai/v1/responses 或 /anthropic/v1/messages 验 Key
    模型不存在模型 ID 错误使用 provider/model-name 格式（如 anthropic/claude-sonnet-4.6、openai/gpt-5.2），对照模型广场
    仍连官方域名配置未生效确认写在用户级配置：Claude → ~/.claude/settings.json；Codex → ~/.codex/config.toml（项目级 .codex/config.toml 无法覆盖网关配置）
    402 / 429配额 / 限流充值或检查 Key 预算与调用频率
    npm 安装失败网络 / 权限见「若 npm 安装失败」