Codex CLI 安装与国内模型配置指南

1. 概述

1.1 什么是 Codex CLI

Codex CLI 是 OpenAI 于 2025 年开源的终端 AI 编程代理（Rust 编写，83,000+ Stars，Apache-2.0），支持在终端中读取文件、执行命令、自主修改代码库。

1.2 架构原理

Codex 核心是一个 Agent Loop（代理循环）：

复制代码

1. 组装 Prompt（系统指令 + 工具列表 + 用户输入 + AGENTS.md + 环境信息）
       │
2. POST JSON → OpenAI Responses API
       │
3. 流式接收事件（推理输出 / 工具调用请求）
       │
4. 执行工具（Bash / 文件操作 / MCP 工具），结果追加回上下文
       │
5. 循环，直到 LLM 发出 done 事件

1.3 与 Claude Code 对比

维度	Codex CLI	Claude Code
开源性	开源（Apache-2.0）	未开源
实现语言	Rust（96.1%）	TypeScript
API 协议	OpenAI Responses API	Anthropic Messages API
沙箱机制	Seatbelt/Landlock/restricted-token	无内置沙箱
子 Agent	`.toml` 文件定义，`max_threads` 并行	`/agent` 命令基于 worktree
生态规模	280+ 资源	丰富的 MCP + Skill
Windows 支持	需 WSL 2	原生支持

2. 安装

2.1 前置条件

依赖	说明
Node.js ≥ 18	推荐 22 LTS
Git	项目必须在 Git 仓库中才能运行
操作系统	macOS / Linux 原生；Windows 需 WSL 2

2.2 方式一：npm 全局安装

bash 复制代码

# 配置国内镜像
npm config set registry https://registry.npmmirror.com

# 安装
npm install -g @openai/codex

# 验证
codex --version

2.3 方式二：Homebrew（macOS）

bash 复制代码

brew install --cask codex

2.4 方式三：桌面版

从 codex.chat 下载桌面安装包（Windows/macOS）。

3. 配置体系

3.1 文件层级与优先级

层级	路径	说明
系统级	`/etc/codex/config.toml`	管理员推送（可选）
用户全局	`~/.codex/config.toml`	个人默认，对所有项目生效
Profile 文件	`~/.codex/<name>.config.toml`	通过 `--profile <name>` 激活
项目级	`.codex/config.toml`	仅对受信项目加载

优先级（从高到低）： CLI 参数 → 项目配置 → Profile → 用户配置 → 系统配置 → 内置默认值。

⚠️ 安全限制： 以下键在项目级 .codex/config.toml 中会被忽略 ------openai_base_url、model_provider、model_providers、chatgpt_base_url 等。这些必须设置在 ~/.codex/config.toml 中。

3.2 config.toml 核心配置

toml 复制代码

# ~/.codex/config.toml ------ 个人全局配置

# ── 模型 ──────────────────────────────
model                         = "gpt-5.5"
model_provider                = "openai"
model_reasoning_effort        = "medium"      # minimal | low | medium | high | xhigh
model_verbosity               = "medium"

# ── 安全边界 ──────────────────────────
sandbox_mode                  = "workspace-write"  # read-only | workspace-write | danger-full-access
approval_policy               = "on-request"       # untrusted | on-request | never

# ── 沙箱微调 ──────────────────────────
[sandbox_workspace_write]
network_access                = false         # pip/npm 需要时设为 true
writable_roots                = ["~/extra"]

# ── Shell 环境 ────────────────────────
[shell_environment_policy]
inherit                       = "all"         # all | core | none
exclude                       = ["AWS_*", "AZURE_*"]

# ── 特性开关 ──────────────────────────
[features]
hooks                         = true
multi_agent                   = true
undo                          = false
memories                      = false

# ── 项目上下文 ────────────────────────
web_search                    = "cached"      # cached | live | disabled
project_doc_max_bytes         = 32768         # AGENTS.md 最大字节数

3.3 常用 CLI 参数

bash 复制代码

codex --model gpt-5.5                          # 指定模型
codex --full-auto                              # workspace-write + on-request 快捷方式
codex --profile deep-review                    # 使用 profile
codex --config 'sandbox_workspace_write.network_access=true'   # 覆盖单项
codex --yolo                                   # 跳过所有审批和沙箱（极度危险）

