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

# Windows

> 在 Windows 上安装 Codex CLI，并通过 AIOAGI 的 OpenAI 兼容接口接入 Codex。

Codex 可以在 Windows 上通过 `npm` 安装。你可以把 Codex CLI 指向 AIOAGI 的 OpenAI 兼容接口，再使用 AIOAGI API Key 调用平台支持的代码模型。

<Info>
  Codex 版本、VS Code 扩展界面、模型名、端点和支持策略可能变化。请以控制台、开发者指南和 OpenAI Codex 官方文档的最新说明为准。
</Info>

<Card title="参考原文" icon="newspaper" href="https://cscitech.blog.csdn.net/article/details/155111533">
  查看 Windows 环境下安装 Codex CLI 并集成到 VS Code 的原文说明。
</Card>

## 准备条件

* Windows 10 或更高版本
* Node.js LTS 版本
* Git for Windows
* 可用的 AIOAGI API Key
* 一个本地代码项目，用于验证 Codex 是否可正常读取仓库

<CardGroup cols={2}>
  <Card title="OpenAI Codex Windows 文档" href="https://developers.openai.com/codex/windows">
    查看 Codex 在 Windows 上的安装和运行说明。
  </Card>

  <Card title="OpenAI Codex 配置文档" href="https://developers.openai.com/codex/config-basic">
    查看 `config.toml`、模型和 Provider 配置方式。
  </Card>

  <Card title="AIOAGI API Key 指南" href="/api-key-guide">
    如果你还没有创建 API Key，可以先完成控制台配置。
  </Card>

  <Card title="开发者指南" href="https://aiearthdev.apifox.cn/">
    核对当前端点、模型和 OpenAI 兼容接口说明。
  </Card>
</CardGroup>

## 安装步骤

<Steps>
  <Step title="安装 Node.js">
    访问 Node.js 官网，下载并安装 LTS 版本。安装完成后，重新打开 PowerShell，并执行下面的命令验证安装结果：

    ```powershell theme={null}
    node --version
    npm --version
    ```
  </Step>

  <Step title="安装 Git for Windows">
    安装 Git for Windows。完成后在 PowerShell 或 `Git Bash` 中执行下面的命令：

    ```powershell theme={null}
    git --version
    ```
  </Step>

  <Step title="安装 Codex CLI">
    打开 PowerShell 或 `Git Bash`，执行下面的命令安装 OpenAI Codex CLI：

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

    安装后执行下面的命令确认版本号：

    ```bash theme={null}
    codex --version
    ```
  </Step>

  <Step title="创建 AIOAGI API Key">
    登录 AIOAGI 控制台，在 **令牌管理** 中创建 API Key。建议为 Codex 单独创建一个 Token 组，便于统计用量和控制额度。
  </Step>

  <Step title="配置 Codex">
    在 Windows 用户目录下创建或更新 `%USERPROFILE%\.codex\config.toml`，把 Codex 指向 AIOAGI 的 OpenAI 兼容接口。
  </Step>

  <Step title="启动 Codex">
    进入你的代码项目目录，执行 `codex`。首次接入时先发送一个简单问题，确认模型能正常返回内容。
  </Step>
</Steps>

## 安装界面示例

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/codex/nodejs-download.png?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=2f1e75cba626a5a5bcfdb01c3a5e66ae" alt="Node.js 下载页面示例" width="1080" height="600" data-path="images/codex/nodejs-download.png" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/codex/codex-install-check.svg?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=035ebcdee67cc4e395bc33585fd086b2" alt="Codex CLI 安装验证示意图" width="1200" height="640" data-path="images/codex/codex-install-check.svg" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/codex/token-management.png?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=93d6894d9fd207653ea011ada0c2d73c" alt="AIOAGI 控制台令牌管理界面示例" width="1080" height="305" data-path="images/codex/token-management.png" />
</Frame>

## AIOAGI 接入配置

### 推荐方式：使用 Windows 用户环境变量

先把 API Key 写入 Windows 用户级环境变量。执行后请重新打开 PowerShell、`Git Bash` 或 VS Code 终端。

```powershell theme={null}
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-your-aioagi-api-key", "User")
```

然后创建 Codex 配置目录和配置文件：

```powershell theme={null}
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"
```

在 `config.toml` 中写入下面的内容：

