OpenClaw와 DeepSeek: 설정, 모델 ID 및 API 비용

OpenClaw는 별도로 설치되는 공식 provider 플러그인을 통해 DeepSeek에 연결됩니다 — openclaw plugins install @openclaw/deepseek-provider — provider id는 deepseek, 키는 DEEPSEEK_API_KEY, API는 OpenAI 호환 방식이며 base URL https://api.deepseek.com에는 /v1가 포함되지 않습니다. 첫 실행이 성공하는지는 두 가지 사실에 달려 있습니다. DeepSeek의 현재 카탈로그에는 deepseek-flash 및 deepseek-v4-pro 두 id만 있으며, 이전 튜토리얼에서 사용하는 deepseek-chat 및 deepseek-reasoner 이름은 2026년 7월 24일에 중단되었습니다. 또한 OpenClaw의 온보딩은 deepseek/deepseek-v4-pro을 기본값으로 설정하는데, 이 모델은 현재 요금에 대해 DeepSeek 자체 페이지들의 내용이 서로 일치하지 않는 모델입니다.

설정에 들어가기 전에 검색 결과에 서로 섞여 있는 두 프로젝트를 구분해야 합니다. 다른 프로젝트인 GitHub의 OpenClaw는 자신을 "원작 Captain Claw(1997) 플랫폼 게임의 멀티플랫폼 C++ 재구현"이라고 설명하며, 이 프로젝트의 내용은 여기와 관련이 없습니다. 여기서 말하는 에이전트는 openclaw.ai의 프로젝트이며, 문서는 docs.openclaw.ai에 있습니다. documentation.openclaw.ai는 해당 호스트로만 리디렉션하므로 이 호스트에 연결하세요.

두 프로젝트의 문서에 따라 설치하고 구성하기

# 1. Install the provider plugin — DeepSeek support is not bundled.
openclaw plugins install @openclaw/deepseek-provider

# 2. Interactive: prompts for the key, sets deepseek/deepseek-v4-pro as default.
openclaw onboard --auth-choice deepseek-api-key

# 2b. Or scripted, with the flags OpenClaw documents for a headless install.
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice deepseek-api-key \
  --deepseek-api-key "$DEEPSEEK_API_KEY" \
  --skip-health \
  --accept-risk

플러그인이 설치되어 있으면 base URL을 직접 지정하지 않습니다. 플러그인이 자체 카탈로그와 자체 호환성 동작을 제공합니다. 최소 구성은 JSON5에서 키와 모델을 지정하는 것입니다.

{
  env: { vars: { DEEPSEEK_API_KEY: "sk-..." } },
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v4-pro" },
    },
  },
}

OpenClaw는 문서화된 우선순위에 따라 네 가지 환경 변수 형식에서 provider 키를 확인합니다. 우선순위가 가장 높은 단일 실시간 재정의인 OPENCLAW_LIVE_DEEPSEEK_KEY, 쉼표 또는 세미콜론으로 구분된 목록인 DEEPSEEK_API_KEYS, 기본 키인 DEEPSEEK_API_KEY, 번호가 붙은 DEEPSEEK_API_KEY_* 항목 순입니다(Control UI 및 키, 2026년 9월 21일 확인). Control UI에서 Settings 다음 Models로 이동하면 파일을 편집하지 않고 키를 추가하거나 교체할 수 있으며, 키 자료는 auth store에 저장됩니다. 서버 설치에서 주의할 점은 표기법이 아니라 범위입니다. OpenClaw 자체 페이지는 Gateway가 launchd 또는 systemd에서 데몬으로 실행되는 경우 키가 해당 프로세스에서 보여야 하며, 예를 들어 ~/.openclaw/.env 또는 env.shellEnv을 통해 제공해야 한다고 경고합니다.

실제로 활성 상태인 DeepSeek 모델 id