4. 协议不兼容------核心问题

4.1 问题根源

	OpenAI Responses API	Chat Completions API
端点	`/v1/responses`	`/v1/chat/completions`
请求体	`instructions` + `input` 扁平结构	`messages` 数组结构
流式事件	`response.created` → `output_item.added` → ... → `response.completed`	`delta.content` + `delta.tool_calls`
工具调用	扁平 function 列表	嵌套 `type: "function"` + `function: {name, arguments}`
Reasoning	`reasoning.effort` / `reasoning.summary`	`reasoning_content` 字段
国内模型支持	❌ 几乎不支持	✅ 全部支持

4.2 解决路线总览

方案	机制	复杂度	适用场景
兼容网关直连	第三方网关已内置协议转换	★☆☆	快速上手，不想本地跑代理
本地代理工具	本地启动协议转换代理	★★☆	长期主力，多模型灵活切换
降级到旧版	安装仍使用 Chat API 的旧版 Codex	★★☆	临时方案，功能受限

5. 方案一：兼容网关直连（最简单）

无需本地代理，只需修改 config.toml 指向已处理协议转换的第三方端点。

5.1 七牛云 AI

toml 复制代码

# ~/.codex/config.toml
openai_base_url = "https://api.qnaigc.com/v1"
model = "deepseek-v4-pro"
sandbox_mode = "workspace-write"

bash 复制代码

export OPENAI_API_KEY="你的七牛云Key"

API Key 获取： portal.qiniu.com/ai-inference/api-key
特点： 一个 Key 统一调用 DeepSeek / Claude / Kimi 等多模型，内部已处理协议转换

5.2 OpenRouter

toml 复制代码

# ~/.codex/config.toml
openai_base_url = "https://openrouter.ai/api/v1"
model = "deepseek/deepseek-chat"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
requires_openai_auth = false

bash 复制代码

export OPENROUTER_API_KEY="你的Key"

API Key 获取： openrouter.ai/keys
特点： 200+ 模型聚合，但国内访问可能不稳定

5.3 Token173 中转

toml 复制代码

openai_base_url = "https://token173.com/v1"
model = "deepseek-v4-pro"

6. 方案二：本地代理工具（推荐）

在本地启动协议转换代理，Codex 请求指向 127.0.0.1，代理负责 Responses ↔ Chat Completions 双向转换。

6.1 CC-Switch（最流行，推荐首选）

仓库： github.com/farion1231/cc-switch
原理： 在 127.0.0.1:15721/v1 启动本地路由，完成协议识别 → 请求改写 → 转发 → 响应回译
预置： 50+ 供应商模板，同时支持 Claude Code / Codex / Gemini CLI
安装： brew install --cask cc-switch（macOS）或下载桌面安装包

配置步骤：

复制代码

1. 安装 CC-Switch → 启动
2. 切换到 Codex 标签页 → 点击 + 添加供应商
3. 选择预设（DeepSeek / 通义千问 / SiliconFlow / Kimi / GLM）
4. 填入 API Key → 勾选「需要本地路由映射」→ 保存
5. 设置 → 路由 → 打开本地路由开关 → 打开 Codex 开关
6. Codex 自动连接 http://127.0.0.1:15721/v1

原理：CC-Switch 修改 ~/.codex/config.toml，将 Codex 请求透明指向本地路由。

6.2 mimo2codex

仓库： github.com/7as0nch/mimo2codex
特点： 内置 MiMo V2.5 + DeepSeek V4 Pro，通用 provider 支持 Qwen/GLM/Kimi/Ollama
管理面板： http://127.0.0.1:8788/admin/

bash 复制代码

npm install -g mimo2codex
mimo2codex
# 启动后在面板配置上游 API 和 provider

toml 复制代码

# ~/.codex/config.toml
model_provider = "my-proxy"
model = "deepseek-chat"

[model_providers.my-proxy]
name = "本地代理"
base_url = "http://127.0.0.1:8788"
wire_api = "responses"
requires_openai_auth = true
preferred_auth_method = "apikey"

6.3 codex-proxy（npm 轻量方案）

npm 包： @roson_liu/codex-proxy
特点： 渠道管理、模型路由、DeepSeek 思考模式多轮透传、Qwen XML tool_call 适配

bash 复制代码

