> ## 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 quickstart](https://developers.openai.com/codex/quickstart)
* [Codex config basics](https://developers.openai.com/codex/config-basic)
* [Codex custom model providers](https://developers.openai.com/codex/config-advanced#custom-model-providers)
* [Codex Authentication](https://developers.openai.com/codex/auth)
* [Codex on Windows](https://developers.openai.com/codex/windows)

## 先決條件

| Requirement      | Details                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------- |
| OS               | macOS、Linux、Windows 原生 PowerShell，或搭配 WSL 的 Windows                                           |
| Git              | 建議使用 2.23+                                                                                    |
| Codex            | 從 [Codex quickstart](https://developers.openai.com/codex/quickstart) 安裝 Codex app 或 Codex CLI |
| CometAPI API key | 從 [CometAPI dashboard](https://www.cometapi.com/console/token) 取得                             |
| Model ID         | 使用來自 [Models page](/zh-Hant/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 key。
  </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

請使用來自[Models 頁面](/zh-Hant/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 app，並從本機專案送出一個簡短的 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="找不到 model">
    請查看[模型頁面](/zh-Hant/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 設定來將 Codex 設定為使用 CometAPI。",
        "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>