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

# 使用 CometAPI 配置 Codex

> 通过编辑用户级 `config.toml` provider 设置，使用本指南将 Codex 配置为通过 CometAPI 运行。

使用本指南将 [Codex](https://developers.openai.com/codex/quickstart) 与 CometAPI 一起作为模型提供方运行。

官方参考：

* [Codex 快速开始](https://developers.openai.com/codex/quickstart)
* [Codex 配置基础](https://developers.openai.com/codex/config-basic)
* [Codex 自定义模型提供方](https://developers.openai.com/codex/config-advanced#custom-model-providers)
* [Codex 身份验证](https://developers.openai.com/codex/auth)
* [Windows 上的 Codex](https://developers.openai.com/codex/windows)

## 前置条件

| 要求              | 详情                                                                                     |
| --------------- | -------------------------------------------------------------------------------------- |
| 操作系统            | macOS、Linux、原生 Windows PowerShell，或带 WSL 的 Windows                                     |
| Git             | 推荐 2.23+                                                                               |
| Codex           | 按照 [Codex 快速开始](https://developers.openai.com/codex/quickstart) 安装 Codex 应用或 Codex CLI |
| CometAPI API 密钥 | 从 [CometAPI 控制台](https://www.cometapi.com/console/token) 获取                            |
| Model ID        | 使用来自 [模型页面](/zh-Hans/overview/models) 的 model ID                                       |

## 选择一种设置方式

我们提供两种选项，帮助你快速配置 Codex。

<CardGroup cols={2}>
  <Card title="选项 1：手动配置 Codex（推荐）" icon="bolt" href="#configure-codex-manually">
    直接编辑用户级 `~/.codex/config.toml` 文件。这是最可靠的方式，尤其适合 Windows 和 WSL 用户。
  </Card>

  <Card title="选项 2：通过脚本配置" icon="puzzle-piece" href="#run-the-setup-script">
    运行设置脚本作为快捷方式。它会写入相同的 provider 配置，并为 Codex 存储 CometAPI API 密钥。
  </Card>
</CardGroup>

## 手动配置 Codex

Codex 会从用户级别的 `~/.codex/config.toml` 文件读取个人 provider 默认设置。请在这里配置 CometAPI provider，而不是在项目的 `.codex/config.toml` 文件中配置。Codex 会忽略项目配置文件中的 provider 和 provider-auth 设置。

推荐的设置方式是使用命名的 `cometapi` provider 和基于命令的身份验证。这样可以让 CometAPI 与内置的 OpenAI provider 保持分离，不需要继承 shell 环境变量，也不会替换 `~/.codex/auth.json`。

<Tabs>
  <Tab title="macOS / Linux / WSL">
    将你的 CometAPI API key 存储到本地 key 文件中：

    ```bash theme={null}
    mkdir -p "$HOME/.codex"
    printf "%s\n" "$COMETAPI_KEY" > "$HOME/.codex/cometapi_key"
    chmod 600 "$HOME/.codex/cometapi_key"
    ```

    将以下配置添加到 `~/.codex/config.toml`：

    ```toml theme={null}
    model_provider = "cometapi"
    model = "your-model-id"

    [model_providers.cometapi]
    name = "CometAPI"
    base_url = "https://api.cometapi.com/v1"
    wire_api = "responses"

    [model_providers.cometapi.auth]
    command = "sh"
    args = ["-c", "cat \"$HOME/.codex/cometapi_key\""]
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    将你的 CometAPI API key 存储到 Windows Codex 主目录中：

    ```powershell theme={null}
    New-Item -ItemType Directory -Force "$HOME\.codex" | Out-Null
    Set-Content -NoNewline -Path "$HOME\.codex\cometapi_key" -Value $env:COMETAPI_KEY
    ```

    将以下配置添加到 `$HOME\.codex\config.toml`：

    ```toml theme={null}
    model_provider = "cometapi"
    model = "your-model-id"

    [model_providers.cometapi]
    name = "CometAPI"
    base_url = "https://api.cometapi.com/v1"
    wire_api = "responses"

    [model_providers.cometapi.auth]
    command = "powershell.exe"
    args = [
      "-NoProfile",
      "-Command",
      "$p=Join-Path $HOME '.codex/cometapi_key'; (Get-Content -Raw $p).Trim()",
    ]
    ```
  </Tab>
</Tabs>

<Note>
  Windows 原生 Codex 使用 `$HOME\.codex`，通常是 `C:\Users\<user>\.codex`。WSL 使用 Linux 发行版的 `~/.codex`。请编辑与 Codex agent 运行环境对应的目录。
</Note>

## 使用环境变量身份验证

如果你更倾向于将 CometAPI API key 保存在环境变量中，请使用 `env_key`，而不是 `[model_providers.cometapi.auth]` 块。

仅当启动 Codex 的环境中可用 `COMETAPI_KEY` 时，才使用以下 provider 配置：

```toml theme={null}
model_provider = "cometapi"
model = "your-model-id"

[model_providers.cometapi]
name = "CometAPI"
base_url = "https://api.cometapi.com/v1"
wire_api = "responses"
env_key = "COMETAPI_KEY"
```

<Warning>
  不要将 `env_key` 与 `[model_providers.cometapi.auth]` 组合使用。Codex 对每个自定义 provider 只支持一种身份验证方式。
</Warning>

## 运行设置脚本

设置脚本是可选的。它会将相同的 `cometapi` provider 配置写入 `~/.codex/config.toml`，将你的 CometAPI API key 存储在 `~/.codex/cometapi_key` 中，在修改文件前创建备份，并在 Codex CLI 可用时通过 `codex exec` 验证配置。

对于 macOS、Linux 或 WSL，请运行交互式安装程序：

```bash theme={null}
sh -c "$(curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh)"
```

对于非交互式设置，请显式传入 API key：

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh | sh -s -- --key "$COMETAPI_KEY"
```

对于 Windows 原生 PowerShell，请运行交互式安装程序：

```powershell theme={null}
powershell -c "irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1' | iex"
```

对于非交互式 Windows 设置，请显式传入 API key：

```powershell theme={null}
powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1'))) -Key $env:COMETAPI_KEY"
```

<Warning>
  默认情况下，脚本不会替换 `~/.codex/auth.json`，也不会移除 ChatGPT 登录。仅当你希望脚本通过 `auth.json` 管理 Codex API-key 登录时，才使用 `--force-auth-json` 或 `-ForceAuthJson`。
</Warning>

## 选择或更改 model ID

使用[模型页面](/zh-Hans/overview/models)中的 model ID。在手动配置中，修改 `~/.codex/config.toml` 里的 `model` 值。

对于 macOS、Linux 或 WSL，请在运行设置脚本时传入 `--model`：

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.sh | sh -s -- --key "$COMETAPI_KEY" --model your-model-id
```

对于 Windows 原生 PowerShell，请在运行设置脚本时传入 `-Model`：

```powershell theme={null}
powershell -c "& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/cometapi-dev/integrations/main/codex/setup.ps1'))) -Key $env:COMETAPI_KEY -Model 'your-model-id'"
```

<Note>
  设置了 `CODEX_HOME` 时，脚本会使用它。否则会写入当前环境的 `~/.codex`。
</Note>

## 验证设置

要使用 Codex CLI 验证设置，请在任意本地项目中运行以下只读命令：

```bash theme={null}
codex exec --ephemeral --skip-git-repo-check --sandbox read-only --color never "Reply exactly with: COMETAPI_CODEX_OK"
```

如果 `PATH` 中没有可用的 Codex CLI，请打开 Codex 应用，并在本地项目中发送一个简短的 Prompt。

## 故障排查

<AccordionGroup>
  <Accordion title="Codex 仍然使用默认的 OpenAI 提供商">
    确认用户级 `~/.codex/config.toml` 文件中包含 `model_provider = "cometapi"`。
  </Accordion>

  <Accordion title="API key 已更改">
    更新 `~/.codex/cometapi_key`，或使用更新后的 `$COMETAPI_KEY` 值重新运行设置脚本。
  </Accordion>

  <Accordion title="PowerShell 脚本在预检期间失败">
    使用手动的 Windows 原生 PowerShell 步骤，然后运行验证命令。
  </Accordion>

  <Accordion title="通过管道执行的 shell 设置没有要求提供 API key">
    使用 `--key "$COMETAPI_KEY"`、设置 `COMETAPI_KEY`，或运行交互式 `sh -c "$(curl ...)"` 命令。
  </Accordion>

  <Accordion title="连接超时或使用了错误的 base URL">
    确认 `~/.codex/config.toml` 中的 `base_url` 为 `https://api.cometapi.com/v1`。
  </Accordion>

  <Accordion title="找不到模型">
    查看[模型页面](/zh-Hans/overview/models)以获取可用的 model ID。
  </Accordion>

  <Accordion title="Windows 设置影响了错误的环境">
    在 Windows 原生模式下编辑 `$HOME\.codex`，或在 WSL agent 模式下编辑 WSL 内的 `~/.codex`。
  </Accordion>

  <Accordion title="ChatGPT 登录方式已更改">
    除非你想使用 API-key 登录模式，否则不要使用 `--force-auth-json` 或 `-ForceAuthJson`。
  </Accordion>
</AccordionGroup>

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/codex#howto",
        "name": "使用 CometAPI 配置 Codex",
        "description": "使用本指南通过编辑用户级 config.toml 中的 provider 设置来配置搭配 CometAPI 使用的 Codex。",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/codex#step-1",
            "position": 1,
            "name": "查看前置条件",
            "text": "完成“使用 CometAPI 配置 Codex”指南中的“查看前置条件”步骤。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/codex#step-2",
            "position": 2,
            "name": "选择一种设置路径",
            "text": "完成“使用 CometAPI 配置 Codex”指南中的“选择一种设置路径”步骤。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/codex#step-3",
            "position": 3,
            "name": "手动配置 Codex",
            "text": "完成“使用 CometAPI 配置 Codex”指南中的“手动配置 Codex”步骤。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/codex#step-4",
            "position": 4,
            "name": "使用环境变量认证",
            "text": "完成“使用 CometAPI 配置 Codex”指南中的“使用环境变量认证”步骤。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/codex#step-5",
            "position": 5,
            "name": "运行设置脚本",
            "text": "完成“使用 CometAPI 配置 Codex”指南中的“运行设置脚本”步骤。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/codex#step-6",
            "position": 6,
            "name": "选择或更改 model ID",
            "text": "完成“使用 CometAPI 配置 Codex”指南中的“选择或更改 model ID”步骤。"
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/codex#step-7",
            "position": 7,
            "name": "验证设置",
            "text": "完成“使用 CometAPI 配置 Codex”指南中的“验证设置”步骤。"
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "CometAPI 文档",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "集成",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "使用 CometAPI 配置 Codex",
            "item": "https://apidoc.cometapi.com/integrations/codex"
          }
        ]
      }
    ]
    }
    `}
</script>