> ## 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를 model provider로 사용하여 실행하세요.

공식 참고 자료:

* [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 앱 또는 Codex CLI를 설치하세요 |
| CometAPI API key | [CometAPI dashboard](https://www.cometapi.com/console/token)에서 발급받으세요                            |
| Model ID         | [Models page](/ko/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는 프로젝트 config 파일의 provider 및 provider-auth 설정을 무시합니다.

권장 설정은 이름이 지정된 `cometapi` provider와 명령 기반 인증을 사용합니다. 이렇게 하면 CometAPI를 내장 OpenAI provider와 분리할 수 있고, 셸 환경 상속이 필요하지 않으며, `~/.codex/auth.json`도 대체하지 않습니다.

<Tabs>
  <Tab title="macOS / Linux / WSL">
    CometAPI API 키를 로컬 키 파일에 저장합니다:

    ```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 키를 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 키를 환경 변수에 유지하려면 `[model_providers.cometapi.auth]` 블록 대신 `env_key`를 사용하세요.

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는 custom provider당 하나의 인증 방법만 지원합니다.
</Warning>

## 설정 스크립트 실행

설정 스크립트는 선택 사항입니다. 이 스크립트는 동일한 `cometapi` provider 구성을 `~/.codex/config.toml`에 작성하고, CometAPI API 키를 `~/.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 키를 명시적으로 전달하세요:

```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 키를 명시적으로 전달하세요:

```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 키 로그인을 관리하도록 하려는 경우에만 `--force-auth-json` 또는 `-ForceAuthJson`을 사용하세요.
</Warning>

## model ID 선택 또는 변경

[Models 페이지](/ko/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"
```

Codex CLI를 `PATH`에서 사용할 수 없다면, Codex 앱을 열고 로컬 프로젝트에서 짧은 프롬프트를 보내세요.

## 문제 해결

<AccordionGroup>
  <Accordion title="Codex가 여전히 기본 OpenAI provider를 사용합니다">
    사용자 수준 `~/.codex/config.toml` 파일에 `model_provider = "cometapi"`가 있는지 확인하세요.
  </Accordion>

  <Accordion title="API 키가 변경되었습니다">
    `~/.codex/cometapi_key`를 업데이트하거나, 업데이트된 `$COMETAPI_KEY` 값으로 설정 스크립트를 다시 실행하세요.
  </Accordion>

  <Accordion title="PowerShell 스크립트가 사전 점검 중 실패합니다">
    수동 Windows 네이티브 PowerShell 단계를 사용한 다음, 검증 명령을 실행하세요.
  </Accordion>

  <Accordion title="파이프된 shell 설정에서 API 키를 묻지 않습니다">
    `--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 ID는 [Models 페이지](/ko/overview/models)에서 확인하세요.
  </Accordion>

  <Accordion title="Windows 설정이 잘못된 환경에 영향을 줍니다">
    Windows 네이티브 모드에서는 `$HOME\.codex`를 편집하고, WSL 에이전트 모드에서는 WSL 내부의 `~/.codex`를 편집하세요.
  </Accordion>

  <Accordion title="ChatGPT 로그인이 변경되었습니다">
    API 키 로그인 모드를 원하지 않는 한 `--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>