> ## 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.

# macOS

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

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

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

## 准备条件

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

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

  <Card title="OpenAI Codex IDE 扩展" href="https://developers.openai.com/codex/ide">
    查看 Codex 与编辑器集成的官方说明。
  </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="安装命令行工具">
    如果你的系统还没有 Git 或编译工具，先安装 Xcode Command Line Tools：

    ```bash theme={null}
    xcode-select --install
    ```

    安装后执行下面的命令验证 Git：

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

  <Step title="安装 Node.js">
    你可以使用 Node.js 官网安装包、Homebrew 或 `nvm` 安装 Node.js LTS 版本。安装完成后验证：

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

  <Step title="安装 Codex CLI">
    执行下面的命令安装 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">
    在当前 macOS 用户目录下创建或更新 `~/.codex/config.toml`，把 Codex 指向 AIOAGI 的 OpenAI 兼容接口。
  </Step>

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

## AIOAGI 接入配置

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

macOS 默认 shell 通常是 `zsh`。先把 API Key 写入 `~/.zshrc`：

```bash theme={null}
echo 'export OPENAI_API_KEY="sk-your-aioagi-api-key"' >> ~/.zshrc
source ~/.zshrc
```

如果你使用 `bash`，把上面的 `~/.zshrc` 改成 `~/.bashrc` 或 `~/.bash_profile`。

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

```bash theme={null}
mkdir -p ~/.codex
nano ~/.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

如果你不想把 API Key 写入 shell 配置，也可以在 `~/.codex` 下创建 `auth.json`：

```bash theme={null}
mkdir -p ~/.codex
nano ~/.codex/auth.json
```

写入：

```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"
```

不要把包含真实 API Key 的 `~/.zshrc`、`auth.json`、`config.toml` 截图或终端输出提交到公开仓库。

## 启动和验证

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

```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>

## 常见问题

<AccordionGroup>
  <Accordion title="执行 `codex` 提示命令不存在" icon="terminal">
    关闭并重新打开终端。然后执行 `npm prefix -g`，确认全局安装路径是否加入了 `PATH`。如果你使用 `nvm`，请确认当前终端已经加载 `nvm` 配置。
  </Accordion>

  <Accordion title="`npm install -g` 权限不足" icon="lock">
    不建议使用 `sudo npm install -g` 作为长期方案。优先使用 `nvm` 安装 Node.js，或配置用户级 npm 全局目录后再安装 Codex。
  </Accordion>

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

  <Accordion title="配置后仍未生效" icon="gear">
    如果配置后仍未生效，或仍返回 OpenAI 官方接口的认证、验证错误，请先完全关闭并重新打开终端和 VS Code。再执行 `codex` 重新测试。如果仍不生效，请重启当前主机后再测试。问题仍存在时，可以通过微信或 QQ 联系平台管理员协助排查。
  </Accordion>

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

## 使用建议

* 为 Codex 单独创建 API Key，便于统计开发工具用量
* 先用小额度 Token 组完成连通性测试，再切换到正式额度
* 第一次接入时优先测试读取仓库、解释文件和生成简单补丁
* 修改 `~/.zshrc`、`auth.json` 或 `config.toml` 后，重新打开终端和 VS Code
* 模型名、价格和支持策略可能变化，请以控制台和开发者指南为准

## 相关文档

* [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/)