---
title: "接入 Codex"
description: "用一个 API Key、一个模型名，把 Codex CLI、ChatGPT 桌面 App 与 VS Code 扩展接到 AI Runtime。"
---

> Documentation Index
> Fetch the complete documentation index at: https://help.airuntime.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 接入 Codex

## 你会得到什么

Codex 是 OpenAI 的 AI 编程助手，通过 Responses API 与模型通信；`https://api.airuntime.dev/v1`
也提供这套接口。Codex CLI、ChatGPT 桌面 App 和 VS Code 的 Codex 扩展读同一个配置文件，所以只需
配置一次，三者都能用上 AI Runtime。

你只需要发一个名字：`deepseek`。具体由哪家已审阅的上游来回答由 AI Runtime 决定，厂商的模型 id
不会出现在你的配置或请求里。

## 1. 把 AI Runtime 配成模型 provider

你需要一个 Workspace API Key，在控制台签发时只显示一次，以 `rk_` 开头。这个 Key 能调用哪个 Pool
决定了你拿到的模型名；本页假设它是一个文本 Pool，model 是 `deepseek`。

### 方案一：安装脚本（推荐）

先确认已经运行过 Codex CLI 或 ChatGPT 桌面 App 至少一次，这样 `~/.codex` 目录已经存在。然后在
macOS / Linux 终端里执行：

```bash
bash <(curl -fsSL https://help.airuntime.dev/codex-airuntime-setup.sh)
```

选择 `1` 把 Codex 指向 AI Runtime，选择 `9` 撤销。脚本会：

- 把 `~/.codex/config.toml` 备份到 `~/.codex/backup-airuntime/`，随时可以还原；
- 写入模型目录 `~/.codex/model-catalogs/airuntime.json`，向 Codex 声明上下文窗口、推理档位、
  工具调用格式等元数据，让 `deepseek` 用起来和内置模型一样；
- 在 `~/.codex/config.toml` 里补上 `[model_providers.airuntime]` 段，并且只改它需要的那几个
  字段。你的 MCP server、项目信任设置等都不会被动；
- 把 API Key 写进 `~/.codex/config.toml` 的 `[model_providers.airuntime]` 段，字段是
  `experimental_bearer_token`，和 DeepSeek 官方安装脚本的做法一致；记得把文件权限收紧
  （`chmod 600 ~/.codex/config.toml`）；
- 写入前先校验生成的文件，校验不通过就什么都不改。

随时可以再跑一次重写配置，或选 `9` 还原到安装前的状态。如果你还留着
`~/.codex/switch-model.sh`，`switch-model.sh airuntime` 是同一套安装，
`switch-model.sh restore-airuntime` 是同一套还原。

### 方案二：自己改配置文件

先把模型目录写到 `~/.codex/model-catalogs/airuntime.json`。安装脚本写入的那份文件发布在
[/airuntime-models.json](https://help.airuntime.dev/airuntime-models.json)，可以直接下载或复制。关键字段是 `slug`
（Codex 发送的模型名，即 `deepseek`）、`apply_patch_tool_type`（`freeform`）、
`context_window` 和 `supported_reasoning_levels`。

然后在 `~/.codex/config.toml` 里加上：

```toml
model = "deepseek"
model_provider = "airuntime"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/model-catalogs/airuntime.json"
web_search = "disabled"

[model_providers.airuntime]
name = "AI Runtime"
base_url = "https://api.airuntime.dev/v1"
wire_api = "responses"
experimental_bearer_token = "rk_..."
```

把 `rk_...` 换成你控制台里的 API Key，然后确保文件只有你自己能读：

```bash
chmod 600 ~/.codex/config.toml
```

这跟 DeepSeek 官方的 Codex 接入方式一致：一把 Key、一个 provider 段，不需要额外凭据存储。

### config.toml 字段说明

| 字段 | 说明 |
| --- | --- |
| `model` | 默认模型。它是你的 Pool 提供的名字，不是厂商的模型 id。 |
| `model_provider` | 使用的 provider，对应下面 `[model_providers.<id>]` 的 id。 |
| `model_reasoning_effort` | 推理档位，支持 `low`、`high`、`max`。越高想得越久，答案更好但更慢。 |
| `web_search` | 内置联网搜索，这个模型上关闭。 |
| `model_catalog_json` | 上面的模型目录路径，Codex 从这里读取模型元数据。 |
| `[model_providers.airuntime]` 的 `name` | provider 的显示名。 |
| `[model_providers.airuntime]` 的 `base_url` | AI Runtime 的 API 入口，`https://api.airuntime.dev/v1`。 |
| `[model_providers.airuntime]` 的 `wire_api` | 与模型通信的协议，`responses` 表示 Responses API。 |
| `[model_providers.airuntime]` 的 `experimental_bearer_token` | 你的 AI Runtime API Key，安装脚本按 DeepSeek 官方脚本的方式写在这里。 |

## 2. 开始使用

三个客户端读同一个文件，不需要分别配置：

- **Codex CLI**：进入项目目录运行 `codex`。启动横幅显示 `model: deepseek` 就说明配置生效了。
- **ChatGPT 桌面 App**：模型选择器显示 “Custom” 或模型名都说明配置生效，具体显示哪个取决于版本。
- **VS Code 的 Codex 扩展**：与 Codex CLI 共用配置，装好直接使用。

## 切换 provider 之后的会话历史

Codex 按登录方式分组保存会话历史：ChatGPT 订阅的会话和第三方 API Key 的会话分开存放，只显示与
当前配置匹配的那一组。会话不会被删除——把配置切回去，之前的会话就回来了，AI Runtime 的会话则
转为隐藏。切换后需要重启客户端。

Source: https://help.airuntime.dev/zh-hans/codex/integrate-with-codex/index.mdx
