Codex CLI 简介

1.1 什么是 Codex CLI?

定位与 Claude Code 一样。Codex CLI 是由 OpenAI 开发的开源系统级 AI 助手，使用 Rust 语言编写，具有极高的性能和效率。它可以在终端中读取、修改和运行代码，是一个真正意义上的 AI Agent。

核心特性:

特性	说明
Rust 原生构建	极速启动和响应，内存占用极低
开源	完全开源，社区驱动，代码透明可审计
多模型支持	原生支持 OpenAI、Ollama、LM Studio、Amazon Bedrock，也可自定义接入任意兼容 API
ChatGPT 认证	支持 ChatGPT Plus/Pro/Business/Edu/Enterprise OAuth 登录，不一定要 API Key
多级 Sandbox	macOS Seatbelt、Linux bubblewrap、Windows 原生沙箱，平台级安全保障
MCP 协议	通过 Model Context Protocol 连接任意外部工具和服务
多 Agent 协作	内置 Subagent 系统，支持并行任务委派
Skills & Plugins	可复用的工作流技能包和可分发的插件系统
内置记忆系统	跨会话的 Memory 机制，自动提取和整合项目知识

---

二、安装与配置

2.1 系统要求

平台	要求
macOS	12+ (Monterey 及以上)
Linux	Ubuntu 20.04+ / Debian 10+
Windows	Windows 10/11 (原生 PowerShell 沙箱或 WSL2)
RAM	最低 4 GB，推荐 8 GB
Git	2.23+ (可选，用于版本控制功能)

2.2 安装 Codex CLI

方式一：npm 全局安装（推荐）:

npm i -g @openai/codex

方式二：Homebrew 安装（macOS）:

brew install --cask codex

方式三：从 GitHub Releases 下载二进制文件:

前往 openai/codex 的 Releases 页面，下载对应平台的预编译二进制文件。

方式四：从源码构建（Rust/Cargo）:

git clone https://github.com/openai/codex.git
cd codex
cargo build --release

💡 仓库中还提供了 justfile，包含构建和测试的辅助命令。

验证安装:

codex --version
# 或 codex -V

# 查看帮助
codex --help

升级 Codex CLI:

npm i -g @openai/codex@latest
# 或 codex update

2.3 认证配置

Codex CLI 支持三种认证方式：

方式一：ChatGPT OAuth 登录（默认，最简单）

这是最推荐的方式，不需要 API Key，只要有 ChatGPT 订阅即可。

# 首次运行 codex 时自动触发 OAuth 登录流程
# 也可以手动登录
codex login

# 支持的订阅类型：
# - ChatGPT Plus
# - ChatGPT Pro
# - ChatGPT Business
# - ChatGPT Edu
# - ChatGPT Enterprise

登录后凭证保存在本地，后续使用无需重复登录。

登出:

codex logout

# 或在交互式会话中
/logout

凭证存储方式配置（cli_auth_credentials_store）:

存储方式	说明
file	存储在本地文件
keyring	使用系统密钥链（macOS Keychain/Linux Secret Service/Windows Credential Manager）
auto	自动选择（默认）

方式二：API Key

# Linux/macOS
export OPENAI_API_KEY="sk-your-api-key"

# 永久配置
echo 'export OPENAI_API_KEY="sk-your-api-key"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell（永久配置）
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-api-key", "User")

方式三：通过 stdin 传入 Access Token

echo "your-access-token" | codex

2.4 配置第三方模型供应商

Codex CLI 原生支持多种模型供应商。

内置供应商

这部分我没这么用过，内容只做参考，这里只做资料收集整理

供应商 ID	说明	认证方式
openai	OpenAI API（默认）	OPENAI_API_KEY 环境变量
ollama	本地模型（Ollama）	无需 Key，自动连接本地 Ollama 服务
lmstudio	本地模型（LM Studio）	无需 Key，自动连接本地 LM Studio 服务
amazon-bedrock	AWS Bedrock 托管模型	AWS Profile + Region

快速接入本地开源模型

使用 --oss 标志可以一键配置本地开源模型：

# 自动检测并连接本地 Ollama 或 LM Studio
codex --oss

在配置文件中指定默认本地供应商：

# ~/.codex/config.toml
oss_provider = "ollama"  # 或 "lmstudio"

自定义第三方供应商

注：关于第三方模型兼容性限制

有一点需要强调的是，Codex CLI 使用的 API 协议规范与 OpenAI 的行业标准 API 协议规范不一样，Codex CLI 使用的是 Responses API 协议，而非行业标准的 Chat Completions API。

所以会有小伙伴发现将 DeepSeek、Kimi 等第三方模型的官方提供 OpenAI 标准规范的接口接入 Codex CLI 仍然无法正常工作就是这个原因，API 在协议层面不兼容。

维度	Chat Completions（行业标准）	Responses API（仅 Codex 支持）
端点	POST /v1/chat/completions	POST /v1/responses
请求格式	messages: [...]	input: [...] + tools + instructions
行业支持	几乎所有供应商都实现	OpenAI 支持

从时间线上看 2026 年 2 月起 Codex CLI 就完全移除 Chat Completions 支持（wire_api 仅支持 "responses"）。所以无论怎么配置 base_url，Codex 发出的请求都是 Responses API 格式，而 DeepSeek、Kimi、GLM、Qwen 等第三方供应商官方支持的 API 只有 Chat Completions 端点，无法理解和处理这种请求。

另一方面，Claude Code 使用的是 Anthropic Messages API，第三方供应商已经实现了对该协议的兼容（例如直接提供 https://api.deepseek.com/anthropic 端点），所以 cc-switch 换个 URL 就能生效。而 Codex CLI 的问题在于协议格式对不上，供应商未支持，所以换 Chat Completions 协议的地址依旧无法使用。

邪修方案：如果确实需要 Codex CLI + 第三方模型，可以使用本地代理（GitHub 上有类似的开源项目，比如 codeproxy-ai/cli，但该项目我未实际试用过，仅作参考）在中间做协议转换，将 Codex 发出的 Responses API 请求转换为 Chat Completions 格式再转发给第三方供应商。

通过这种方式配置 model_providers 配置块可以接入任意兼容 OpenAI Responses API 的服务。

# 启动本地代理
npx @codeproxy/cli --upstream-format openai-chat \
--base-url https://api.deepseek.com/v1 \
--apikey sk-your-deepseek-key

# 然后在 Codex 配置中指向本地代理
[model_providers.deepseek]
name = "DeepSeek"
base_url = "http://127.0.0.1:8787/v1"  # 指向本地代理，而非 DeepSeek 官方地址
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

自定义供应商完整参数:

参数	说明
base_url	API 基础地址
env_key	存放 API Key 的环境变量名
name	供应商显示名称
wire_api	协议类型（目前仅支持 "responses"）
http_headers	静态 HTTP 请求头
env_http_headers	从环境变量读取的 HTTP 请求头
query_params	额外查询参数
request_max_retries	HTTP 重试次数（默认 4）
stream_idle_timeout_ms	SSE 空闲超时（默认 300000ms）
stream_max_retries	SSE 重试次数（默认 5）
supports_websockets	是否支持 WebSocket 传输

配置示例

一个比较完整的 ~/.codex/config.toml 配置示例，展示如何同时配置多个供应商并使用自定义供应商作为默认：

#:schema https://developers.openai.com/codex/config-schema.json