```toml theme={null}
model_provider = "aioagi"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"

[model_providers.aioagi]
name = "AIOAGI"
base_url = "https://api.aiearth.dev/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

如果你的网络更适合 CDN 加速线路，也可以把 `base_url` 改成：

```toml theme={null}
base_url = "https://api.aiearth.vip/v1"
```

<Warning>
  `gpt-5.1-codex` 仅作为配置示例。模型 ID、可用模型和调用策略可能变化，请先在控制台或开发者指南中确认后再配置。
</Warning>

### 是否需要 `OPENAI_BASE_URL`

如果你按上面的 `config.toml` 配置了 `[model_providers.aioagi].base_url`，不需要再设置 `OPENAI_BASE_URL`。Codex 会从 `config.toml` 读取 AIOAGI 的 base URL，`OPENAI_API_KEY` 只负责提供密钥。

如果你不定义 AIOAGI Provider，而是改用 Codex 内置 `openai` Provider 的代理方式，请在用户级 `config.toml` 中配置 `openai_base_url`：

```toml theme={null}
model_provider = "openai"
model = "gpt-5.1-codex"
openai_base_url = "https://api.aiearth.dev/v1"
```

这种方式仍需要保留 `OPENAI_API_KEY`。不要把 `OPENAI_BASE_URL` 和 `[model_providers.aioagi].base_url` 当作两项必填配置同时维护。

### 兼容方式：使用 `auth.json`

如果你不想写入系统环境变量，也可以在 `%USERPROFILE%\.codex` 下创建 `auth.json`。不要删除整个 `.codex` 目录。已有配置请先备份。

```json theme={null}
{
  "OPENAI_API_KEY": "sk-your-aioagi-api-key"
}
```

此时 `config.toml` 仍保留 AIOAGI Provider 配置：

```toml theme={null}
model_provider = "aioagi"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"

[model_providers.aioagi]
name = "AIOAGI"
base_url = "https://api.aiearth.dev/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/codex/codex-config-files.svg?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=806ad4296f04600ec9d6961dfd11055e" alt="Codex 配置文件位置示意图" width="1200" height="640" data-path="images/codex/codex-config-files.svg" />
</Frame>

## 启动和验证

进入你的代码项目目录后，执行：

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

你可以先用下面这类提示词验证接入是否成功：

```text theme={null}
请先阅读当前仓库结构，再总结主要目录和入口文件。
```

如果 Codex 能正常读取仓库并返回结果，说明 CLI 安装、配置文件和 API Key 已基本可用。

## 集成到 VS Code

安装好 Codex CLI 后，你可以在 VS Code 中安装 Codex 扩展。

<Steps>
  <Step title="打开扩展面板">
    在 VS Code 中点击 **Extensions**，搜索 `Codex`。
  </Step>

  <Step title="安装官方扩展">
    选择 OpenAI 官方 Codex 扩展并安装。安装后重新加载 VS Code。
  </Step>

  <Step title="打开项目">
    在 VS Code 中打开你的项目目录，并确认当前集成终端可以执行 `codex --version`。
  </Step>

  <Step title="验证集成">
    先在 VS Code 集成终端执行 `codex`，再使用扩展入口检查是否能正常调用 Codex。
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/aioagi/bRZH7qujHkk2cLE_/images/codex/vscode-codex-extension.svg?fit=max&auto=format&n=bRZH7qujHkk2cLE_&q=85&s=1c491d633a23159ea50d8ca636efbd2f" alt="VS Code 中安装 Codex 扩展示意图" width="1200" height="640" data-path="images/codex/vscode-codex-extension.svg" />
</Frame>

## 常见问题

<AccordionGroup>
  <Accordion title="执行 `codex` 提示命令不存在" icon="terminal">
    关闭并重新打开 PowerShell 或 `Git Bash`。如果问题仍在，检查 `npm install -g @openai/codex` 是否成功，再执行 `npm prefix -g` 确认全局安装路径是否已经加入 `PATH`。
  </Accordion>

  <Accordion title="认证失败或返回 401 / 403" icon="key">
    检查 `OPENAI_API_KEY` 是否完整复制。再确认 Token 组额度、模型权限、`base_url` 和网络代理设置。你也可以参考 [常见问题](/faq) 中的 Codex 排障条目。
  </Accordion>

  <Accordion title="模型不存在或不可用" icon="sparkles">
    到控制台确认当前 API Key 可访问的模型列表，并核对 `model` 是否与模型 ID 完全一致。如果平台近期调整了模型别名或支持策略，请以控制台和开发者指南最新信息为准。
  </Accordion>

  <Accordion title="配置修改后没有生效" icon="gear">
    确认配置文件位于 `%USERPROFILE%\.codex\config.toml`。如果配置后仍未生效，或仍返回 OpenAI 官方接口的认证、验证错误，请先完全关闭并重新打开 PowerShell、`Git Bash` 和 VS Code。多个终端环境混用时，请确认它们读取的是同一个 Windows 用户目录。如果仍不生效，请重启当前主机后再测试。问题仍存在时，可以通过微信或 QQ 联系平台管理员协助排查。
  </Accordion>
</AccordionGroup>

## 使用建议

* 为 Codex 单独创建 API Key，便于统计开发工具用量
* 先用小额度 Token 组完成连通性测试，再切换到正式额度
* 第一次接入时优先测试读取仓库、解释文件和生成简单补丁
* 长期在 Windows 上开发时，建议固定使用同一种终端方案
* 模型名、价格和支持策略可能变化，请以控制台和开发者指南为准

## 相关文档

* [OpenAI Codex Windows setup](https://developers.openai.com/codex/windows)
* [OpenAI Codex configuration](https://developers.openai.com/codex/config-basic)
* [OpenAI Codex IDE extension](https://developers.openai.com/codex/ide)
* [AIOAGI 开发者指南](https://aiearthdev.apifox.cn/)