Codex 使用指南

Codex 是一款专为代码生成、修改和审查设计的 AI Agent 工具。

本次实测仅覆盖上述 CLI 普通 Key 请求。Codex App、CC-Switch 导入、auth.json 认证、WebSocket 和远程压缩未在本次实测。

安装

根据使用习惯选择安装方式。

Codex App 适合使用图形界面的用户。

按系统选择对应安装包：

• Codex App for Windows
• Codex App for macOS (Apple Silicon)
• Codex App for macOS (Intel)

下载完成后，按照系统提示完成安装并启动即可。

推荐在终端中使用 Codex CLI。

安装方式：

npm install -g @openai/codex

验证安装：

codex --help

命令能正常输出帮助信息即表示安装成功。

无需全局安装，可直接使用 npx 按需调用 Codex。

npx @openai/codex

第一次运行时，npx 会自动下载并执行 Codex。适合以下场景：

• 不想改动全局环境
• 在某台机器上按需运行一次
• 验证 CLI 是否满足需求

如果使用频率较高，建议全局安装以加快启动速度。

导入

安装完成后，选择以下两种方式之一将 Codex 接入 TokenFlux。

推荐使用 CC-Switch 统一管理配置。

操作步骤：

1. 按 创建 API Key 教程 生成 API Key。
2. 在密钥列表里点击该 Key 的“更多”，选择“导入到 CCS”，在 CC-Switch 弹窗中确认导入。详细说明见 CC-Switch。
3. 在 CC-Switch 的 Codex 页面启用刚导入的 TokenFlux 供应商。
4. 重启 Codex 或 Codex App。

第一步：确认配置目录

Codex 的本地配置目录为：

• Windows：%userprofile%\.codex
• macOS / Linux：~/.codex

Codex CLI 与官方 IDE 扩展共享 config.toml 配置层。通过 Zed 的 Codex 外部 Agent 使用时，配置读取方式取决于所安装的集成版本。

建议先启动一次 Codex 或 Codex App，让程序自动初始化配置目录。

第二步：写入 config.toml

模型可选择 gpt-6-astra 或 gpt-6.1-sol，以 Key 所属分组支持的模型为准。下面以 gpt-6-astra 为例。

在配置目录中创建或编辑 config.toml，确保以下内容位于文件开头：

model_provider = "tokenflux"
model = "gpt-6-astra"
review_model = "gpt-6-astra"
model_reasoning_effort = "xhigh"

[model_providers.tokenflux]
name = "OpenAI"
base_url = "https://tokenflux.dev/v1"
wire_api = "responses"
requires_openai_auth = true

第三步：写入 auth.json

在同一目录中创建或编辑 auth.json：

{
  "OPENAI_API_KEY": "YOUR_TOKENFLUX_API_KEY"
}

将 YOUR_TOKENFLUX_API_KEY 替换为实际的 API Key。

WebSocket 版本（可选）

如需使用 WebSocket 协议，将 supports_websockets = true 合并到现有的 [model_providers.tokenflux] 表中，并在 [features] 中开启 responses_websockets_v2。下面展示合并后的供应商配置；同一张表在文件中只保留一份。

[model_providers.tokenflux]
name = "OpenAI"
base_url = "https://tokenflux.dev/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true

[features]
responses_websockets_v2 = true

沙箱网络访问（可选）

使用 workspace-write 沙箱且需要让其中运行的命令联网时，在 config.toml 的 [sandbox_workspace_write] 表中设置：

[sandbox_workspace_write]
network_access = true

该设置控制沙箱内命令的网络访问，不控制 Codex 自身连接模型 API。其他沙箱模式和网络设置见 官方配置参考。

远程压缩

Codex 会在长对话接近上下文上限时压缩历史。压缩方式取决于客户端版本、供应商能力配置和服务端支持。

本页保留 name = "OpenAI" 以兼容已有配置。部分版本会据此选择默认能力；当前版本也支持显式配置供应商能力，不能仅凭显示名判断是否使用远程压缩。远程压缩协议也随版本变化，例如 0.162 系列包含通过 Responses 请求发送 compaction_trigger 的实现。

遇到压缩失败时，请记录 Codex 版本、分组、模型和完整报错，按 排障 反馈。供应商能力字段见 官方配置参考。

codex-auto-review

ChatGPT、ChatGPT (Azure) 和 ChatGPT (不稳定) 分组当前默认将 codex-auto-review 重定向到 gpt-6.1-sol。

如需使用其他模型，可以在 API 密钥页面 设置该 Key 的模型重定向。目标模型须在所选分组中可用，价格可在 模型广场 查看。