Codex CLI 从零安装到精通：config.toml 完全详解与 DeepSeek 接入实战（Mac 2026万字教程）

Codex CLI是OpenAI推出的命令行AI编程助手，对标Claude Code。它使用OpenAI的Responses API协议，支持文件读写、代码执行、Shell命令等工具调用。本文是2026年最详细的Codex CLI教程：从安装到config.toml每个字段的含义，从日常使用到DeepSeek接入，超过8000字，全部手把手截图级讲解。

一、Codex CLI 是什么？

Codex CLI是OpenAI在2025年底推出的命令行AI编程代理（Coding Agent）。它运行在终端中，能理解你的代码库、执行shell命令、读写文件、安装依赖——就像一个会编程的AI同事坐在你旁边。

和Claude Code一样，Codex CLI属于Agentic Coding工具：不是简单的代码补全，而是能自主完成编程任务的AI代理。你给它一个需求（"给这个项目加单元测试"），它会自己读代码、写测试、运行、修复。

Codex CLI vs 其他AI编程工具

Codex CLI的核心优势在于深度绑定OpenAI生态。如果你主要用GPT-5，Codex CLI是最佳选择。但如果你需要多模型切换、微信接入、定时任务等，Hermes Agent更合适。

二、环境准备

2.1 系统要求

• 操作系统：macOS 12+ / Windows 10+ / Linux
• Node.js：18.0.0 或更高版本（必须）
• npm：9.0+（随Node.js一起安装）
• 磁盘空间：至少500MB
• 网络：需要稳定连接API

2.2 安装Node.js（Mac）

# 方式一：Homebrew（推荐）
brew install node@18

# 方式二：nvm（推荐高级用户）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install 18
nvm use 18

# 验证
node --version  # v18.x.x+
npm --version   # 9.x.x+

2.3 配置npm（避免EACCES权限错误）

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

三、安装Codex CLI

npm install -g @openai/codex-cli
codex --version  # 验证
which codex     # 查看安装位置

常见安装错误

更新与卸载

# 更新
npm update -g @openai/codex-cli
# 卸载
npm uninstall -g @openai/codex-cli
rm -rf ~/.codex

四、config.toml 完全详解

config.toml是Codex CLI的核心配置文件，位置：~/.codex/config.toml。首次运行Codex会自动创建，你也可以手动编辑。

4.1 [model_providers] 节

定义API提供商。每个provider有这些字段：

完整示例：

[model_providers.openai]
base_url = "https://api.openai.com/v1"
api_key = "sk-your-key"

[model_providers.ccswitch]
base_url = "http://127.0.0.1:7890/v1"
wire_api = "responses"
requires_openai_auth = false
stream_idle_timeout_ms = 300000

[model_providers.deepseek_proxy]
base_url = "http://127.0.0.1:11435/v1"
wire_api = "responses"
requires_openai_auth = false

4.2 [profiles] 节

定义可用模型配置：

完整示例：

[profiles.gpt5]
model_provider = "openai"
model_name = "gpt-5"
context_window = 200000
max_output_tokens = 32768

[profiles.deepseek]
model_provider = "ccswitch"
model_name = "deepseek-v4-pro"
context_window = 1000000
max_output_tokens = 32768

[profiles.deepseek.features]
tool_search = false
tool_search_always_defer_mcp_tools = false

4.3 全局设置 [settings]

[settings]
default_profile = "gpt5"
max_concurrent_tools = 5
tool_call_timeout_ms = 60000

五、命令行使用全指南

# 交互模式
codex
codex --profile deepseek

# 单次查询
codex -p "写Python快速排序"

# 分析文件
codex -p "解释这个文件" < app.py

# 管道输入
cat error.log | codex -p "分析错误日志"

# 自动接受编辑（谨慎）
codex --accept-edits -p "重构这个文件" < old.py

# 详细日志
codex --verbose -p "debug this"

六、通过CC-Switch使用Codex

# 1. 确保CC-Switch运行
lsof -i :7890

# 2. config.toml
[model_providers.ccswitch]
base_url = "http://127.0.0.1:7890/v1"
wire_api = "responses"
requires_openai_auth = false

# 3. 使用
codex --profile deepseek

七、接入DeepSeek完整流程

# 1. 部署ccswitch-deepseek
git clone https://github.com/liuzhengming/ccswitch-deepseek.git
cd ccswitch-deepseek && npm install
echo "api_key=sk-your-key" > .env && npm start

# 2. config.toml
[model_providers.deepseek_proxy]
base_url = "http://127.0.0.1:11435/v1"
wire_api = "responses"
requires_openai_auth = false

[profiles.deepseek]
model_provider = "deepseek_proxy"
model_name = "deepseek-v4-pro"
context_window = 1000000
max_output_tokens = 32768

# 3. 使用
codex --profile deepseek -p "写冒泡排序"

八、FAQ（10个常见问题）

九、总结

1. brew install node@18 → npm install -g @openai/codex-cli
2. 配置~/.codex/config.toml：定义provider和profile
3. 用CC-Switch统一管理API，用ccswitch-deepseek接入DeepSeek
4. 日常使用：codex --profile deepseek开始编程

Codex CLI是2026年AI编程三巨头之一。虽然接入DeepSeek比Claude Code多一步协议转换，但配合CC-Switch和ccswitch-deepseek后体验同样流畅。花30分钟搭好环境，长期享受AI辅助编程效率。

本文链接：https://www.kkkliao.cn/?id=3897 转载需授权！