# Claude Code에서 OpenRouter와 DeepSeek 쓰기: 경로, 설정, 첫 오류 해결

> Claude Code를 OpenRouter나 DeepSeek로 연결할 때 필요한 경로 선택, 환경 변수, 모델명, /status, 공급자 로그, 첫 오류 복구 기준을 정리합니다.

- URL: https://blog.laozhang.ai/ko/posts/claude-code-openrouter-deepseek
- Published: 2026-07-03
- Updated: 2026-07-03
- Author: AI Free API Team (https://blog.laozhang.ai/ko/about)
- Category: Claude Code
- Tags: Claude Code, OpenRouter, DeepSeek, 개발자 도구, API 설정

---
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가 설명해야 함. |

실제 저장소 작업 전에 <code>/status</code>, provider logs, 작은 canary prompt가 같은 owner를 가리키는지 확인합니다. 한 테스트에는 base URL 하나, credential owner 하나, model owner 하나만 있어야 합니다. 다르면 설정을 더 넣지 말고 먼저 되돌립니다.

## 환경 변수보다 경로가 먼저다

자주 깨지는 이유는 Claude Code에 숨겨진 특수 명령어가 없어서가 아닙니다. OpenRouter base URL에 DeepSeek token을 붙이거나, DeepSeek model ID를 쓰면서 예전 Anthropic 로그인이나 <code>ANTHROPIC_API_KEY</code>가 우선되거나, proxy가 HTTP 요청만 받고 Claude Code가 기대하는 Anthropic API shape를 보존하지 못하는 식의 소유권 혼합입니다.

2026-07-03 기준으로 책임은 이렇게 나눕니다.

| Owner | 책임지는 것 | 증명하지 않는 것 |
| --- | --- | --- |
| Anthropic Claude Code docs | 클라이언트 동작, 환경 변수 이름, settings, <code>/status</code>, 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 정리

![Claude Code, OpenRouter, DeepSeek, proxy 경로의 환경 변수 소유자 지도](https://blog.laozhang.ai/posts/ko/claude-code-openrouter-deepseek/img/env-var-ownership-map.png)

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, <code>.env</code> loader, IDE terminal, devcontainer, CI secret, <code>.claude/settings.local.json</code> 중 어디에서 왔는지 찾습니다. 새 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만 둡니다. 핵심은 <code>ANTHROPIC_BASE_URL</code>, <code>ANTHROPIC_AUTH_TOKEN</code>, model selector가 모두 OpenRouter route에 속한다는 점입니다.

첫 proof는 작아야 합니다. 새 Claude Code session에서 <code>/status</code>를 보고, 파일을 바꾸지 않는 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 문서에는 <code>deepseek-v4-flash</code> 같은 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"
      }
    }

먼저 <code>.claude/settings.local.json</code>이 ignore되는지 확인합니다. shared settings에는 provider tokens, private base URLs, 개인 provider 선택을 넣지 않습니다. 팀 파일은 행동을 설명하고, 개인 파일은 개인 경로를 담습니다.

## 실제 작업 전 검증 루프

![Claude Code 백엔드 경로 검증 루프](https://blog.laozhang.ai/posts/ko/claude-code-openrouter-deepseek/img/verification-loop.png)

검증은 장애 후 정리가 아니라 설정의 일부입니다. backend switch는 route, credential, model, provider evidence가 모두 같은 owner를 말할 때만 안전합니다.

| 단계 | 확인할 것 | 통과 조건 |
| --- | --- | --- |
| 1. Minimal prompt | 저장소를 수정하지 않는 작은 prompt. | auth/tool error 없이 응답. |
| 2. <code>/status</code> | 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는 특히 중요합니다. <code>/status</code>는 Claude Code의 시각이고, provider activity는 실제로 누가 요청을 받았는지 보여줍니다.

## 첫 오류는 먼저 분류한다

![OpenRouter와 DeepSeek를 쓰는 Claude Code 첫 오류 분류 보드](https://blog.laozhang.ai/posts/ko/claude-code-openrouter-deepseek/img/first-error-triage.png)

첫 run이 실패하면 설정을 더 넣기 전에 분류합니다. 대부분은 ownership mismatch입니다.

| 증상 | 가능 원인 | 첫 조치 |
| --- | --- | --- |
| <code>401</code> 또는 <code>403</code> | token이 base URL owner와 다르거나 만료, 다른 credential variable이 우선. | route vars를 지우고 하나의 token owner만 설정 후 재시작. |
| <code>404</code>, model not found, model mismatch | model ID가 다른 route 소유이거나 catalog가 오래됨. | 현재 route owner의 model ID로 바꾸고 provider activity 확인. |
| provider dashboard가 조용함 | 요청이 예상한 provider에 도달하지 않음. | <code>ANTHROPIC_BASE_URL</code>, shell source, 오래된 auth, proxy 확인. |
| Claude Code가 멈춤 또는 tools 이상 | proxy 호환성이 부분적이고 headers/tool calls가 보존되지 않음. | 문서화된 route로 돌아가고 proxy는 별도 테스트. |
| 비용이 다른 곳에 나타남 | route owner와 billing owner가 섞임. | <code>/status</code>와 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된 <code>.claude/settings.local.json</code>에 둡니다. provider token, private base URL, 개인 route를 shared settings에 넣지 않습니다.

### <code>/status</code>만으로 충분한가요?

충분하지 않습니다. <code>/status</code>는 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 문서에서 다시 확인합니다.