npm install -g @roson_liu/codex-proxy
codex-proxy
# 管理面板：http://localhost:10204

bash 复制代码

export OPENAI_BASE_URL=http://localhost:10204/v1
export OPENAI_API_KEY="你的DeepSeek/通义千问 API Key"

6.4 本地代理方案对比

方案	图形界面	多工具管理	部署方式	适用场景
CC-Switch	✅	✅（Claude Code + Codex + Gemini）	桌面应用	长期主力
mimo2codex	✅ Web 面板	❌（仅 Codex）	npm / Docker / 桌面包	多 provider 并存
codex-proxy	✅ Web 面板	❌（仅 Codex）	npm 全局	快速轻量

7. 方案三：降级到旧版 Codex

如果不需要新版特性，可安装仍使用 Chat Completions 的旧版（≤ 0.80.0）：

bash 复制代码

npm install -g @openai/codex@0.80.0

旧版直接兼容国内模型：

toml 复制代码

# ~/.codex/config.toml（仅 ≤ 0.80.0 有效）
openai_base_url = "https://api.deepseek.com/v1"
model = "deepseek-chat"
sandbox_mode = "workspace-write"

⚠️ 代价： 失去新版 Responses API 特性（推理摘要、并行工具调用优化、流式改进）、Bug 修复和安全更新。

8. 国内厂商配置速查

8.1 各厂商端点

平台	Base URL	获取 API Key
DeepSeek	`https://api.deepseek.com/v1`	platform.deepseek.com
SiliconFlow	`https://api.siliconflow.cn/v1`	siliconflow.cn
阿里百炼	`https://dashscope.aliyuncs.com/compatible-mode/v1`	百炼控制台 → API-KEY 管理
智谱 GLM	`https://open.bigmodel.cn/api/paas/v4`	open.bigmodel.cn
Kimi	`https://api.moonshot.cn/v1`	platform.moonshot.cn
MiniMax	`https://api.minimax.io/v1`	platform.minimax.io
七牛云	`https://api.qnaigc.com/v1`	portal.qiniu.com
腾讯云	`https://tokenhub.tencentmaas.com/plan/v3`	腾讯云 AI 控制台
魔搭免费	`https://api-inference.modelscope.cn/v1`	每日 2000 次免费调用

8.2 推荐模型

场景	推荐模型
日常编码	DeepSeek V4 Pro / DeepSeek V3.2
复杂推理	DeepSeek R2 / Qwen3.6-Max
中文优化	Qwen 系列 / GLM 系列
长上下文	Kimi K2.6（百万 Token）
省钱首选	DeepSeek Chat + 魔搭免费额度
离线/隐私	Ollama 本地部署

8.3 各方案配置速查

CC-Switch + DeepSeek： 在 CC-Switch 中添加 DeepSeek 预设 → 填入 Key → 勾选本地路由 → 启动

七牛云直连（最简）：

toml 复制代码

openai_base_url = "https://api.qnaigc.com/v1"
model = "deepseek-v4-pro"

mimo2codex + DeepSeek：

toml 复制代码

model_provider = "local"
model = "deepseek-chat"
[model_providers.local]
base_url = "http://127.0.0.1:8788"
wire_api = "responses"

9. 协议转换原理

复制代码

Codex (Responses API)              国产 LLM (Chat Completions)
       │                                   │
       │  POST /v1/responses               │
       │  { instructions, input,           │
       │    reasoning, tools, ... }         │
       └──────►  Proxy 转换引擎 ──────────►│
                · instructions → system 消息
                · input → user/assistant 消息
                · reasoning.effort → reasoning_effort
                · tools（扁平）→ tools（嵌套）
                · SSE 事件映射                              │
                ◄──────────────────────────┘
                · Chat 响应 → Responses SSE
                · tool_call → function_call
                · reasoning_content 回传

关键转换点：

转换	Responses API	Chat Completions API
系统提示	`instructions: "..."`	`messages[0] = {role: "system", content: "..."}`
用户消息	`input[{type: "input_text", text: "..."}]`	`messages.push({role: "user", content: "..."})`
工具定义	`tools[{type: "function", name, parameters}]`	`tools[{type: "function", function: {name, parameters}}]`
推理力度	`reasoning: {effort: "medium"}`	`reasoning_effort: "medium"`
SSE 完成	`event: response.completed`	`data: [DONE]`

