Claude Code에서 OpenRouter와 DeepSeek를 연결할 때는 명령어를 먼저 붙여 넣지 말고 활성 경로부터 고릅니다. OpenRouter를 쓰면 gateway, 모델 카탈로그, provider routing, activity 기록의 소유자는 OpenRouter입니다. DeepSeek 직접 연결을 쓰면 Anthropic-compatible endpoint, 토큰, 모델 ID, 사용 기록의 소유자는 DeepSeek입니다. 프록시나 router 프로젝트를 쓰면 API shape, 로그, 비용, 데이터 경로가 증명될 때까지 실험 경로로 봐야 합니다.
| 경로 | 맞는 경우 | 테스트 전에 맞아야 하는 것 |
|---|---|---|
| OpenRouter 경로 | OpenRouter가 gateway, provider routing, 모델 카탈로그, activity를 맡아야 할 때. | OpenRouter base URL, OpenRouter token, OpenRouter 모델명, OpenRouter activity. |
| DeepSeek 직접 경로 | Claude Code 요청을 DeepSeek Anthropic-compatible API로 직접 보내야 할 때. | DeepSeek base URL, DeepSeek token, DeepSeek model ID, DeepSeek 쪽 activity. |
| proxy/router 경로 | 3rd-party adapter, 로컬 gateway, 팀 router를 검증할 때. | base URL, token, model mapping, logs, data handling, cost proof를 같은 owner가 설명해야 함. |
실제 저장소 작업 전에 /status, provider logs, 작은 canary prompt가 같은 owner를 가리키는지 확인합니다. 한 테스트에는 base URL 하나, credential owner 하나, model owner 하나만 있어야 합니다. 다르면 설정을 더 넣지 말고 먼저 되돌립니다.
환경 변수보다 경로가 먼저다
자주 깨지는 이유는 Claude Code에 숨겨진 특수 명령어가 없어서가 아닙니다. OpenRouter base URL에 DeepSeek token을 붙이거나, DeepSeek model ID를 쓰면서 예전 Anthropic 로그인이나 ANTHROPIC_API_KEY가 우선되거나, proxy가 HTTP 요청만 받고 Claude Code가 기대하는 Anthropic API shape를 보존하지 못하는 식의 소유권 혼합입니다.
2026-07-03 기준으로 책임은 이렇게 나눕니다.
| Owner | 책임지는 것 | 증명하지 않는 것 |
|---|---|---|
| Anthropic Claude Code docs | 클라이언트 동작, 환경 변수 이름, settings, /status, gateway boundary. | 모든 third-party model이나 proxy가 Anthropic 지원이라는 뜻. |
| OpenRouter docs | OpenRouter Claude Code route, token, base URL, model naming, provider activity. | DeepSeek 직접 API가 OpenRouter routing과 같은 동작이라는 뜻. |
| DeepSeek docs | DeepSeek Anthropic-compatible endpoint, DeepSeek model IDs, mapping, caveats. | OpenRouter provider routing이나 proxy route가 활성이라는 뜻. |
| proxy/router project | 자체 adapter, logs, cost, data path, compatibility claim. | Claude Code 공식 지원, provider cost, tool behavior 보장. |
OpenRouter cookbook은 OpenRouter가 gateway owner일 때 쓰는 자료입니다. DeepSeek coding-agent 문서는 DeepSeek 직접 연결이 owner일 때 쓰는 자료입니다. Anthropic Claude Code 문서는 클라이언트 경계입니다. 세 자료를 섞지 말고 선택한 owner에 맞춰 읽어야 합니다.
충돌 credential 정리
OpenRouter나 DeepSeek를 설정하기 전에 현재 shell을 확인합니다. secret 값을 출력하지 말고 존재 여부만 봅니다.
test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set"
test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set"
test -n "$ANTHROPIC_BASE_URL" && echo "ANTHROPIC_BASE_URL is set"
test -n "$ANTHROPIC_MODEL" && echo "ANTHROPIC_MODEL is set"
예상 밖 결과가 나오면 shell profile, .env loader, IDE terminal, devcontainer, CI secret, .claude/settings.local.json 중 어디에서 왔는지 찾습니다. 새 export를 계속 덮으면 잠깐은 통과해도 나중에 어떤 owner가 이겼는지 설명할 수 없습니다.
깨끗한 테스트는 먼저 비웁니다.
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_MODEL
확인한 shell에서 Claude Code를 시작합니다. 확인한 환경과 실행한 환경이 다르면 테스트는 route proof가 아닙니다.
OpenRouter 경로 설정
OpenRouter 경로는 OpenRouter가 gateway owner일 때 씁니다. token은 OpenRouter에서 오고, base URL은 OpenRouter를 가리키며, model selector는 OpenRouter의 현재 문서를 따르고, activity proof도 OpenRouter에서 보여야 합니다.
임시 shell 테스트:
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
unset ANTHROPIC_API_KEY
claude
/status
문서와 공유 script에는 placeholder만 둡니다. 핵심은 ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, model selector가 모두 OpenRouter route에 속한다는 점입니다.
첫 proof는 작아야 합니다. 새 Claude Code session에서 /status를 보고, 파일을 바꾸지 않는 canary prompt를 보낸 뒤, OpenRouter activity에서 같은 request, model, provider route를 찾습니다. 맞지 않으면 model name을 바꾸기보다 환경을 지우고 하나의 owner에서 다시 세웁니다.
DeepSeek 직접 연결
DeepSeek 직접 연결은 Claude Code가 Anthropic-compatible request를 DeepSeek API로 바로 보내야 할 때 씁니다. endpoint, token, model ID, compatibility caveat, activity proof는 DeepSeek가 소유합니다.
shell-scoped 테스트:
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="$DEEPSEEK_API_KEY"
export ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
claude
/status
DeepSeek 문서에는 deepseek-v4-flash 같은 coding-agent model option도 있습니다. 하지만 model ID는 영구값이 아닙니다. availability, suffix, web-search behavior, mapping, price는 변하므로 팀 runbook에 쓰기 전 다시 확인해야 합니다.
OpenRouter log는 DeepSeek 직접 연결의 proof가 아닙니다. 그것은 OpenRouter-owned route가 DeepSeek provider를 썼을 수 있다는 proof입니다. direct route는 DeepSeek endpoint, DeepSeek model ID, DeepSeek activity가 같이 보여야 합니다.
settings.local로 shell drift 줄이기
shell export는 한 번의 canary에 좋지만 며칠 뒤 재개할 때 위험합니다. 반복 실험은 commit되지 않는 local settings에 두면 경로가 보이고 secret은 공유되지 않습니다.
DeepSeek 직접 연결 예:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
"ANTHROPIC_AUTH_TOKEN": "$DEEPSEEK_API_KEY",
"ANTHROPIC_MODEL": "deepseek-v4-flash"
}
}
OpenRouter도 같은 owner 원칙을 씁니다.
{
"env": {
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_AUTH_TOKEN": "$OPENROUTER_API_KEY",
"ANTHROPIC_MODEL": "openrouter-model-id-from-current-docs"
}
}
먼저 .claude/settings.local.json이 ignore되는지 확인합니다. shared settings에는 provider tokens, private base URLs, 개인 provider 선택을 넣지 않습니다. 팀 파일은 행동을 설명하고, 개인 파일은 개인 경로를 담습니다.
실제 작업 전 검증 루프
검증은 장애 후 정리가 아니라 설정의 일부입니다. backend switch는 route, credential, model, provider evidence가 모두 같은 owner를 말할 때만 안전합니다.
| 단계 | 확인할 것 | 통과 조건 |
|---|---|---|
| 1. Minimal prompt | 저장소를 수정하지 않는 작은 prompt. | auth/tool error 없이 응답. |
2. /status | Claude Code가 보는 account, route, model. | 선택한 owner와 일치. |
| 3. Environment | base URL, token owner, model variable. | 목표 경로 변수만 남음. |
| 4. Provider activity | OpenRouter 또는 DeepSeek dashboard/log. | 같은 request가 올바른 provider owner에 나타남. |
| 5. Read-only repo action | config 설명, scripts 요약, harmless command. | 파일을 바꾸지 않고 정상 동작. |
| 6. Rollback | env vars를 지우고 재시작. | 이전에 아는 route로 돌아감. |
비용, availability, model choice 때문에 바꾸는 경우 provider activity proof는 특히 중요합니다. /status는 Claude Code의 시각이고, provider activity는 실제로 누가 요청을 받았는지 보여줍니다.
첫 오류는 먼저 분류한다
첫 run이 실패하면 설정을 더 넣기 전에 분류합니다. 대부분은 ownership mismatch입니다.
| 증상 | 가능 원인 | 첫 조치 |
|---|---|---|
401 또는 403 | token이 base URL owner와 다르거나 만료, 다른 credential variable이 우선. | route vars를 지우고 하나의 token owner만 설정 후 재시작. |
404, model not found, model mismatch | model ID가 다른 route 소유이거나 catalog가 오래됨. | 현재 route owner의 model ID로 바꾸고 provider activity 확인. |
| provider dashboard가 조용함 | 요청이 예상한 provider에 도달하지 않음. | ANTHROPIC_BASE_URL, shell source, 오래된 auth, proxy 확인. |
| Claude Code가 멈춤 또는 tools 이상 | proxy 호환성이 부분적이고 headers/tool calls가 보존되지 않음. | 문서화된 route로 돌아가고 proxy는 별도 테스트. |
| 비용이 다른 곳에 나타남 | route owner와 billing owner가 섞임. | /status와 provider activity로 다시 확인. |
| free/unlimited 경로 실패 | 현재 provider evidence가 claim을 증명하지 않음. | route, model, limits proof가 생길 때까지 미검증으로 둠. |
빠른 복구:
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_MODEL
claude
/status
알려진 상태로 돌아간 뒤 한 branch만 추가합니다. OpenRouter 실패는 OpenRouter base URL, token, model, activity 안에서 봅니다. DeepSeek 실패는 DeepSeek endpoint, token, model ID, activity 안에서 봅니다. branch를 섞은 fix는 proof를 망칩니다.
비용, 데이터, 지원의 중지 기준
첫 약속은 싸다는 말이 아니라 증명 가능한 경로입니다. prices, free tiers, provider priority, web-search charges, model availability, rate limits는 빠르게 바뀝니다. free forever, unlimited, works with any model 같은 말은 현재 owner proof 없이는 팀 규칙이 될 수 없습니다.
| 중지 기준 | 이유 |
|---|---|
| 검증 안 된 proxy에 sensitive code를 보내지 않음 | prompts, files, tool output을 누가 기록하는지 모릅니다. |
| provider proof 없는 cost claim을 믿지 않음 | OpenRouter와 DeepSeek의 price, availability, provider path는 바뀝니다. |
| non-Claude route를 Anthropic 공식 지원으로 부르지 않음 | Anthropic은 Claude Code client boundary를 책임집니다. |
| token과 private base URL을 commit하지 않음 | shared settings는 secret storage가 아닙니다. |
| provider activity proof 전에 real edits를 실행하지 않음 | agent가 파일을 바꾸기 전 rollback path가 필요합니다. |
질문이 gateway 선택이면 gateway 비교를 먼저 합니다. CLI 설치면 install path를 먼저 봅니다. 다른 제품에서 DeepSeek를 쓰는 문제라면 그 product route를 Claude Code gateway 설정과 섞지 않습니다.
자주 묻는 질문
Claude Code에서 OpenRouter와 DeepSeek를 쓸 수 있나요?
쓸 수 있습니다. 다만 한 session에서 섞으면 안 됩니다. OpenRouter owner, DeepSeek direct owner, proxy owner 중 하나로 base URL, token, model, activity proof를 맞춥니다.
DeepSeek는 OpenRouter 경유와 직접 연결 중 무엇이 낫나요?
OpenRouter provider routing, dashboard, model catalog, gateway behavior가 필요하면 OpenRouter입니다. DeepSeek endpoint, DeepSeek model ID, DeepSeek-side activity가 필요하면 직접 연결입니다. 더 나은 경로는 현재 repo, cost boundary, support owner를 증명할 수 있는 경로입니다.
설정은 어디에 두나요?
일회성 canary는 shell variables입니다. 반복 local experiment는 ignore된 .claude/settings.local.json에 둡니다. provider token, private base URL, 개인 route를 shared settings에 넣지 않습니다.
/status만으로 충분한가요?
충분하지 않습니다. /status는 client-side check입니다. 실제 작업 전에는 environment check와 OpenRouter 또는 DeepSeek provider activity를 같이 봅니다.
free 또는 unlimited route는 믿어도 되나요?
현재 provider route가 증명할 때만 믿습니다. free tier, unlimited, priority, pricing은 volatile fact입니다. 팀 문서에는 proof date, owner, rollback path를 남깁니다.
model name이 계속 실패하는 이유는 무엇인가요?
model ID가 다른 route의 것일 수 있습니다. OpenRouter model name, DeepSeek direct model ID, Anthropic model alias는 서로 바꿔 쓸 수 없습니다. route를 지우고 하나의 owner 문서에서 다시 확인합니다.