---
verifiedAt: '2026-08-22'
---

# Codex 使用指南

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

## 安装

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

<DocsTabs default-tab="app">
  <DocsTab title="Codex App" name="app">

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

按系统选择对应安装包：

- [Codex App for Windows](https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi)
- [Codex App for macOS (Apple Silicon)](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)
- [Codex App for macOS (Intel)](https://persistent.oaistatic.com/codex-app-prod/Codex-latest-x64.dmg)

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

  </DocsTab>

  <DocsTab title="Codex CLI" name="cli">

推荐在终端中使用 `Codex CLI`。

安装方式：

```bash
npm install -g @openai/codex
```

验证安装：

```bash
codex --help
```

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

  </DocsTab>

  <DocsTab title="npx 直接调用" name="npx">

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

```bash
npx @openai/codex
```

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

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

如果后续经常使用，建议全局安装以获得更快的启动速度。

  </DocsTab>
</DocsTabs>

## 导入

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

<DocsTabs default-tab="cc-switch-setup">
  <DocsTab title="使用 CC-Switch" name="cc-switch-setup">

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

操作步骤：

1. 按 [创建 API Key 教程](https://docs.tryflux.net/docs/flux/create-apikey.md) 生成 API Key。
2. 按 [CC-Switch](https://docs.tryflux.net/docs/agents/cc-switch.md) 完成统一供应商配置。
3. 配置完成后，重启 `Codex` 或 `Codex App`。

  </DocsTab>

  <DocsTab title="手动填写" name="manual-setup">

**第一步：确认配置目录**

`Codex` 的本地配置目录为：

- Windows：`%userprofile%\.codex`
- macOS / Linux：`~/.codex`

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

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

**第二步：写入 `config.toml`**

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

```toml
model_provider = "flux"
model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true

[model_providers.flux]
name = "OpenAI"
base_url = "https://api.tryflux.net/v1"
wire_api = "responses"
requires_openai_auth = true
```

**第三步：写入 `auth.json`**

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

```json
{
  "OPENAI_API_KEY": "YOUR_FLUX_API_KEY"
}
```

将 `YOUR_FLUX_API_KEY` 替换为实际的 API Key。

**WebSocket 版本（可选）**

如需使用 WebSocket 协议，`config.toml` 还需额外配置：

```toml
supports_websockets = true

[features]
responses_websockets_v2 = true
```

  </DocsTab>
</DocsTabs>

## 关于远程压缩

上方配置已经把 `[model_providers.flux]` 的 `name` 设为 `OpenAI`，正是为了开启 Codex 的远程压缩。

`Codex` 在长对话接近上下文上限时会触发压缩。只有当上游 provider 的 `name` 严格为 `OpenAI` 时，`Codex` 才会优先走远程压缩接口（`/v1/responses/compact`）；远程压缩质量更高，超长对话也能稳定保持，不容易降智。

如果把 `name` 改成其他值（例如 `flux`），`Codex` 会强制使用本地压缩，效果较差。

说明：

- `name` 是用于触发远程压缩的显示名，保持 `OpenAI` 即可。
- provider 标识 `flux`（即 `model_provider` 和 `[model_providers.flux]`）不受影响，保持不变。
- 这个设置不会丢失已有聊天记录。

## 1M 上下文窗口

`ChatGPT` 分组已全面支持 100 万上下文，推荐开启。

### 安装 Skill

克隆到 `Codex` 的用户 Skill 目录：

```bash
git clone https://github.com/smartcmd/codex-context-window.git ~/.codex/skills/codex-context-window
```

也可以把下面这段直接发给 `Codex`，让它自己完成安装和配置：

```text
安装这个 Skill：https://github.com/smartcmd/codex-context-window

然后将 gpt-5.6-luna、gpt-5.6-terra、gpt-5.6-sol 的上下文窗口调整为 1M，自动压缩阈值设置为 900k。
```

### 配置模型

新开一个任务让 `Codex` 发现 Skill，然后发送：

```text
将 gpt-5.6-luna、gpt-5.6-terra、gpt-5.6-sol 的上下文窗口调整为 1M，自动压缩阈值设置为 900k。
```

Skill 会依次确认目标模型、原始窗口大小、有效窗口比例和自动压缩策略，确认后才写入配置。有效比例保持默认的 `95%` 即可（1M 原始窗口对应可用上下文为 `950000` token，状态栏显示折算后的数值）。配置完成后重启 `Codex`。

### 确认是否生效

- `Codex App`：在 **设置 → 常规 → 编辑器** 中开启 **显示上下文窗口使用情况**，新开一条消息即可看到窗口大小。
- `Codex CLI`：输入 `/status`，在输出中查看 **Context window**。

## 关于 codex-auto-review

为消除歧义，`codex-auto-review` 现已默认重定向到 `gpt-5.6-sol`。

模型路由功能已经上线，可以在 [API 密钥页面](https://tryflux.net/keys) 自助把它重定向到 `gpt-5.6-terra` 或 `gpt-5.6-luna`，以降低花费。