아래 행에는 하나가 아닌 세 가지 상태가 표시됩니다. DeepSeek의 list-models 참조에 있는 샘플 응답에는 deepseek-flash 및 deepseek-v4-pro라는 정확히 두 개의 id가 표시되지만, OpenClaw에 포함된 카탈로그에는 여전히 네 개의 ref가 제공됩니다.

두 가지 중단 관련 설명은 서로 모순되는 것처럼 보이지만 실제로는 그렇지 않으므로 분리해서 보아야 합니다. OpenClaw는 DeepSeek가 deepseek-chat 및 deepseek-reasoner을 중단했으며 "해당 모델 ID는 더 이상 접근할 수 없다"고 설명합니다. 한편 DeepSeek는 "레거시 이름 deepseek-v4-flash 및 deepseek-v4-flash-vision-exp은 여전히 허용되지만 해당 모델은 중단되었다"고 별도로 설명합니다. 서로 다른 두 쌍의 이름이며 결과도 서로 다릅니다. DeepSeek의 Models & Pricing 페이지에는 두 활성 id 모두 컨텍스트 길이 1M, 최대 출력 384K로 표시되어 있고, OpenClaw의 카탈로그 표에도 네 ref 모두에 동일한 1,000,000 / 384,000 쌍이 기재되어 있습니다.

아직 해결되지 않은 문제입니다. DeepSeek의 2026년 9월 10일 발표는 "V4-Pro를 단계적으로 종료한다"고 하며 "2026년 9월 14일 04:00 UTC부터 모든 deepseek-v4-pro 요청이 V4.1-Flash로 라우팅되고 V4.1-Flash 요금이 적용된다"고 합니다. 그러나 같은 출시의 변경 로그는 반대로 "사용자 수요에 따라 2026년 9월 14일 이후에도 DeepSeek V4 Pro에 대한 API 서비스를 계속 제공하기로 결정했으며, 요금 방식은 변경하지 않는다"고 합니다. Models & Pricing 페이지에는 여전히 V4 Pro가 더 높은 자체 요금과 함께 표시되어 있고 중단 안내가 없습니다. 두 페이지 모두 2026년 9월 21일, 해당 날짜로부터 일주일 후에 확인했습니다. 이 페이지로는 어느 쪽이 사용자에게 요금을 청구하는지 알 수 없습니다. 온보딩 기본값을 그대로 두기 전에 자신의 DeepSeek 계정에서 확인하세요. 기본값이 바로 논쟁 중인 모델이라는 점도 기억해야 합니다.

토큰 비용과 시간이 가격의 일부인 이유

DeepSeek는 피크 및 비피크 요금을 게시하며, 비피크 요금은 피크의 절반입니다. 시간대는 좁습니다. "피크 시간은 월요일부터 금요일까지 01:00~04:00 및 06:00~10:00 UTC이며, 중국 공휴일은 제외됩니다. 주말과 중국 공휴일 전체를 포함한 그 밖의 모든 시간은 비피크입니다." 평일 중 7시간만 피크이고 나머지는 모두 비피크이므로, 피크 시간이라고 암묵적으로 가정한 추정치는 일반적인 청구액을 과대평가합니다.

2026년 9월 21일 DeepSeek의 Models & Pricing 페이지에서 확인했습니다. Flash 행은 OpenClaw의 공급자 페이지에서도 독립적으로 뒷받침되며, 해당 페이지에는 "입력 토큰 100만 개당 $0.30, 출력 토큰 100만 개당 $1.20, 캐시된 입력 토큰 100만 개당 $0.006"이라고 명시되어 있습니다. V4 Pro 행은 Models & Pricing 페이지만을 근거로 하며 위의 모순과 관련되어 있으므로, 확정된 값이 아니라 인용된 값으로 취급하세요.

