Codex Desktop

Codex Desktop은 CC Switch 원클릭 가져오기로 HiAPI에 연결할 수 있습니다. 아래 단계는 gpt-6-astra를 예로 사용하며, HiAPI는 OpenAI Responses 프로토콜을 사용합니다. 모든 과정을 그래픽 인터페이스에서 진행합니다. Node.js 설치도, 명령도, 설정 파일 편집도 필요 없습니다.

1. Codex Desktop 설치

1. OpenAI 공식 데스크톱 시작 페이지를 열고 Desktop app 다운로드 항목을 선택합니다. Mac에서는 공식 Codex.dmg를 사용하세요. 공식 페이지에 나온 시스템 및 칩 요구 사항이 적용됩니다.

2. Finder → Downloads를 열고 .dmg를 더블클릭해 앱을 Applications로 끌어다 놓습니다. 복사가 끝나면 Applications에서 열고, 시스템이 물으면 공식 출처인지 확인한 뒤 Open을 클릭하세요.

3. 첫 실행이 로그인 페이지에서 멈춘다면 그대로 두고 CC Switch 설치, HiAPI 가져오기와 활성화를 계속하세요. ChatGPT에 한 번 로그인했다가 로그아웃할 필요가 없습니다.

Windows: 공식 페이지에서 Windows 설치 파일을 선택하고 설치를 마친 뒤 시작 메뉴에서 앱을 엽니다. Mac용 DMG는 사용하지 마세요.

2. CC Switch 설치 및 열기

CC Switch 설치 및 원클릭 가져오기에 설명된 대로 CC Switch를 내려받아 설치하고 엽니다. 이미 있다면 열기만 하세요.

이미 공급자가 있다면 먼저 Codex 페이지에서 “In use”로 표시된 카드의 이름을 기록해 두고, 필요할 때 기존 설정 백업에 설명된 대로 SQL 백업을 내보내세요.

3. HiAPI API 키 선택

API 키 발급받기에 설명된 대로 키를 선택하거나 만들고 이름을 기록하세요. 여기서는 키를 복사할 필요가 없습니다. 가져오기가 키를 함께 전달합니다.

4. 웹에서 원클릭 가져오기 준비

1. HiAPI Codex 연결 페이지를 열고 API Key setup → Codex → Desktop → gpt-6-astra → macOS를 선택합니다. Windows에서는 시스템으로 Windows를 선택하세요.

① API Key setup을 선택합니다. ② Codex를 선택합니다. ③ Desktop을 선택합니다. ④ gpt-6-astra를 선택합니다. ⑤ 시스템으로 macOS를 선택합니다(Windows에서는 Windows 선택). ⑥ Import to CC Switch를 클릭합니다.

2. Import to CC Switch를 클릭하고 API Key 드롭다운에서 기록한 키 이름을 고른 뒤, 하단에 **Responses API · https://api.hiapi.ai/v1**이 표시되는지 확인합니다.
3. Prepare import를 클릭한 다음 Open CC Switch를 클릭하고, 브라우저가 물으면 허용합니다.

각 단계의 스크린샷은 연결 페이지에서 가져오기 준비에 있습니다.

5. CC Switch에서 가져오기 확인

“Confirm provider import” 창에서 아래 항목을 확인하고 Switch to this provider immediately after import를 끈 상태로 두었다가 Import를 클릭합니다:

항목	예상 값
App type	Codex
Provider name	HiAPI - gpt-6-astra
API endpoint	https://api.hiapi.ai/v1
Model	gpt-6-astra
API key	입력되어 있고 가려짐

CC Switch의 Codex 페이지로 돌아왔을 때 HiAPI - gpt-6-astra 카드가 있으면 가져오기가 성공한 것입니다(아직 활성화되지는 않음). 스크린샷은 CC Switch에서 가져오기 확인을 참고하세요.

6. HiAPI 활성화