10. 进阶配置

10.1 自定义 Provider

toml 复制代码

# ~/.codex/config.toml
model_provider = "my-deepseek"
model = "deepseek-chat"

[model_providers.my-deepseek]
name = "DeepSeek 本地代理"
base_url = "http://127.0.0.1:15721/v1"
wire_api = "responses"
env_key = "DEEPSEEK_API_KEY"
requires_openai_auth = false
request_max_retries = 4
stream_idle_timeout_ms = 300000

10.2 Ollama 本地模型

toml 复制代码

[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

bash 复制代码

export OPENAI_API_KEY="ollama"   # 占位符，Ollama 不需要真实 Key

10.3 Profile 多配置切换

bash 复制代码

# ~/.codex/quick.config.toml（轻量任务）
model = "deepseek-chat"
model_reasoning_effort = "minimal"

# ~/.codex/deep.config.toml（深度推理）
model = "deepseek-reasoner"
model_reasoning_effort = "xhigh"

# 使用
codex --profile quick
codex --profile deep

10.4 MCP 服务器

toml 复制代码

# STDIO 服务器
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
enabled_tools = ["resolve-library-id", "get-library-docs"]

# HTTP 服务器
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

10.5 Hooks 系统

存储位置：~/.codex/hooks.json 或 <repo>/.codex/hooks.json

支持事件：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、Stop、SubagentStart/Stop、PreCompact

json 复制代码

{
  "PreToolUse": [{
    "matcher": "^Bash$",
    "hooks": [{
      "type": "command",
      "command": "python3 ~/.codex/hooks/pre_bash_audit.py",
      "timeout": 30
    }]
  }]
}

10.6 AGENTS.md 项目指令

Codex 自动从 Git 仓库根目录加载 AGENTS.md，无需额外配置：

markdown 复制代码

# AGENTS.md

## 技术栈
- TypeScript + React 18 + Vite
- 状态管理：Zustand
- 样式：Tailwind CSS

## 编码规范
- 使用 strict TypeScript 模式
- 导出使用 named export
- 测试框架：Vitest

可自定义根目录标记：project_root_markers = [".git", ".hg"]

11. 常见问题

问题	原因	解决方案
Codex 报 404	协议不匹配	使用 CC-Switch / mimo2codex 协议转换；或降级到 0.80.0
`openai_base_url` 不生效	项目级 `.codex/config.toml` 会忽略此键	移到 `~/.codex/config.toml`
DeepSeek 上游 404	Base URL 带了 `/chat/completions`	只保留根地址
白屏/无法启动	图形驱动或权限问题	检查 macOS 辅助功能权限；用 `codex --terminal` 纯终端模式
沙箱内 pip/npm 超时	`network_access = false`	设置 `sandbox_workspace_write.network_access = true`
Windows 运行失败	官方暂不支持原生 Windows	使用 WSL 2
非 Git 目录不能运行	Codex 要求 Git 仓库	`git init` 初始化仓库
工具调用退化	转换层未完整映射	更换代理方案或接受能力折损（Image Gen / Computer Use 不可用）

12. 最佳实践

首选 CC-Switch + DeepSeek：图形化管理 + 稳定协议转换 + 多工具统一，是目前最成熟的国内接入方案。
七牛云直连用于快速上手：三行配置即可跑通，适合初次体验。
API Key 只放环境变量 ：不在 config.toml 中硬编码，通过 env_key 引用。
Profile 分场景使用 ：轻量任务用 quick profile（省 Token），复杂推理用 deep profile。
沙箱就不要全关 ：workspace-write 是平衡安全与效率的最佳默认值。
接受功能折损：接入国产模型后，Image Gen 和 Computer Use 能力不可用，基础编码/调试/文件操作正常。

参考资源

GitHub 仓库： github.com/openai/codex
官方文档： developers.openai.com/codex
配置参考： developers.openai.com/codex/config-reference
CC-Switch： github.com/farion1231/cc-switch
mimo2codex： github.com/7as0nch/mimo2codex
codex-proxy： npmjs.com/package/@roson_liu/codex-proxy
七牛云 AI： portal.qiniu.com/ai-inference
SiliconFlow： docs.siliconflow.cn
awesome-codex-cli： github.com/RoggeOhta/awesome-codex-cli