에이전트 청구액을 좌우하는 열은 캐시 열이며, 그 비율도 특이합니다. deepseek-flash에서 캐시 적중은 100만 개당 $0.006이고 미적중은 $0.30이므로, 미적중 요금의 대략 50분의 1입니다. 이는 다른 곳에서 흔한 10분의 1 비율보다 훨씬 낮으므로 다른 공급자의 가정을 그대로 적용하지 마세요. DeepSeek의 캐싱 가이드에 따르면 이 기능은 "코드를 수정할 필요 없이 모든 사용자에게 기본적으로 활성화"되어 있고, 적중하려면 접두사가 완전히 일치해야 하며, 사용되지 않은 캐시는 "보통 몇 시간에서 며칠 이내에" 삭제됩니다. 적중과 미적중은 prompt_cache_hit_tokens 및 prompt_cache_miss_tokens 사용량 필드로 반환됩니다. DeepSeek는 캐시 쓰기 요금을 게시하지 않았고 가격표에도 캐시 쓰기 열이 없습니다. 이는 게시된 요금이 없다는 뜻이지 쓰기가 무료라는 뜻은 아닙니다.

deepseek-flash에서 DeepSeek의 게시 요금을 적용한 예시 세션입니다. 한 번의 OpenClaw 실행에서 입력 토큰 600,000개를 전송하고, 그중 450,000개는 접두사 캐시에 적중하며 150,000개는 미적중이고, 출력 토큰 40,000개를 받는다고 가정해 보겠습니다. 피크 시간에는 $0.045와 $0.0027 및 $0.048의 합인 $0.096이고, 같은 세션의 비피크 비용은 $0.048입니다. 캐시 적중이 전혀 없는 동일한 실행은 피크 시간에 $0.228입니다. 이는 명시된 가정에 따른 토큰 산술일 뿐, 측정된 작업 비용이나 지출 상한이 아닙니다. 가장 중요한 변수는 실제 캐시 적중 비율이며, OpenClaw 앱의 수치로는 이를 확정할 수 없습니다. OpenClaw는 자체 비용이 추정치라고 하며 청구의 기준으로 DeepSeek 가격 페이지를 안내합니다.

모델 기능과 클라이언트 도구 지원은 서로 다른 문제입니다

가격표만으로는 알 수 없는 부분이며, 직접 provider 항목을 작성하는 대신 플러그인을 사용해야 하는 실질적인 이유입니다. DeepSeek V4 사고 세션에서는 사고가 활성화된 턴의 assistant 메시지를 후속 요청에 재생할 때 reasoning_content을 포함해야 합니다. OpenClaw의 DeepSeek 플러그인은 이 필드를 자동으로 보완하므로, 멀티턴 도구 사용이 "다른 OpenAI 호환 provider에서 기록이 넘어온 경우(네이티브 reasoning_content 없음)나 일반 assistant 메시지에서도" 작동하며, 세션 중간에 provider를 전환한 뒤에도 /new가 필요하지 않습니다. 사고 기능이 꺼져 있으면 UI에서 None을 선택한 경우를 포함해 OpenClaw는 thinking: { type: "disabled" }를 전송하고 나가는 기록에서 재생된 reasoning_content를 제거합니다. 또한 OpenClaw는 /think xhigh 및 /think max을 DeepSeek의 최대 reasoning_effort로 매핑합니다.

일반적인 openai-completions 사용자 지정 provider에서 DeepSeek 호환 엔드포인트를 지정하면 이러한 보완 기능을 사용할 수 없으며, 호환성 블록을 직접 선언하지 않는 한 DeepSeek 사고 형식도 사용할 수 없습니다. OpenClaw의 ds4 페이지에는 thinkingFormat: "deepseek" 및 supportsReasoningEffort를 포함한 형식이 나와 있습니다. 이 차이가 도구 턴이 한 번은 성공한 뒤 후속 턴에서 실패하는 일반적인 원인입니다.

