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

# Codex CLI

> 将 OpenAI Codex CLI 连接到 AihubMax

## 概述

[Codex CLI](https://github.com/openai/codex) 是 OpenAI 开源的命令行编程代理。它可以读取你的代码库、提出修改建议、执行命令，并根据反馈进行迭代——全部在终端中完成。

通过将 Codex CLI 指向 AihubMax，你可以使用 AihubMax 提供的任意 OpenAI 兼容模型。

<Info>
  Codex CLI 支持通过 `config.toml` 配置文件定义自定义模型提供商，无需修改 Base URL 环境变量即可轻松连接 AihubMax。
</Info>

## 前置条件

<CardGroup cols={2}>
  <Card title="AihubMax API Key" icon="key">
    一个有效的 AihubMax API Key，并确保有权限访问 OpenAI 兼容模型。[前往 AihubMax →](https://api.aihubmax.com/console)
  </Card>

  <Card title="Node.js 22+" icon="node-js">
    Codex CLI 需要 Node.js 22 或更高版本。[下载 Node.js →](https://nodejs.org/zh-cn/download/)
  </Card>
</CardGroup>

## 安装与配置

<Steps>
  <Step title="安装 Codex CLI">
    ```bash theme={null}
    npm install -g @openai/codex
    ```

    验证安装：

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

  <Step title="设置 API Key">
    在配置环境变量前，先前往 [AihubMax 控制台](https://api.aihubmax.com/console) 创建专用密钥：

    1. 打开「API 密钥」页面，点击「创建密钥」。
    2. 密钥名称可自定义，便于区分不同 CLI。
    3. **分组务必选择「Codex」**，这是 Codex CLI 的官方通道，可确保使用 OpenAI 兼容协议以及足够的并发额度。

    <Warning>
      如果没有选择「Codex」分组，Codex CLI 可能无法调用 AihubMax 的 Codex 兼容模型，或出现速率/功能限制。
    </Warning>

    下面两种方式二选一即可：使用 **CC-Switch** 一步到位（自动写入环境变量和 Codex 配置），或通过 **手动配置** 依次设置环境变量并在下一步编辑 `config.toml`。

    Codex CLI 通过 `OPENAI_API_KEY` 环境变量读取认证信息，将其设置为你的 AihubMax API Key：

    <Tabs>
      <Tab title="CC-Switch（推荐）">
        [CC-Switch](https://github.com/farion1231/cc-switch/releases) 可以自动写入 Codex CLI 所需的环境变量：

        1. 根据你的系统[下载并安装](https://github.com/farion1231/cc-switch/releases)最新的 CC-Switch 安装包。
        2. 通过以下**任一方式**将密钥导入 CC-Switch：
           * **一键导入（推荐）**：在 AihubMax 控制台的密钥列表中，点击对应密钥右侧的下拉菜单，选择 **「CC Switch」**，配置会自动导入到 CC-Switch 中。
           * **手动添加**：在 CC-Switch 中手动新增一个「Codex CLI」配置，Base URL 填写 `https://api.aihubmax.com/v1`，并填入你的 API Key。

        ![在 AihubMax 控制台一键导入到 CC-Switch](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260329003930220.png)

        导入后，CC-Switch 会在当前 Shell 会话中注入 `OPENAI_API_KEY`，无需手动编辑配置文件。
      </Tab>

      <Tab title="macOS / Linux">
        在你的 Shell 配置文件（`~/.bashrc`、`~/.zshrc` 等）中添加以下内容：

        ```bash theme={null}
        export OPENAI_API_KEY="sk-your-foxapi-api-key"
        ```

        然后重新加载配置：

        ```bash theme={null}
        source ~/.zshrc  # 或 source ~/.bashrc
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        为当前用户永久设置环境变量：

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

        重启终端使设置生效。
      </Tab>
    </Tabs>
  </Step>

  <Step title="配置 AihubMax 为模型提供商">
    <Tip>
      如果你在上一步选择了 CC-Switch，工具已经帮你写入 `~/.codex/config.toml`，可以直接跳到「开始使用」。仅在手动配置的情况下需要继续本步骤。
    </Tip>

    创建或编辑 Codex CLI 配置文件：

    <Tabs>
      <Tab title="macOS / Linux">
        编辑 `~/.codex/config.toml`：

        ```toml theme={null}
        model = "gpt-4.1"
        model_reasoning_effort = "medium"
        model_provider = "foxapi"

        [model_providers.foxapi]
        name = "AihubMax"
        base_url = "https://api.aihubmax.com/v1"
        env_key = "OPENAI_API_KEY"
        wire_api = "responses"
        ```
      </Tab>

      <Tab title="Windows">
        编辑 `C:\Users\{username}\.codex\config.toml`：

        ```toml theme={null}
        model = "gpt-4.1"
        model_reasoning_effort = "medium"
        model_provider = "foxapi"

        [model_providers.foxapi]
        name = "AihubMax"
        base_url = "https://api.aihubmax.com/v1"
        env_key = "OPENAI_API_KEY"
        wire_api = "responses"
        ```
      </Tab>
    </Tabs>

    <Warning>
      `wire_api` 字段必须设置为 `"responses"`。`"chat"` 选项已弃用，可能导致意外行为。
    </Warning>

    **配置字段说明：**

    | 字段                       | 说明                                           |
    | ------------------------ | -------------------------------------------- |
    | `model`                  | 默认使用的模型（可通过 `--model` 参数覆盖）                  |
    | `model_reasoning_effort` | 推理努力程度：`"low"`、`"medium"` 或 `"high"`         |
    | `model_provider`         | 自定义提供商名称（必须与 `[model_providers.xxx]` 部分名称一致） |
    | `base_url`               | AihubMax 的 API 端点                            |
    | `env_key`                | 存储 API Key 的环境变量名称                           |
    | `wire_api`               | 使用的 API 协议（必须为 `"responses"`）                |
  </Step>

  <Step title="开始使用">
    进入你的项目目录并启动 Codex：

    ```bash theme={null}
    cd /path/to/your/project
    codex
    ```

    或直接运行单次命令：

    ```bash theme={null}
    codex "为注册表单添加输入验证"
    ```
  </Step>
</Steps>

## 验证连接

使用简单的提示测试连接：

```bash theme={null}
codex "请说你好，并确认你正在正常工作"
```

如果配置正确，Codex 将通过 AihubMax 的 API 返回回复。

## 推荐模型

| 模型        | 适用场景               |
| --------- | ------------------ |
| `gpt-4.1` | 复杂的多步骤编程任务（推荐默认选择） |
| `gpt-4o`  | 通用编程任务，速度与质量平衡     |
| `o4-mini` | 快速、经济的编程辅助         |

你可以在启动时通过参数覆盖 `config.toml` 中的默认模型：

```bash theme={null}
codex --model gpt-4o "重构认证模块"
```

## 常见问题

<AccordionGroup>
  <Accordion title="错误：401 Unauthorized">
    * 确认 `OPENAI_API_KEY` 是有效的 AihubMax Key。
    * 确认 Key 未过期且账户余额充足。
    * 如果使用 `config.toml`，确认 `env_key` 字段与你设置的环境变量名称一致（默认为 `OPENAI_API_KEY`）。
  </Accordion>

  <Accordion title="错误：连接失败">
    * 检查 `config.toml` 中的 `base_url` 是否设置为 `https://api.aihubmax.com/v1`（需包含 `/v1`）。
    * 确认你的网络能够访问 `api.aihubmax.com`。
  </Accordion>

  <Accordion title="模型未找到">
    * 确认模型名称正确且在 AihubMax 上可用。
    * 检查你的 AihubMax 账户是否有该模型的访问权限。
  </Accordion>

  <Accordion title="配置文件未生效">
    * 确认文件位于 `~/.codex/config.toml`（macOS/Linux）或 `C:\Users\{username}\.codex\config.toml`（Windows）。
    * 检查 TOML 语法——确保字符串使用引号包裹，section 标题使用方括号。
    * 确认 `model_provider` 的值与 `[model_providers.xxx]` 的 section 名称完全一致。
  </Accordion>
</AccordionGroup>

![](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260331080211773.png)