서드파티 API로 쓰는 Claude Desktop: Configure Third-Party Inference 설정과 문제 해결

Wokey Team · 2026-09-24

짧은 답: Claude 데스크톱 앱에서 서드파티 API를 쓰는 방법은 단 하나, Developer → Configure Third-Party Inference입니다. 이 앱은 ANTHROPIC_BASE_URL도 ~/.claude/settings.json도 읽지 않으므로, 터미널에서 잘 되는 설정도 데스크톱 앱에서는 아무 효과가 없습니다. 이 가이드는 사람들이 자주 겪는 문제를 차례로 다룹니다. 메뉴가 보이지 않음, 설정이 적용되지 않음, 모델 목록이 비어 있음, 그리고 서드파티 모드에서는 애초에 쓸 수 없는 기능입니다. 처음부터 설정하는 전체 과정은 Claude Desktop 설정 가이드를 참고하세요.

올바른 순서

1. 데스크톱 앱을 실행하고 Anthropic 계정에 로그인하지 마세요.

2. Help → Troubleshooting → Enable Developer Mode를 엽니다.

3. **Developer → Configure Third-Party Inference…**를 엽니다.

4. Connection에서 Inference provider를 Gateway로 설정한 뒤 Gateway credentials를 입력합니다.

   항목	값
   Gateway base URL	https://api.wokey.ai(/v1 없이)
   Gateway API key	Wokey API 키
   Credential kind	Static API key
   Gateway auth scheme	Bearer(Wokey는 x-api-key도 받으니 기본값 그대로 두세요)

5. Apply Changes를 클릭한 다음 Save & Restart를 클릭합니다.

시스템 요구 사항:

• macOS: 14(Sonoma) 이상, Apple 실리콘 또는 Intel.
• Windows: Windows 10 빌드 19041 이상, x64 또는 Arm64.

Developer 메뉴가 보이지 않음

Developer 메뉴는 개발자 모드를 켠 뒤에만 나타납니다: Help → Troubleshooting → Enable Developer Mode. Help 메뉴에도 이 항목이 없다면 앱을 최신 버전으로 업데이트하세요. 이전 버전에는 서드파티 추론 설정이 없습니다.

설정 창이 읽기 전용임

회사의 MDM 프로필처럼 관리자가 배포한 설정이 이미 컴퓨터에 있다면, 창이 읽기 전용으로 열리며 로컬에서 바꿀 수 없습니다. 관리자에게 문의하거나 관리되지 않는 컴퓨터를 사용하세요.

환경 변수가 효과가 없음

가장 흔한 실수입니다. 데스크톱 앱은 게이트웨이 설정을 서드파티 추론 설정에서만 가져옵니다. ANTHROPIC_BASE_URL도 settings.json도 읽지 않습니다.

데스크톱 앱의 Code 탭도 마찬가지입니다. CLI와 같은 Claude Code 엔진을 실행하지만, 게이트웨이 주소와 자격 증명은 데스크톱 설정에서 바로 가져옵니다. ~/.claude/settings.json의 사용자 수준 설정으로는 이를 덮어쓸 수 없습니다.

반대 방향도 같습니다. 데스크톱 설정은 터미널의 claude에 영향을 주지 않습니다. 각각 따로 설정하세요. 터미널은 Claude Code base URL 가이드를 참고하세요.

모델 목록이 비어 있거나 모델이 빠져 있음

직접 지정한 모델 목록이 없으면 앱은 게이트웨이의 GET /v1/models를 요청하고 ID로 Claude임을 알아볼 수 있는 모델만 남깁니다. 그래서 Wokey에서는 자동 검색으로 claude-opus-5, claude-sonnet-5 같은 모델이 보이고 GPT, Grok 등 다른 모델은 걸러집니다. 정상 동작입니다.

목록을 고정하거나 기본 모델을 고르려면 설정 창의 모델 목록(Model list, 키는 inferenceModels)에 전체 모델 ID를 입력하세요.

• 첫 번째 항목이 기본값이 되며, Code 탭의 새 세션도 이 모델로 시작합니다.
• 모든 항목이 전체 ID이면 앱은 /v1/models 요청을 건너뜁니다.
• /v1/models가 실패하고 목록도 비어 있으면 모델 선택기가 비게 됩니다.

오류

Gateway was unreachable: 앱이 게이트웨이에 연결할 수 없습니다. Gateway base URL에 오타가 없는지 확인한 뒤 터미널에서 curl로 테스트하세요.

curl -X POST https://api.wokey.ai/v1/messages \
  -H "Authorization: Bearer your Wokey API key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

curl은 되는데 앱은 안 된다면 원인은 대개 프록시입니다. 터미널은 프록시를 거치는데 앱은 거치지 않거나, 그 반대입니다.

code가 invalid_api_key인 401: 요청은 Wokey에 도착했지만 키가 없거나 틀렸습니다. Wokey는 두 인증 방식을 모두 받으므로 그 설정은 바꿀 필요가 없습니다. 키를 다시 붙여 넣으세요.

invalid x-api-key: 요청이 Anthropic으로 갔으므로 서드파티 설정이 적용되지 않은 것입니다. 대개 Save & Restart를 클릭하지 않았거나, 그 뒤 로그인 화면에서 Anthropic 로그인을 선택한 경우입니다. invalid x-api-key 가이드를 참고하세요.

더 자세히 보려면: Help → Troubleshooting → Generate Diagnostic Report로 보고서를 내보내세요. 그 안의 파일 세 개가 유용합니다.

• managed-config.txt: 현재 적용된 설정.
• provider-status.txt: 게이트웨이 연결 상태.
• deployment-mode.txt: 현재 모드.

로그 위치:

• macOS: ~/Library/Logs/Claude-3p/main.log
• Windows: %LOCALAPPDATA%\Claude-3p\Logs\main.log

서드파티 모드에서 사용할 수 없는 기능

다음 기능은 Anthropic 계정이나 Anthropic 클라우드 서비스에 의존하므로 게이트웨이에서는 사용할 수 없습니다. 설정 문제가 아닙니다.

• 모바일 및 claude.ai 웹 액세스
• 음성 모드
• 프로젝트와 플러그인 공유
• Claude Design, Claude Security, Claude Tag
• Computer use
• Remote Control과 Anthropic 호스팅 클라우드 환경

두 가지는 기본적으로 꺼져 있습니다.

• 도구 검색과 실험적 베타 기능. 엄격한 게이트웨이와의 호환성을 위해 앱이 이 기능들을 끕니다. 도구 검색은 toolSearchEnabled로 다시 켤 수 있습니다.
• SSH 원격 세션. 서드파티 모드에서는 베타이며, 관리자가 호스트 허용 목록을 설정해야 합니다.

Anthropic 계정으로 돌아가기

로그인 화면에서 Anthropic 로그인 옵션을 선택하면 일반 Claude 데스크톱 앱으로 돌아갑니다.