DeepSeek 측의 두 가지 제한도 함께 고려해야 합니다. 엄격 모드 도구 호출은 다른 base URL인 https://api.deepseek.com/beta에서 작동하며, 각 함수에 "strict": true와 "additionalProperties": false가 필요합니다. 플러그인은 기본적으로 이 위치를 사용하지 않습니다. 또한 DeepSeek의 도구 호출 가이드에는 "Chat Completion API는 대화 중간에 도구 호출을 삽입하는 기능은 지원하지 않지만 system 메시지를 대화 중간에 삽입하는 기능은 지원합니다. 도구 호출을 삽입하려면 Anthropic API 또는 Responses API를 사용하세요"라고 명시되어 있습니다. 이는 OpenClaw 플러그인이 사용하는 엔드포인트의 제한이며, 모델의 제한이 아니라 문서화된 두 가지 대안이 있습니다.

모델 지원에 대해서는 두 출처가 일치합니다. DeepSeek의 Models & Pricing 페이지의 FEATURES 열은 deepseek-flash 및 deepseek-v4-pro 모두에서 Tool Calls, JSON Output, Responses API 및 Anthropic API를 지원한다고 표시하며, vision은 별도로 deepseek-flash에서는 지원되고 deepseek-v4-pro에서는 지원되지 않는다고 표시합니다. OpenClaw는 네 개의 ref 모두에서 멀티턴 도구 사용이 가능하다고 설명합니다. 어느 쪽도 병렬 도구 호출을 문서화하지 않았으므로, 이 부분은 어느 한쪽으로도 답이 정해지지 않은 실제 미해결 사항입니다.

세 단계로 확인한 뒤, 이름을 붙여야 할 실패를 살펴보세요

각 항목은 서로 다르게 실패하므로 순서대로 확인하세요. 첫째는 카탈로그입니다. openclaw models list --provider deepseek 또는 실행 중인 Gateway 없이 플러그인의 정적 카탈로그를 확인하는 openclaw models list --all --provider deepseek를 사용한 다음, 온보딩 기본값이 아닌 논쟁의 여지가 없는 모델을 원한다면 openclaw models set deepseek/deepseek-flash를 실행합니다. 둘째는 짧은 비스트리밍 프롬프트 하나와 스트리밍 프롬프트 하나입니다. 이 단계에서 인증 또는 base URL 문제가 명확하게 드러납니다. 셋째이자 마지막으로, 도구 호출 후 같은 세션에서 두 번째 턴을 실행합니다. 이는 앞서 설명한 reasoning_content 재생을 유일하게 테스트하는 단계입니다.

404 행은 문서만으로 설명할 수 없는 유일한 항목이므로 별도의 문장으로 다룰 가치가 있습니다. DeepSeek의 오류 코드 표에는 400, 401, 402, 422, 429, 500, 503이 나열되어 있고 404는 없으므로, 여기서 404가 발생한다는 것은 DeepSeek가 아니라 사용자의 라우팅에 대한 증거입니다. 알 수 없는 모델 id에 대해 DeepSeek가 실제로 반환하는 내용은 문서화되지 않았으며 여기서 테스트하지도 않았습니다. 오류 참조에는 Kunavo 자체 엔드포인트의 이에 해당하는 상태 코드가 설명되어 있습니다.

직접 연결, Gateway, 로컬 중 어느 경로가 우선되는가

Kunavo는 DeepSeek 모델을 제공하지 않습니다. 텍스트 모델은 Claude 및 OpenAI 제품군이므로 Kunavo에서 DeepSeek 모델로 연결되는 경로는 없으며, 이 페이지도 그러한 경로를 제공하지 않습니다. 다만 메커니즘은 동일합니다. DeepSeek 자체가 아니라 모델 제품군 전반에 하나의 키를 사용하려고 이 DeepSeek 설정 페이지를 읽고 있다면 알아둘 가치가 있습니다.

