# 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` 接入 `Modelink`。

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

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

  操作步骤：

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

  </DocsTab>

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

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

  `Codex` 的本地配置目录通常是：

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

  如果你在 VSCode 或 Zed 中使用 `Codex`，通常同样走 `Codex` 的全局配置；按本节方式写入配置后，重启编辑器即可生效。

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

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

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

  ```toml
  model_provider = "modelink"
  model = "gpt-5.4"
  review_model = "gpt-5.4"
  model_reasoning_effort = "xhigh"
  disable_response_storage = true
  network_access = "enabled"
  windows_wsl_setup_acknowledged = true
  model_context_window = 1000000
  model_auto_compact_token_limit = 900000

  [model_providers.modelink]
  name = "OpenAI"
  base_url = "https://api.aigoo.xyz/v1"
  wire_api = "responses"
  requires_openai_auth = true
  ```

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

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

  ```json
  {
    "OPENAI_API_KEY": "YOUR_MODELINK_API_KEY"
  }
  ```

  将 `YOUR_MODELINK_API_KEY` 替换为你的真实 API Key。


  **WebSocket 版本（可选）**

  如果需要 WebSocket 版本，`config.toml` 还需额外配置：

  ```toml
  supports_websockets = true

  [features]
  responses_websockets_v2 = true
  ```


  </DocsTab>
</DocsTabs>

## 关于远程压缩

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

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

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

说明：

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