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

# Codex

> 安装 Codex CLI，配置 aibal.ai 模型服务并验证第一次调用

本教程使用 Codex CLI 的自定义模型提供商配置，把终端中的编程请求发送到 aibal.ai。配置管理界面可参考 [cc-switch](/zh/cc-switch)。

## 操作前准备

* 已[创建 API Key](/zh/create-api-key)，密钥分组提供支持 Responses 的文本模型，余额或额度可用。
* 已准备一个你允许 Codex 读取的项目目录。首次验证可使用空目录。
* 使用 npm 安装时，先安装受支持的 Node.js 与 npm；其他方式见 [Codex 官方安装说明](https://developers.openai.com/codex/cli)。

## 配置步骤

<Steps>
  <Step title="安装并确认命令可用">
    在终端执行：

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

    能显示版本号后继续。若提示找不到命令，重新打开终端，检查 npm 全局命令目录是否在 `PATH` 中。
  </Step>

  <Step title="准备密钥和模型 ID">
    登录 [aibal.ai](https://aibal.ai/)，在 API 密钥列表中打开 **使用密钥**，选择 Codex。复制当前分组支持的文本模型 ID。下面的 `YOUR_AVAILABLE_MODEL_ID` 是占位符，必须替换。
  </Step>

  <Step title="编辑用户级 config.toml">
    打开 `~/.codex/config.toml`；Windows 原生环境对应 `%USERPROFILE%\.codex\config.toml`。如果设置过 `CODEX_HOME`，请使用该目录下的配置。文件不存在时先创建目录和文件，已存在时先备份并合并以下字段。

    ```toml theme={null}
    model_provider = "aibal"
    model = "YOUR_AVAILABLE_MODEL_ID"

    [model_providers.aibal]
    name = "aibal.ai"
    base_url = "https://aibal.ai/v1"
    env_key = "AIBAL_API_KEY"
    wire_api = "responses"
    requires_openai_auth = false
    supports_websockets = false
    ```

    `model_provider` 和 `model` 是顶层字段，放在第一个 `[表名]` 之前；不要重复声明已经存在的同名字段或 `[model_providers.aibal]`。保留你的其他设置。提供商配置应写入用户级文件，不要放到项目仓库的 `.codex/config.toml`。
  </Step>

  <Step title="在启动终端中设置密钥">
    推荐在当前终端隐藏输入密钥，避免把密钥直接写入命令历史。以下 Bash/Zsh 写法会要求你粘贴密钥，输入时不显示字符：

    ```bash theme={null}
    export AIBAL_API_KEY="$(bash -c 'read -r -s -p "aibal.ai API Key: " key; printf "\n" >&2; printf "%s" "$key"')"
    ```

    Windows PowerShell：

    ```powershell theme={null}
    $credential = Get-Credential -UserName "aibal" -Message "Paste your aibal.ai API Key in the password field"
    $env:AIBAL_API_KEY = $credential.GetNetworkCredential().Password
    Remove-Variable credential
    ```

    环境变量只对当前终端及其启动的程序生效。关闭终端后需重新设置，也可由可信的密码管理器注入。不要把真实密钥写入项目文件。
  </Step>

  <Step title="启动新会话并验证">
    在准备好的项目目录执行 `codex`。按提示确认项目信任范围，然后发送：

    ```text theme={null}
    只回复“连接成功”，不要读取或修改文件，不要执行命令。
    ```

    收到正常回答后，回到 aibal.ai 的 **使用记录**，核对这次调用的时间、密钥和模型。测试调用也可能产生费用。
  </Step>
</Steps>

## 配置字段说明

| 字段                     | 含义                                  |
| ---------------------- | ----------------------------------- |
| `model_provider`       | 选择下方定义的 `aibal` 提供商                 |
| `model`                | 当前密钥允许使用的完整文本模型 ID                  |
| `base_url`             | API 基础地址，常用值为 `https://aibal.ai/v1` |
| `env_key`              | 环境变量的名称 `AIBAL_API_KEY`，不是密钥本身      |
| `wire_api`             | Codex 使用的协议，此处必须为 `responses`       |
| `requires_openai_auth` | 本教程用环境变量密钥，设为 `false`               |
| `supports_websockets`  | 此示例使用 HTTP/SSE，设为 `false`           |

<Note>
  如果控制台为你的分组提供模型目录文件或专用地址，请同时按 **使用密钥** 的说明保存目录文件，并使用其给出的完整路径与模型 ID。不要把其他分组的配置混在一起。
</Note>

## 常见问题

### 提示缺少 AIBAL\_API\_KEY

确认你在设置变量的同一个终端启动 `codex`。从 Dock、开始菜单或另一个终端启动的程序不一定继承该变量。本页面向 CLI，不保证桌面应用直接继承终端配置。

### 仍出现 ChatGPT 登录或请求走向其他服务

检查 `model_provider = "aibal"` 是否位于顶层、用户级配置是否生效，以及是否被其他配置管理工具覆盖。不要把本教程的 `env_key` 方式与其他教程的 `auth.json` 登录方式混用。

### 模型未找到或请求报错

把占位模型替换为当前密钥支持的完整 ID。检查该分组是否支持 Responses、Base URL 是否重复带 `/v1`，以及密钥额度。更多错误处理见[接入概览](/zh/integrations)。

### 修改配置后旧会话没有变化

结束旧的 Codex 进程，在配置生效的终端重新启动。若使用 CC Switch，后续在同一个供应商配置中维护，避免手工文件和工具配置来回覆盖。

### 能直接让 Codex 生成图片吗

文本模型接入成功不代表内置图像工具自动使用同一网关。支持客户端图片执行器时，可按[文生图的 Codex 使用说明](/zh/text-to-image)在控制台选择 **API Key Mode**，保存完整配套配置并重启客户端；不要与本页的 `env_key` 片段混用。也可以按该页明确调用图片 API 并保存结果。具体图片工具能力取决于客户端与分组；视频参考[文生视频](/zh/text-to-video)。

## 密钥安全与下一步

不要在提示词、截图、Git 提交或日志中输出 API Key。可以为 Codex 单独设置密钥额度；泄露时在控制台停用旧密钥并替换。

配置依据：[Codex 官方配置参考](https://developers.openai.com/codex/config-reference)与[自定义模型提供商](https://developers.openai.com/codex/config-advanced)。客户端界面可能随版本变化。