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

# Codex Desktop

> GravitexAI로 Codex 데스크톱을 설정하고 모델 연결 및 로컬 도구 호출 확인하기

## 1. 사전 준비

이 가이드는 **macOS 및 Windows**의 Codex 데스크톱 인터페이스를 다룹니다. 운영체제에 맞는 클라이언트를 설치하고 Codex 화면이 열리는지 확인하세요. 배포판에 따라 설치 경로와 화면이 다를 수 있습니다. 터미널 사용법은 [Codex CLI 가이드](https://docs.gravitex.ai/ko/integrations/codex.md)를 참고하세요.

* Codex 인터페이스를 정상적으로 열 수 있는 앱이 설치되어 있어야 합니다.
* [GravitexAI 계정](https://maas.gravitex.ai)에 충분한 잔액이 있어야 합니다.
* [API 키](https://maas.gravitex.ai/#/keys)의 그룹이 대상 GPT 모델과 Responses API를 지원해야 합니다.

다음 내장 CLI 경로가 있는 설치에서는 선택적으로 버전을 확인할 수 있습니다.

```bash theme={null}
ls /Applications/ChatGPT.app
/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex --version
```

경로가 없다면 실제 설치 위치를 확인하세요.

Windows에서는 앱의 정보 또는 설정 화면에서 버전을 확인하세요. 위 명령은 macOS 전용입니다.

## 2. API 키와 모델 권한 확인

아래 키를 본인의 키로 바꾸세요. `gpt-6.1-sol`은 예시이며, [모델 카탈로그](https://maas.gravitex.ai/#/models)와 키 그룹에서 실제로 사용 가능한 모델 ID를 사용하세요.

> [tab] macOS
>
> ```bash theme={null}
> curl https://api.gravitex.ai/v1/responses \
>   -H "Authorization: Bearer sk-your-gravitex-key" \
>   -H "Content-Type: application/json" \
>   -d '{"model":"gpt-6.1-sol","input":"say ok"}'
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $headers = @{ Authorization = "Bearer sk-your-gravitex-key" }
> $body = @{ model = "gpt-6.1-sol"; input = "say ok" } | ConvertTo-Json
> Invoke-RestMethod -Uri "https://api.gravitex.ai/v1/responses" -Method Post -Headers $headers -ContentType "application/json" -Body $body
> ```

| 응답 | 처리 방법 |
| - | - |
| `"status": "completed"` | 기본 호출 성공, 다음 단계 진행 |
| `503` / `No available channel` | 모델 권한 및 채널 가용성 확인 |
| `404` / `endpoint_not_found` | 주소 및 그룹의 Responses API 지원 여부 확인 |
| `401` / `invalid api key` | 키 유효성, 불필요한 공백과 줄바꿈 확인 |

> [!NOTE]
>
> 이 테스트는 소량의 API 사용량을 발생시킵니다. 기본 연결만 확인하므로 데스크톱 도구 호출은 별도로 검증하세요.

## 3. 공급자 설정

두 운영체제는 동일한 TOML 설정을 사용합니다.

| 운영체제 | 기본 사용자 설정 경로 |
| - | - |
| macOS | `~/.codex/config.toml` |
| Windows 네이티브 클라이언트 | `%USERPROFILE%\.codex\config.toml` (일반적으로 `C:\Users\사용자명\.codex\config.toml`) |

`CODEX_HOME`이 설정되어 있다면 해당 디렉터리의 `config.toml`을 편집하세요. Windows에서는 **Win + R**을 누르고 `%USERPROFILE%\.codex`를 입력해 기본 폴더를 열 수 있습니다. 이 가이드는 Windows 네이티브 클라이언트용이며, WSL의 `~/.codex`는 일반적으로 별도 디렉터리입니다.

기존 설정을 백업한 뒤 편집하세요.

> [tab] macOS
>
> ```bash theme={null}
> mkdir -p ~/.codex
> if [ -f ~/.codex/config.toml ]; then
>   cp ~/.codex/config.toml ~/.codex/config.toml.backup-$(date +%Y%m%d-%H%M%S)
> fi
> nano ~/.codex/config.toml
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> $codexConfigDir = Join-Path $env:USERPROFILE ".codex"
> if ($env:CODEX_HOME) { $codexConfigDir = $env:CODEX_HOME }
> New-Item -ItemType Directory -Path $codexConfigDir -Force | Out-Null
> $codexConfigPath = Join-Path $codexConfigDir "config.toml"
> if (Test-Path $codexConfigPath) {
>   Copy-Item $codexConfigPath "$codexConfigPath.backup-$(Get-Date -Format yyyyMMdd-HHmmss)"
> } else {
>   New-Item -ItemType File -Path $codexConfigPath | Out-Null
> }
> notepad $codexConfigPath
> ```

다음 설정을 병합하고 키를 교체하세요. 같은 필드나 테이블이 있다면 기존 위치를 수정하고 중복 정의하지 마세요.

```toml theme={null}
model = "gpt-6.1-sol"
model_provider = "gravitex"
model_reasoning_effort = "medium"

[model_providers.gravitex]
name = "GravitexAI"
base_url = "https://api.gravitex.ai/v1"
wire_api = "responses"

[model_providers.gravitex.http_headers]
Authorization = "Bearer sk-your-gravitex-key"
Content-Type = "application/json"
```

| 필드 | 작성 규칙 |
| - | - |
| `model` | API 테스트에 성공한 GPT 모델 ID 사용 |
| `model_provider` | 공급자 테이블 이름의 `gravitex`와 일치 |
| `base_url` | `https://api.gravitex.ai/v1` 사용, `/responses` 추가 금지 |
| `wire_api` | `responses` 사용 |
| `Authorization` | `Bearer` 뒤 공백 하나, 키는 한 줄로 작성 |

> [!TIP]
>
> `model` 등의 최상위 필드는 첫 번째 TOML 테이블 앞에 배치하세요. `Authorization`은 `http_headers` 테이블에 속해야 합니다. 이 테이블이 파일의 마지막에 있을 필요는 없습니다. 새로운 `[테이블]` 헤더 이후의 필드는 해당 테이블에 속합니다.

> [!NOTE]
>
> 정적 헤더를 사용하면 키가 로컬 설정 파일에 평문으로 저장됩니다. 공급자의 `env_key`도 사용할 수 있지만 Finder나 Launchpad에서 실행한 앱은 일반적으로 터미널에서 임시로 export한 변수를 상속하지 않습니다. 앱 프로세스가 변수를 읽을 수 있는지 먼저 확인하세요. Windows의 `$env:변수명`도 현재 PowerShell과 자식 프로세스에만 적용됩니다. 시작 메뉴에서 실행한 앱은 해당 세션의 임시 변수를 자동으로 상속하지 않습니다.

저장 후 Codex를 제공하는 앱을 완전히 종료하세요.

* **macOS**: **Command + Q**를 사용하세요.
* **Windows**: 앱 메뉴의 종료 명령을 사용하고 시스템 트레이에 남아 있다면 트레이 메뉴에서도 종료하세요. 필요하면 작업을 저장한 뒤 작업 관리자에서 해당 앱과 남은 Codex 프로세스를 종료하고 시작 메뉴에서 다시 여세요.

다시 연 뒤 새 로컬 채팅을 시작하세요. 창만 닫으면 백그라운드 프로세스가 남을 수 있습니다.

## 4. CC Switch로 연결

macOS와 Windows 모두 먼저 API 키를 검증하고 Codex 설정을 백업하세요.

1. [CC Switch 가이드](https://docs.gravitex.ai/ko/integrations/cc-switch.md)에 따라 설치하고 **Codex** 페이지에서 GravitexAI 공급자를 추가하세요.

2. API 키, Base URL `https://api.gravitex.ai/v1`, 검증된 GPT 모델 ID(예: `gpt-6.1-sol`)를 입력하세요. 프로토콜 선택 항목이 있다면 **Responses**를 선택하세요.

   ![CC Switch Codex 공급자의 API 주소 및 모델 목록 설정](https://mintcdn.com/gravitexai/r6k6xZ-OnsQI5bKV/images/codex-desktop-cc-switch.png?fit=max\&auto=format\&n=r6k6xZ-OnsQI5bKV\&q=85\&s=d2d0ec20ceecb5c4c3c1bcfd0ad63e16)

3. 저장 후 현재 공급자로 전환하세요. `CODEX_HOME`을 포함해 데스크톱 앱과 같은 사용자 설정 디렉터리에 기록되는지 확인하세요.

4. Codex Desktop을 완전히 종료하고 다시 연 뒤 아래 절차로 채팅과 도구를 검증하세요.

> [!NOTE]
>
> 이 절차는 공급자 전환 방식입니다. 로컬 라우팅이나 집계 모드는 CC Switch의 지속 실행이 필요할 수 있습니다. 집계 모델 목록을 바꾸면 Codex를 재시작하세요. 되돌리려면 이전 공급자로 전환하거나 Codex 종료 후 백업을 복원하세요.

## 5. Magpie로 연결

요청 경로는 **Codex Desktop → 로컬 Magpie → GravitexAI**입니다. 두 운영체제 모두 게이트웨이를 실행 상태로 유지하세요.

1. [Magpie 가이드](https://docs.gravitex.ai/ko/integrations/magpie.md)에 따라 설치하고 `gravitex` 공급자에 GravitexAI 키 및 Responses 기본 주소 `https://api.gravitex.ai/v1`을 설정하세요.

   ![Magpie GravitexAI 공급자의 OpenAI Responses 주소 설정](https://mintcdn.com/gravitexai/r6k6xZ-OnsQI5bKV/images/codex-desktop-magpie.png?fit=max\&auto=format\&n=r6k6xZ-OnsQI5bKV\&q=85\&s=556bf6b7a49daa3cfbd4c5d7e92df96b)

   스크린샷의 공급자 ID는 `gravitexai`이고 아래 명령은 `gravitex`를 사용합니다. 스크린샷과 같은 ID를 사용한다면 명령도 바꾸세요. 예: `magpie codex gravitexai/gpt-6.1-sol`.

2. Codex Desktop을 완전히 종료하고 설정을 백업하세요.

3. 아래 명령에서 공급자 및 모델 ID를 실제 사용 가능한 값으로 바꾸어 실행하세요.

> [tab] macOS
>
> ```bash theme={null}
> magpie ls
> magpie provider set gravitex responses=https://api.gravitex.ai/v1
> magpie codex gravitex/gpt-6.1-sol
> ```

> [tab] Windows PowerShell
>
> ```powershell theme={null}
> magpie.exe ls
> magpie.exe provider set gravitex responses=https://api.gravitex.ai/v1
> magpie.exe codex gravitex/gpt-6.1-sol
> ```
>
> PATH에 없다면 실제 실행 파일 경로를 사용하세요. 공백이 있는 경로는 `& "C:\actual path\magpie.exe"`처럼 호출하세요.

4. 또는 Magpie의 **Agent** 페이지에서 **Codex** 연결을 활성화하고 GravitexAI 모델을 선택하세요. 데스크톱 앱이 사용하는 Codex 디렉터리와 일치하는지 확인하세요.
5. Magpie를 실행한 상태로 Codex Desktop을 다시 열고 채팅과 도구를 검증하세요. 연결 실패 시 기본 게이트웨이 포트 `3425`, 로컬호스트 프록시 및 상위 공급자 권한을 확인하세요.

> [!TIP]
>
> 직접 연결로 돌아가려면 Magpie에서 Codex 연결을 해제하고 이전 설정을 복원하거나 CC Switch에서 공급자를 선택한 뒤 Codex를 완전히 재시작하세요. 같은 설정을 두 관리 도구가 동시에 관리하지 않도록 하세요. 로컬 게이트웨이 인증 정보와 GravitexAI 키는 용도가 다릅니다.

## 6. 연결 확인

1. 로컬 프로젝트를 열고 새 채팅을 만드세요. 모델 또는 공급자를 확인하세요. 버전에 따라 `Custom`으로 표시될 수 있으며 표시 이름만으로 연결을 판단하지 마세요.
2. `hello`를 보내 정상 응답을 확인하세요.
3. “현재 디렉터리의 파일을 나열해 줘”라고 요청하세요. 파일 또는 터미널 도구가 실행되고 결과를 바탕으로 답변하는지 확인하세요. 필요한 로컬 권한을 허용하세요.
4. GravitexAI 콘솔에서 해당 요청의 모델 및 사용량을 확인하세요.

## 7. 문제 해결

| 증상 | 확인 사항 |
| - | - |
| 공식 계정 로그인 요구 | 실제 설정 경로, 공급자 이름, 완전한 재시작 확인. 일부 기능은 공식 로그인 필요 가능 |
| `401` | 키, `Bearer` 뒤 공백, TOML 테이블 위치 확인 |
| `404` | 기본 URL 및 그룹의 Responses API 지원 확인 |
| 모델 사용 불가 | 모델 ID, 그룹 권한, 채널 상태 확인 후 curl 재시험 |
| `400` | 오류에 표시된 매개변수 확인. `service_tier` 미지원 오류이면 해당 필드 제거 |
| 변경 미적용 | 완전히 재시작하고 프로젝트 및 프로필의 덮어쓰기 확인 |
| 채팅은 되지만 도구 실패 | 로컬 권한, 클라이언트 버전 및 모델·채널의 도구 호환성 확인 |
| Windows 명령 또는 매개변수 오류 | PowerShell에서 Windows 탭의 명령을 실행하세요. Bash의 역슬래시 줄 연결을 붙여 넣지 마세요 |
| Windows 설정 파일 누락 또는 미적용 | 파일명이 `config.toml.txt`가 아닌 `config.toml`인지, `CODEX_HOME` 및 별도 WSL 설정을 잘못 수정했는지 확인하세요 |

## 8. 선택 설정 및 주의 사항

* 모델 변경 시 최상위 `model`을 수정하고 사용 권한을 검증한 뒤 재시작하세요.
* 모델이 지원하는 범위에서 `model_reasoning_effort`를 `low`, `medium`, `high`로 설정하세요. 높은 강도는 보통 시간과 토큰을 더 사용하며 더 나은 결과를 보장하지 않습니다.
* 원래 설정은 백업으로 복원하세요. 공식 공급자로 돌아가려면 최상위 `model_provider = "openai"`와 공식 계정에서 사용 가능한 모델을 설정하고 재시작 후 로그인하세요.
* 키를 저장소나 공개 스크린샷에 포함하지 마세요. 유출 시 즉시 폐기하고 재발급하세요.
* 클라우드 작업과 플러그인 등의 기능은 클라이언트, 계정 및 공급자 지원에 따라 달라집니다.

## 9. 참고 자료

* [Codex CLI 가이드](https://docs.gravitex.ai/ko/integrations/codex.md)

* [GravitexAI API 키](https://maas.gravitex.ai/#/keys)

* [GravitexAI 모델 카탈로그](https://maas.gravitex.ai/#/models)

* [OpenAI 설정 참고 문서](https://learn.chatgpt.com/docs/config-file/config-reference)

* [Windows desktop configuration](https://learn.chatgpt.com/docs/windows/windows-app)

* [CC Switch documentation](https://github.com/farion1231/cc-switch)

* [Magpie reference](https://github.com/yetone/magpie/blob/main/docs/reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.