Gateway 행에서 구성에 사용하는 레버는 동일한 두 가지입니다. models.providers.<id>을 선언하고 baseUrl, apiKey, api: "openai-completions" 및 각 id를 최소 하나씩 나열하는 models[] 배열을 지정하거나, --auth-choice custom-api-key, --custom-base-url, --custom-model-id를 사용해 엔드포인트에 맞춰 온보딩합니다. 모델 ref는 항상 provider/model 형식이며, agents.defaults.models에서 모델의 별칭만 지정하고 models.providers.<provider>.models[]에는 등록하지 않는 것이 조용한 실패의 원인입니다. OpenClaw의 사용자 지정 provider 참조에는 해당 별칭이 "재정의를 제한하지도 않고 그 자체로 새 런타임 모델을 등록하지도 않는다"고 명시되어 있습니다. 이 경로에서 Kunavo의 base URL은 https://api.kunavo.com/v1이며 /v1가 정확히 하나 포함됩니다. 이는 DeepSeek의 접미사 없음 규칙과 반대이므로, 한 페이지의 값을 다른 페이지의 필드에 복사할 때 404가 발생하는 가장 가능성 높은 원인입니다.

이 대안의 규모를 가늠할 수 있도록 동일한 가정의 세션 형태, 즉 입력 토큰 600,000개와 출력 토큰 40,000개를 사용하고 캐시는 가정하지 않은 경우를 Kunavo 카탈로그의 현재 요금으로 계산해 보겠습니다. 이는 다른 엔드포인트의 다른 모델이므로 위의 DeepSeek 수치와 동일한 작업 비용을 비교하는 것이 아닙니다. 게시된 최저 요금과 작업을 완료하는 최저 비용은 별개의 주장이고, 두 번째 항목은 실제 실행만으로 확인할 수 있습니다.

명시된 가정에 따른 예시 토큰 산술이며, 측정된 작업 비용이나 청구 상한이 아닙니다. Kunavo의 카탈로그 금액은 상한이 아니라 청구 하한입니다. upstream이 요금을 보고하면 청구액은 카탈로그 비용과 upstream 비용에 해당 마크업을 적용한 금액 중 큰 값입니다. 캐시 요금과 외부 도구 비용은 이 예시에 포함되지 않습니다. 최소 충전액은 선불 크레딧 $10입니다. 이는 자금 충전 최소액이지 작업 요금이나 구독료가 아닙니다. 청구 세부 정보 및 캐싱을 참조하세요.

실제로 원하는 것이 이 인접한 경로라면 통합 개요에서 base URL과 키 설정을 확인하고, 빠른 시작에서 첫 호출을 수행한 다음, 키에 자금을 충전할 준비가 되면 Kunavo 계정 만들기로 이동하세요. 이는 호환성 테스트 결과가 아니라 게시된 구성 참조로 취급해야 합니다. OpenClaw는 Kunavo 엔드포인트에서 실제 실행 테스트를 하지 않았습니다. OpenClaw를 계속 사용하면서 대신 모델을 선택하시겠습니까? OpenClaw 요금에서는 무료 소프트웨어와 사용량 기반 청구를 구분하고, OpenClaw에 가장 적합한 API에서는 작업별 경로를 비교하며, OpenAI 호환 API에서는 이 페이지에서 계속 경고하는 base URL 규칙을 설명합니다.

자주 묻는 질문

위의 모든 OpenClaw 및 DeepSeek 관련 내용은 해당 프로젝트의 자체 문서와 레지스트리를 2026년 9월 21일에 확인한 것으로, OpenClaw v2026.9.5를 기준으로 했습니다. 공급자 페이지, 가격 페이지, 변경 로그, 9월 10일 발표, list-models 참조, 오류 코드 표, 요청 제한 페이지 및 사용자 지정 공급자 규칙을 모두 이 페이지를 위해 직접 다시 가져왔습니다. 설치, 온보딩 또는 호출은 수행하지 않았습니다. OpenClaw 실행, api.deepseek.com에 대한 요청, Kunavo에 대한 실제 실행 테스트 모두 없었습니다. Kunavo 토큰 요금은 현재 카탈로그에서 가져왔으며, 모든 달러 금액은 측정된 비용이 아니라 명시된 가정에 따른 예시 토큰 계산입니다.