Claude Desktop

Claude Desktop: SSL 및 로딩 오류 해결

CC Switch의 로컬 라우팅과 Needs model mapping을 확인해 Claude Desktop의 무응답 및 SSL 인증서 만료 오류를 해결하세요.

Claude Desktop이 이미 API에 연결되어 있지만 정상 response를 반환하지 않거나 다음과 같은 error를 표시한다면:

API Error: Unable to connect to API: SSL certificate has expired

이것이 항상 API Key가 invalid하다는 뜻은 아니며 server certificate가 실제로 expired되었다는 뜻도 아닙니다. user reports에 따르면 Claude Desktop은 proxy networks, restricted networks 또는 strict certificate inspection environments에서 third-party API Gateway에 직접 연결할 때 실패할 수 있습니다.

CC Switch Claude Desktop local routing을 사용하고 Needs model mapping을 enable하세요. Claude Desktop이 먼저 local address에 연결하고 CC Switch가 request를 BetterToken으로 forward합니다.

Claude Desktop에 API Error: Unable to connect to API: SSL certificate has expired가 표시됩니다.

사용할 시점

Claude Desktop이 API에 연결되었지만 messages가 response를 반환하지 않음
page에 SSL certificate has expired가 표시됨
Chat page가 response를 시작하는 것처럼 보이지만 loading state에 머묾
proxy network, restricted network, company network 또는 certificate inspection environment를 사용 중임
같은 API Key가 다른 tools에서는 작동함

해결

CC Switch provider 활성 상태 확인

CC Switch를 열고 BetterToken provider가 선택되었는지 확인한 다음 상단 routing / proxy toggle을 enable하세요.

CC Switch에서 BetterToken provider가 선택되어 있고 상단 routing toggle이 enabled되어 있습니다.

Needs model mapping 활성화

provider edit page를 열고 Needs model mapping을 enable하세요.

이렇게 하면 CC Switch가 Claude Desktop이 허용하는 세 model roles를 BetterToken에서 available한 actual models에 map할 수 있습니다.

claude-sonnet-*
claude-opus-*
claude-haiku-*

Needs model mapping이 enabled되어 있고 API Format과 Model mapping settings가 보이는 CC Switch provider edit page입니다.

API Format 선택

API Format에서 다음을 선택하세요.

Anthropic Messages (Native)

Model mapping 입력

Model mapping을 입력하세요. 모델 광장에서 현재 available model IDs를 사용하세요.

모델 역할	메뉴 표시 이름	요청 model
Sonnet	`claude-sonnet-5`	`claude-sonnet-5`
Opus	`claude-opus-4-8`	`claude-opus-4-8`
Haiku	`claude-haiku-4-5`	`claude-haiku-4-5-20251001`

model이 1M context window를 지원하면 Declare 1M을 enable하세요.

저장 후 다시 테스트

Save를 클릭하세요. Claude Desktop으로 돌아가 model을 다시 선택하고 test message를 보내세요.

setup이 올바르면 Claude Desktop은 CC Switch local route를 통해 BetterToken을 호출합니다. 이렇게 하면 보통 SSL error 또는 no-response issue가 해결됩니다.

CC Switch local routing과 model mapping을 enable한 후 Claude Desktop이 response를 반환합니다.

참고

이전 screenshots의 model names를 그대로 복사하지 마세요. 모델 광장의 현재 available model IDs를 사용하세요.
API Key는 CC Switch provider에 저장하세요. public docs, screenshots 또는 chat logs에 넣지 마세요.
계속 실패하면 상단 CC Switch routing toggle, active provider, complete Model mapping 및 local firewall이 127.0.0.1을 block하는지 확인하세요.