1. 먼저 Codex에서 실행 중인 작업이 끝날 때까지 기다리세요. CC Switch의 Codex → Direct 페이지에서 HiAPI - gpt-6-astra 카드의 Switch / Enable 버튼을 클릭합니다. 카드에 “In use”가 표시되어야 HiAPI가 활성화된 것입니다. 스크린샷은 HiAPI 활성화를 참고하세요.
2. 새 설정이 적용되도록 Codex를 완전히 종료했다가 다시 엽니다. CLI와 Desktop은 로컬 Codex 설정을 공유할 수 있습니다. 나중에 원래 공급자로 돌아가려면 여기서 해당 카드로 전환하고 클라이언트를 다시 여세요.

7. 클라이언트 다시 열기 및 필요 시 로그인

1. 실행 중인 작업이 끝날 때까지 기다린 뒤, Mac에서는 앱 메뉴의 Quit을 클릭하거나 ⌘Q를 누르고 Applications에서 앱을 다시 엽니다. 창만 닫으면 종료되지 않습니다. Windows에서도 앱 메뉴에서 종료한 뒤 시작 메뉴에서 다시 여세요.

2. 바로 메인 인터페이스로 넘어가면 다음 단계를 계속하세요. API 키 로그인 항목이 나타나면 Sign in another way를 클릭한 다음, HiAPI 콘솔 → API Keys로 이동해 앞에서 선택한 키를 찾고 옆의 복사 아이콘을 클릭해 전체 HiAPI API 키를 복사하세요.

3. 클라이언트로 돌아와 API Key 입력란에 HiAPI API 키를 붙여 넣고 Continue를 클릭합니다. 채팅 입력란에 붙여 넣지 말고, 이름이나 마스킹된 표시 값을 복사하지 마세요. 버전마다 문구가 다를 수 있으니 API 키 로그인 항목을 기준으로 하고, 설정 파일은 편집할 필요가 없습니다.

8. 로컬 폴더 열기, 모델 선택 후 시작

1. Mac에서는 Finder 메뉴에서 Go → Home을 클릭하고, ⌘⇧N을 눌러 hiapi-project라는 폴더를 만든 뒤 Enter를 눌러 확인합니다. 기존 프로젝트 폴더를 사용해도 됩니다.

   Windows에서는 파일 탐색기에서 사용자 디렉터리를 열고 빈 영역을 마우스 오른쪽 버튼으로 클릭해 New → Folder를 선택한 뒤 hiapi-project라고 이름을 지정합니다.

2. 클라이언트에서 New chat / New task를 클릭하고 Codex를 입력해 Local 작업 모드를 선택합니다. Open / Add folder를 클릭하고, Mac 파일 선택 창에서는 ⌘⇧G를 눌러 ~/hiapi-project를 입력한 뒤 Enter를 누르고 Open / Select folder를 클릭하세요. Windows에서는 방금 만든 폴더를 선택합니다.

3. 이 폴더에서 새 채팅을 시작하고 입력 상자 옆의 모델 선택기를 열어 GPT-6 Astra / gpt-6-astra를 선택합니다. 버전에 따라 Codex가 제품 메뉴나 별도 프로젝트 영역에 있을 수 있습니다. 모드가 로컬이고 폴더와 모델이 맞으면 됩니다.

4. 실행 전 확인 권한은 기본값으로 유지하세요. “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내세요. 정상적으로 답하면 연결이 된 것입니다. HiAPI 콘솔의 요청 로그에 이 요청이 보이면 HiAPI를 거쳐 가는 것입니다. 이후에는 하고 싶은 작업을 적으면 됩니다.

문제 해결

여기에는 Codex Desktop에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.

증상	원인	해결 방법
다시 열어도 ChatGPT 로그인 페이지에 머묾	데스크톱 앱이 API 키 로그인을 요구함	Sign in another way를 클릭하고 HiAPI API 키를 붙여 넣으세요. 7단계 참고
모델 선택기에 gpt-6-astra가 없음	HiAPI 카드가 활성화되지 않았거나 클라이언트를 완전히 종료하지 않음	CC Switch의 Codex 페이지에서 HiAPI 카드에 “In use”가 표시되는지 확인한 뒤 ⌘Q로 완전히 종료하고 다시 여세요
명령줄 Codex도 함께 바뀜	둘이 로컬 Codex 설정을 공유함	정상 동작입니다. 원래 공급자로 돌아가려면 CC Switch에서 해당 카드로 전환하세요