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

# Codex

# 通过 AGIPower 使用 Codex CLI 指南

Codex CLI 是 OpenAI 推出的开源编程助手工具，可以在本地终端运行，能够在您选择的目录中读取、修改和运行代码。它使用 Rust 构建，速度快、效率高，并在 GitHub 上持续改进。通过与 AGIPower 的集成，您可以使用更多模型选择，而不仅仅局限于 OpenAI 官方 API。

> [!NOTE]
>
> OpenAI 已明确将 Responses 作为新一代统一接口，Chat Completions 仍可使用但不再是新项目首选；Codex 也将顺应这一方向，把 Chat Completions 视为兼容选项并逐步迁移到 Responses（本文配置即按 Responses 给出）。
>
> 注意 OpenAI 协议的 base\_url="[https://api.agipower.ai/v1"。](https://api.agipower.ai/v1"。)

## 配置方案

### 安装 Codex CLI

```bash title="npm/pnpm" theme={null}
# 使用 pnpm 安装（推荐）
pnpm install -g @openai/codex

# 或使用 npm 安装
npm install -g @openai/codex
```

### 配置环境变量

在您的 shell 配置文件中添加 AGIPower API Key：

```bash theme={null}
# 编辑 ~/.zshrc 或 ~/.bashrc 文件，根据您实际使用的终端来选择
export AGIPower_API_KEY="sk-xxx"  # [!code highlight]
```

> [!WARNING]
>
> 请确保将 `sk-xxx` 替换为您的真实 AGIPower API Key。您可以在 [AGIPower 控制台](https://agipower.ai/settings/keys) 中获取 API Key。

### 配置 Codex

创建或修改 Codex 配置文件 `~/.codex/config.toml`：

```toml theme={null}
model_provider = "agipower"  # [!code highlight]
model = "openai/gpt-5.2-codex"  # [!code highlight]

[model_providers.agipower]  # [!code highlight]
name = "AGIPower"  # [!code highlight]
base_url = "https://api.agipower.ai/v1"  # [!code highlight]
env_key = "AGIPower_API_KEY"  # [!code highlight]
wire_api = "responses"  # [!code highlight]
```

> [!TIP]
>
> * `model_provider`: 指定使用 AGIPower 作为模型提供商
> * `model`: 设置要使用的模型，可以是 AGIPower 支持的任何模型
> * `base_url`: AGIPower API 的基础 URL
> * `env_key`: 环境变量中 API Key 的名称
> * `wire_api`: 指定使用 Responses 协议（推荐）

### 直接启动使用

配置完成后，重新加载 shell 配置并启动 Codex：

```bash theme={null}
# 重新加载配置文件
source ~/.zshrc  # 或 source ~/.bashrc

# 进入项目目录
cd my-project

# 直接启动 Codex CLI
codex  # [!code highlight]
```

> [!TIP]
>
> 将环境变量配置添加到 shell 配置文件后，就无需每次手动设置。配置会在每次打开新终端时自动生效。

## 支持的模型

您可以灵活更换 `config.toml` 中的 `model` 字段为 AGIPower 支持的任何模型。

> [!NOTE]
>
> * 通过 [AGIPower 模型列表](https://agipower.ai/models?sort=newest\&supported_protocol=responses) 查看 Responses 协议可用模型
> * 使用模型的 slug 名称（如 `openai/gpt-5.2-codex`）
> * 如需指定特定供应商，请参考 [Provider Routing 文档](https://docs.agipower.ai/zh/guide/provider-routing)

支持Responses协议的模型请访问 [AGIPower 模型列表](https://agipower.ai/models?sort=newest\&supported_protocol=responses) 查看！

## 故障排除

### 常见问题解决

#### API Key 错误

**问题**：提示 API Key 无效或未授权

**解决方案**：

* 检查环境变量 `AGIPower_API_KEY` 是否正确设置
* 使用 `echo $AGIPower_API_KEY` 验证环境变量值
* 确认 API Key 是否已激活且有足够余额
* 验证 API Key 格式是否以 `sk-` 开头

#### 连接失败问题

**问题**：Codex CLI 无法连接到 AGIPower 服务

**解决方案**：

* 检查网络连接是否正常
* 验证 `config.toml` 中的 `base_url` 是否配置正确为 `https://api.agipower.ai/v1`
* 确认防火墙设置是否阻止了外部连接
* 尝试使用 `curl https://api.agipower.ai/v1/models` 测试连接

#### 环境变量配置不生效

**问题**：设置了 API Key 后仍然提示未配置

**解决方案**：

* 重新打开终端窗口，或执行 `source ~/.zshrc` 或 `source ~/.bashrc` 重新加载配置
* 确认环境变量已正确设置：`echo $AGIPower_API_KEY`
* 检查是否在正确的 shell 配置文件中添加了环境变量（zsh 用户使用 `.zshrc`，bash 用户使用 `.bashrc`）

#### 配置文件路径问题

**问题**：修改配置文件后不生效

**解决方案**：

* 确认配置文件路径为 `~/.codex/config.toml`
* 如果目录不存在，需要先创建：`mkdir -p ~/.codex`
* 检查配置文件语法是否正确（TOML 格式）
* 使用 `cat ~/.codex/config.toml` 验证文件内容

#### 模型不可用

**问题**：使用某个模型时提示模型不可用或不支持

**解决方案**：

* 访问 [AGIPower 模型列表](https://agipower.ai/models?sort=newest\&supported_protocol=responses) 确认模型是否可用
* 检查模型 slug 拼写是否正确
* 尝试使用其他推荐的模型进行测试
* 确认您的账户是否有权限访问该模型

## 进阶配置

### 配置不同规模的模型

您可以根据不同任务需求在 `config.toml` 中切换不同规模的模型：

```toml title="均衡配置" theme={null}
# 平衡性能和成本的模型选择
model_provider = "agipower"
model = "anthropic/claude-sonnet-4.5"

[model_providers.agipower]
name = "AGIPower"
base_url = "https://api.agipower.ai/v1"
env_key = "AGIPower_API_KEY"
wire_api = "responses"
```

```toml title="性能优先配置" theme={null}
# 注重性能表现的模型选择
model_provider = "agipower"
model = "openai/gpt-5.2-codex"

[model_providers.agipower]
name = "AGIPower"
base_url = "https://api.agipower.ai/v1"
env_key = "AGIPower_API_KEY"
wire_api = "responses"
```

```toml title="成本优化配置" theme={null}
# 注重成本效益的模型选择
model_provider = "agipower"
model = "deepseek/deepseek-chat"

[model_providers.agipower]
name = "AGIPower"
base_url = "https://api.agipower.ai/v1"
env_key = "AGIPower_API_KEY"
wire_api = "responses"
```

> [!TIP]
>
> 如果您在使用过程中遇到任何问题，或有任何建议和反馈，欢迎通过以下方式联系我们：
>
> * **官方网站**：[https://agipower.ai](https://agipower.ai)
> * **技术支持邮箱**：[support@agipower.ai](mailto:support@agipower.ai)
>
> 更多联系方式和详细信息，请访问我们的[联系我们页面](https://docs.agipower.ai/zh/help/contact.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.