> ## Documentation Index
> Fetch the complete documentation index at: https://api.xcompute.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex 接入

> 基于 OpenAI 官方 Codex CLI 文档与配置方式，把 Codex 接到 Xcompute。

Codex 是 OpenAI 官方的编程 Agent。它既有桌面端，也有 CLI。这里重点写 CLI，因为这是最适合接中转站和自定义 `Base URL` 的方式。

<Frame>
  <img src="https://developers.openai.com/og/codex/cli.png" alt="Codex CLI 官方图" />
</Frame>

<caption>*Codex CLI 官方页面配图*</caption>

<Warning>
  Codex 更新很快，配置字段以后可能会变化。你要记住的是思路：先安装官方 CLI，再通过 `~/.codex/config.toml` 接入 Xcompute。
</Warning>

## 这篇文章会带你完成什么

1. 安装 Codex CLI
2. 找到本地 `.codex` 配置目录
3. 配置 `Base URL` 和 `API Key`
4. 完成第一次交互式使用

## Codex 官方安装方式

如果你还没准备 Node 环境，先看 [环境准备：NVM、Node.js 22 和 npm](/node-setup)。

官方 CLI 安装命令：

```bash theme={null}
npm install -g @openai/codex
```

验证：

```bash theme={null}
codex --help
```

如果命令能正常输出帮助信息，说明 CLI 已经安装好了。

## 你需要准备的内容

1. `Base URL`：`https://xcompute.us/v1`
2. `API Key`：你的 Xcompute 密钥，格式一般以 `sk-` 开头

## 第一步：先创建 API Key

1. 打开 [Xcompute API 密钥页面](https://xcompute.us/keys)
2. 创建一把新密钥
3. 记下这两个信息：
   * `Base URL`
   * `API Key`

## 第二步：先运行一次 Codex

这一步很重要。你需要先执行一次：

```bash theme={null}
codex
```

这样它才会在你的用户目录下生成 `.codex` 配置目录。

常见位置：

* Linux / macOS：`~/.codex`
* Windows：`C:\Users\你的用户名\.codex`

如果你找不到这个目录，说明你还没真正执行过一次 `codex`。

## 第三步：编辑 Codex 配置

根据 OpenAI 官方文档，Codex 的用户级配置文件在：

* `~/.codex/config.toml`

如果你只想先跑通，可以先用一份最小配置。

### 建议配置

```toml theme={null}
model_provider = "OpenAI"
model = "gpt-5.5"
review_model = "gpt-5.5"
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.OpenAI]
name = "OpenAI"
base_url = "https://xcompute.us/v1"
wire_api = "responses"
requires_openai_auth = true
```

这份配置适合“先跑通再说”的用户。

### 更稳妥的写法

如果你想更接近官方文档里的 provider 配置方式，也可以写成：

```toml theme={null}
model = "gpt-5.5"
model_provider = "xcompute"

[model_providers.xcompute]
name = "Xcompute"
base_url = "https://xcompute.us/v1"
env_key = "XCOMPUTE_API_KEY"
wire_api = "responses"
```

然后在环境变量里放密钥：

```bash theme={null}
export XCOMPUTE_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

如果你当前版本的 Codex 对自定义 provider 支持不稳定，再回退到上面那份兼容思路即可。

## 第四步：配置 API Key

```json theme={null}
{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

如果你不想把密钥写在文件里，也可以只保留环境变量写法。

## 第五步：重新启动 Codex

```bash theme={null}
codex
```

重新进入后，如果能正常工作，就说明已经通过 Xcompute 接好了。

## 第一次正式使用：一步一步来

### 1. 进入项目目录

```bash theme={null}
cd your-project
```

### 2. 启动 Codex

```bash theme={null}
codex
```

### 3. 先做一个低风险任务

```text theme={null}
请先帮我解释这个项目的目录结构
```

### 4. 再做一个轻量修改

```text theme={null}
请帮我给首页增加一句欢迎语
```

## 日常使用教程

<Steps>
  <Step title="进入项目目录启动">
    ```bash theme={null}
    cd your-project
    codex
    ```
  </Step>

  <Step title="执行一次快速问答">
    ```text theme={null}
    帮我解释这个仓库的核心结构
    ```
  </Step>

  <Step title="执行一次真实修改任务">
    ```text theme={null}
    为这个项目补充一个登录失败重试提示，并告诉我改了哪些文件
    ```
  </Step>
</Steps>

## 常见问题

### 找不到 `.codex/config.toml` 怎么办？

先执行一次：

```bash theme={null}
codex
```

退出后再去用户目录找。

### 为什么我建议先用最小配置？

因为 Codex 的配置能力很多，非技术用户一开始最容易被一大堆字段吓到。先跑通，再慢慢加规则。

## 常用能力

1. `codex`：进入交互模式
2. `codex "你的问题"`：单次执行
3. 使用截图或设计稿作为输入
4. 在大型任务里用多轮对话持续推进

## Windows 使用建议

OpenAI 官方文档对 Windows 的建议是：

1. 可以原生跑 Windows
2. 也可以在 WSL2 里跑
3. 如果你更熟悉 Linux 工具链，WSL2 会更稳

## 可选：桌面版

如果你想试桌面版，也可以看官方入口：

* [https://chatgpt.com/zh-Hans-CN/codex](https://chatgpt.com/zh-Hans-CN/codex)

<Tip>
  如果某个版本的配置格式变了，不要死抠旧字段名。你只要记住四个关键点就行：安装官方 CLI、运行一次生成配置目录、找到 `config.toml`、把 `Base URL` 和 `API Key` 指到 Xcompute。
</Tip>