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

# Codex 接入 PPIO LLM API

Codex 是一款运行在终端中的 AI 编程工具。您可以通过自定义 OpenAI-compatible endpoint，在 Codex 中连接 PPIO 派欧云的大语言模型 API，用于代码理解、生成、重构和调试等任务。

<Warning>
  Codex 当前仅支持 Responses API。请按本文配置 `wire_api = "responses"`，不要切换到 Chat Completions 模式。
</Warning>

## 前置准备

开始前，请先准备以下信息：

* **API Key**：前往 [API 密钥管理](https://ppio.com/settings/key-management) 创建或复制 API Key。
* **Base URL**：`https://api.ppio.com/openai/v1`
* **Model ID**：前往模型广场或模型详情页，复制需要使用的模型 ID，例如 `deepseek/deepseek-v3.1`。

<Tip>
  请妥善保存 API Key。密钥仅用于本地 Codex 配置，不要提交到 Git 仓库或公开文档中。
</Tip>

## 安装 Codex

在安装 Codex 前，请确保本地环境已安装 [Node.js 18 或更高版本](https://nodejs.org/en/download/)。

如果您使用 macOS 且已安装 Homebrew，可以执行：

```bash theme={null}
brew install node
```

检查 Node.js 与 npm 版本：

```bash theme={null}
node -v
npm -v
```

安装 Codex CLI：

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

检查 Codex 版本：

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

## 配置 API Key

打开您的 shell 配置文件，例如 `~/.zshrc`：

```bash theme={null}
nano ~/.zshrc
```

写入环境变量：

```bash theme={null}
export PPIO_API_KEY="<your-ppio-api-key>"
```

保存后刷新配置，并确认变量已生效：

```bash theme={null}
source ~/.zshrc
echo $PPIO_API_KEY
```

## 配置 Codex

打开 Codex 配置文件：

```bash theme={null}
mkdir -p ~/.codex
nano ~/.codex/config.toml
```

写入以下配置，并将 `model` 替换为您要使用的 PPIO 模型 ID：

```toml theme={null}
model_provider = "ppio"
model = "deepseek/deepseek-v3.1"

[model_providers]
[model_providers.ppio]
name = "PPIO"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://api.ppio.com/openai/v1"
env_key = "PPIO_API_KEY"
```

## 启动 Codex

进入您的项目目录，然后启动 Codex：

```bash theme={null}
cd <your-project-directory>
codex
```

启动后，您可以输入编程任务，例如：

```text theme={null}
请帮我阅读这个项目，并总结主要模块职责。
```

如果 Codex 返回模型不存在或鉴权失败，请检查：

* `PPIO_API_KEY` 是否已在当前终端会话中生效。
* `model` 是否与 PPIO 模型详情页中的 Model ID 完全一致。
* `base_url` 是否为 `https://api.ppio.com/openai/v1`。