모델 제공자

모델 제공자 (Model Providers)

에이전트를 쓸 때 "어느 모델로 돌릴까"는 항상 갈리는 질문이에요. Deep Agents Code는 LangChain과 호환되는 어떤 채팅 모델 제공자든 지원해서, 사실상 툴 콜링(tool calling)을 지원하는 거의 모든 LLM을 쓸 수 있게 해줘요. OpenAI 호환 또는 Anthropic 호환이 API를 노출하는 서비스라면 설정 없이 그대로 동작하기도 해요. 여기서 제공자를 어떻게 설치·인증하고, 모델을 어떻게 전환하는지 살펴볼게요.

출처: 공식문서

퀵스타트

Deep Agents Code는 다음 모델 제공자와 자동으로 통합돼요. 관련 제공자 패키지만 설치하면 추가 설정이 필요 없어요.

제공자 패키지 설치

각 모델 제공자는 해당 LangChain 통합 패키지를 필요로 해요. 이 패키지들은 선택적 extra로 제공돼서 앱을 가볍게 유지해요. OpenAI, Anthropic, Gemini는 기본 포함돼요. 다른 extra는 세션 안에서 /install로, 또는 셸에서 dcode --install로 설치할 수 있어요:
```
/install groq
```
```
dcode --install groq
```
인자 없이 /install을 실행하면 유효한 extra 목록을 보여줘요. 초기 CLI 설치 중 extra를 미리 설치하려면 DEEPAGENTS_CODE_EXTRAS를 설정해요:
```
DEEPAGENTS_CODE_EXTRAS="baseten,groq" curl -LsSf https://langch.in/dcode | bash
```
자격 증명 설정

/auth 자격 증명 매니저로 제공자의 API 키를 추가해요:
```
/auth
```
/auth는 사용 가능한 제공자 목록을 보여주고, 세션을 넘나들며 재사용할 자격 증명을 저장해요.

비대화형 실행, CI/CD, TUI를 쓸 수 없는 곳에서는 셸에서 dcode auth set으로 같은 키를 저장하거나, 제공자의 환경 변수를 설정하면 돼요. 전체 키 해석 순서는 Provider credentials 문서를, Deep Agents Code에 키를 스코프하는 방법은 DEEPAGENTS_CODE_ prefix 문서를, 각 제공자의 환경 변수는 Provider reference를 참고하세요.

모델 파라미터를 설정하려면 Model parameters를 참고하세요.

제공자 참조 (Provider reference)

여기 없는 제공자를 쓰고 싶나요? Arbitrary providers 문서를 보세요. 추가 설정으로 어떤 LangChain 호환 제공자든 Deep Agents Code에서 쓸 수 있어요.

제공자	패키지	자격 증명 환경 변수	모델 프로파일
OpenAI	`langchain-openai`	`OPENAI_API_KEY`	✅
OpenAI (Codex)	`langchain-openai`	None; ChatGPT로 로그인	✅
Azure OpenAI	`langchain-openai`	`AZURE_OPENAI_API_KEY`	✅
Anthropic	`langchain-anthropic`	`ANTHROPIC_API_KEY`	✅
Google Gemini API	`langchain-google-genai`	`GOOGLE_API_KEY`	✅
Gemini Enterprise Agent Platform	`langchain-google-genai`	`GOOGLE_CLOUD_PROJECT`	✅
Gemini Enterprise Agent Platform (Anthropic)	`langchain-google-vertexai`	`GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`	✅
Baseten	`langchain-baseten`	`BASETEN_API_KEY`	✅
AWS Bedrock	`langchain-aws`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	✅
AWS Bedrock Converse	`langchain-aws`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	✅
Hugging Face	`langchain-huggingface`	`HUGGINGFACEHUB_API_TOKEN`	✅
Ollama	`langchain-ollama`	`OLLAMA_API_KEY` (클라우드 전용; 선택)	❌
Groq	`langchain-groq`	`GROQ_API_KEY`	✅
Cohere	`langchain-cohere`	`COHERE_API_KEY`	❌
Fireworks	`langchain-fireworks`	`FIREWORKS_API_KEY`	✅
Together	`langchain-together`	`TOGETHER_API_KEY`	❌
Meta	`langchain-meta`	`MODEL_API_KEY`	✅
Mistral AI	`langchain-mistralai`	`MISTRAL_API_KEY`	✅
DeepSeek	`langchain-deepseek`	`DEEPSEEK_API_KEY`	✅
IBM (watsonx.ai)	`langchain-ibm`	`WATSONX_APIKEY`	❌
Nvidia	`langchain-nvidia-ai-endpoints`	`NVIDIA_API_KEY`	✅
xAI	`langchain-xai`	`XAI_API_KEY`	✅
Perplexity	`langchain-perplexity`	`PERPLEXITY_API_KEY` (또는 `PPLX_API_KEY`)	✅
OpenRouter	`langchain-openrouter`	`OPENROUTER_API_KEY`	✅
LiteLLM	`langchain-litellm`	제공자별 (문서)	❌

Gemini Enterprise Agent Platform에서 Anthropic 모델 설정

google_anthropic_vertex 제공자는 Gemini Enterprise Agent Platform에서 Anthropic의 Messages API를 통해 Claude를 실행해요. Anthropic API 키 대신 Google Cloud Application Default Credentials(ADC)를 사용해요.

Gemini Enterprise Agent Platform extra를 설치해요:
```
/install vertex
```
```
dcode --install vertex
```
Google Cloud 프로젝트에서 Claude 모델을 활성화하고 ADC를 설정해요:
```
gcloud auth application-default login
```
Google Cloud 프로젝트와 위치를 설정해요:
```
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="global"
```
DEEPAGENTS_CODE_GOOGLE_CLOUD_PROJECT와 DEEPAGENTS_CODE_GOOGLE_CLOUD_LOCATION으로 이 값을 Deep Agents Code에 스코프할 수 있어요.
google_anthropic_vertex 제공자로 Claude 모델을 선택해요:
```
/model google_anthropic_vertex:claude-sonnet-4-6
```
```
dcode --model google_anthropic_vertex:claude-sonnet-4-6
```
Google 모델에는 google_vertexai를 사용해요. Claude 모델은 Anthropic의 Messages API를 사용하므로 반드시 google_anthropic_vertex를 써야 해요.

DEEPAGENTS_CODE_ prefix를 추가하면 모든 자격 증명을 Deep Agents Code에 스코프할 수 있어요. 예를 들어 DEEPAGENTS_CODE_OPENAI_API_KEY는 다른 도구에 영향을 주지 않으면서 Deep Agents Code 안에서 OPENAI_API_KEY보다 우선해요. 자세한 내용은 DEEPAGENTS_CODE_ prefix 문서를 참고하세요.

모델 프로파일은 대화형 /model 스위처가 쓰는 모델 메타데이터를 제공해요. 모델이 스위처에 없으면 모델 이름을 직접 전달하거나 config.toml에 추가하세요.

ChatGPT로 로그인

openai_codex 제공자는 OPENAI_API_KEY 대신 유료 ChatGPT 구독으로 OpenAI Codex 모델을 쓸 수 있게 해줘요. ChatGPT 계정으로 로그인하면, API 키 기반 openai 제공자와 별개로 /auth와 /model 스위처 양쪽에 독자적으로 나타나요.

로그인 시작: 아무 세션에서 /auth를 실행하고 **openai_codex**를 선택해요. ChatGPT는 브라우저로 로그인하므로, API 키를 묻는 대신 브라우저 로그인이 시작돼요.
브라우저에서 인증: Deep Agents Code가 브라우저에서 ChatGPT 로그인 페이지를 열어요. 브라우저를 열 수 없으면(예: SSH) 로그인 URL을 화면에 보여주므로 다른 기기의 브라우저로 복사할 수 있어요.
Codex 모델 선택: 로그인 후 openai_codex 제공자 아래 /model 스위처에 Codex 모델이 나타나요. 스펙으로 직접 전환해요:
```
/model openai_codex:gpt-5.5
```

로그인은 세션을 넘나들며 유지돼요. 상태를 확인하거나 로그아웃하려면 /auth를 실행하고 openai_codex를 선택한 뒤 재인증 또는 로그아웃을 선택하세요.

openai_codex는 openai와 별개입니다. 표준 API 키로 OpenAI 모델을 쓰려면 일반 openai 제공자를 쓰세요 (예: /model openai:gpt-5.5).

일부 제공자별 계정 유형이나 키 스코프는 API 접근에 안 맞을 수 있습니다. /auth에 제공자가 구성된 것처럼 보여도 요청이 실패하면, 계정 플랜과 API 키 권한이 제공자의 API 요구사항과 일치하는지 확인하세요.

모델 라우터와 프록시

OpenRouter와 LiteLLM 같은 모델 라우터는 여러 제공자의 모델을 단일 엔드포인트로 접근하게 해줘요.

이 서비스에는 전용 통합 패키지를 사용해요:

라우터	패키지	구성
OpenRouter	`langchain-openrouter`	`openrouter:<model>` (내장, Provider reference 참고)
LiteLLM	`langchain-litellm`	`litellm:<model>` (내장, Provider reference 참고)

OpenRouter는 내장 제공자예요. extra를 설치하고 바로 사용해요:

/install openrouter

dcode --install openrouter

LiteLLM도 내장 제공자예요:

/install litellm

dcode --install litellm

모델 전환

Deep Agents Code에서 모델을 전환하려면:

/model 명령으로 대화형 모델 스위처를 사용합니다.

모든 모델이 여기에 나타나는 것은 아닙니다. 빠진 모델이 있으면 모델 이름을 직접 전달(예: /model gpt-5.5)하거나 config.toml에 추가하세요.
인자로 모델 이름을 직접 지정합니다(예: /model gpt-5.5). 선택한 제공자가 지원하는 어떤 모델이든, 1번 목록에 있는지와 무관하게 쓸 수 있습니다. 모델 이름은 API 요청으로 전달됩니다.
--model로 시작 시 지정합니다:
```
dcode --model openai:gpt-5.5
```

모델 해석 순서

Deep Agents Code가 시작할 때 다음 순서로 사용할 모델을 결정해요:

--model 플래그: 제공되면 항상 우선합니다.
~/.deepagents/config.toml의 [models].default: 사용자의 의도된 장기 선호입니다.
~/.deepagents/config.toml의 [models].recent: /model로 마지막 전환한 모델입니다. 자동으로 기록되며 [models].default를 덮어쓰지 않습니다.
환경 자동 감지: 사용 가능한 첫 시작 자격 증명으로 폴백합니다. 순서는 OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, GOOGLE_CLOUD_PROJECT (Gemini Enterprise Agent Platform).

이 시작 폴백은 의도적으로 이 네 개 자격 증명만 확인해요. 다른 지원 제공자(Groq 등)는 여전히 --model, /model, 저장된 기본값([models].default / [models].recent)으로 쓸 수 있어요.

스위처에 나타나는 모델

/model 선택기는 설치된 제공자 패키지에서 목록을 동적으로 구성해요. 자세한 기준과 문제 해결은 아래를 참고하세요.

스위처가 모델 목록을 만드는 방식

대화형 /model 선택기는 설치된 제공자 패키지와 config.toml에 구성된 모델에서 목록을 만들어요. 모델은 다음 조건일 때 나타나요:

제공자 패키지가 설치됨
모델이 제공자 패키지, 로컬 제공자, 또는 config.toml에서 사용 가능
모델 프로파일이 텍스트 입력·출력을 미지원으로 표시하지 않음

모델이 없다면 /model <provider>:<model>로 직접 쓰거나 [models.providers.<name>].models에 추가하세요.

자격 증명 상태는 모델이 나열되는지에 영향을 주지 않습니다. 자격 증명이 없는 모델도 선택할 수 있고, 요청 시점에 제공자가 인증 오류를 보고합니다.

오픈 웨이트 모델

오픈 웨이트(open weights) 모델을 쓰고 싶다면, 로컬 또는 클라우드 호스팅 추론 중 어느 쪽을 선호하느냐에 따라 두 가지 흔한 경로가 있어요.

Ollama로 로컬 추론 — API 키 없이 무료로 시작하기 가장 쉬운 방법이에요:

Ollama 설치하고 모델을 pull해요:
```
ollama pull qwen3:4b
```
Ollama extra를 설치해요:
```
/install ollama
```
```
dcode --install ollama
```
모델을 선택해요:
```
/model
```
```
dcode --model ollama:qwen3:4b
```
대화형 스위처를 쓰거나 /model ollama:qwen3:4b로 직접 전달해요.

Groq로 클라우드 호스팅 오픈 웨이트 — 로컬에서 아무것도 실행하지 않고 빠른 추론을 얻는 방법이에요:

console.groq.com에서 무료 API 키를 받아요.
Groq extra를 설치해요:
```
/install groq
```
```
dcode --install groq
```
모델을 선택해요:
```
/model
```
```
GROQ_API_KEY="your-api-key" dcode --model groq:openai/gpt-oss-120b
```
대화형 스위처를 쓰거나 /model groq:openai/gpt-oss-120b로 직접 전달해요.

Fireworks — 오픈 웨이트 모델용으로 인기 있는 또 다른 클라우드 제공자예요:

/install fireworks
/model

dcode --install fireworks
FIREWORKS_API_KEY="your-api-key" dcode --model fireworks:accounts/fireworks/models/deepseek-v4-pro

대화형 스위처를 쓰거나 /model fireworks:accounts/fireworks/models/deepseek-v4-pro로 직접 전달해요.

Baseten — 오픈 웨이트 모델용 또 다른 클라우드 제공자예요:

/install baseten
/model

dcode --install baseten
BASETEN_API_KEY="your-api-key" dcode --model baseten:moonshotai/Kimi-K2.7-Code

대화형 스위처를 쓰거나 /model baseten:moonshotai/Kimi-K2.7-Code로 직접 전달해요.

초기 설치 시 CLI와 함께 제공자를 미리 설치하고 싶다면 DEEPAGENTS_CODE_EXTRAS를 사용하세요:

DEEPAGENTS_CODE_EXTRAS="fireworks" curl -LsSf https://langch.in/dcode | bash

여러 제공자를 합칠 수 있어요: DEEPAGENTS_CODE_EXTRAS="groq,fireworks,ollama". Deep Agents Code가 이미 설치됐다면 세션에서 /install <extra>를, 셸에서 dcode --install <extra>를 쓰세요.

Together, OpenRouter, Hugging Face(langchain-huggingface)는 클라우드 호스팅 오픈 웨이트의 다른 옵션이에요. 자격 증명과 패키지 이름은 Provider reference를 참고하세요.

기본 모델 설정

향후 모든 CLI 시작에 적용되는 영구 기본 모델을 설정할 수 있어요.

모델 선택기: /model을 열고 원하는 모델로 이동한 뒤 Ctrl+S로 기본값을 고정해요. 현재 기본값에서 Ctrl+S를 다시 누르면 해제돼요.
명령: /model --default provider:model (예: /model --default anthropic:claude-opus-4-8)
구성 파일: ~/.deepagents/config.toml에 [models].default 설정 (Configuration 참고)

셸에서:

dcode --default-model anthropic:claude-opus-4-8

현재 기본값을 보려면:

dcode --default-model

기본값을 지우려면:

셸에서:
```
dcode --clear-default-model
```
명령: /model --default --clear
모델 선택기: 현재 고정된 기본 모델에서 Ctrl+S 누르기

기본값이 없으면 Deep Agents Code는 가장 최근 사용한 모델을 사용해요.

모델 파라미터

모델에 추가 생성자 kwarg를 전달할 수 있어요 — 샘플링 컨트롤, 추론/사고 예산, 컨텍스트 윈도우 크기, 요청 타임아웃, 그리고 기저 채팅 모델 클래스가 받는 그 밖의 것까지. 설정 위치는 우선순위 순으로 세 곳이에요:

시작 시 --model-params로 일회성 설정 — JSON 문자열, 세션 전용:

# OpenAI reasoning effort
dcode --model openai:gpt-5.5 --model-params '{"reasoning": {"effort": "high"}}'

# Anthropic extended thinking
dcode --model anthropic:claude-opus-4-8 --model-params '{"thinking": {"type": "enabled", "budget_tokens": 10000}, "max_tokens": 16000}'

세션 중 /model --model-params — 같은 JSON 문법으로, 재시작 없이 파라미터(선택적으로 모델도)를 교체해요:

/model --model-params '{"temperature": 0.7}' anthropic:claude-opus-4-8
/model --model-params '{"num_ctx": 16384}'           # opens selector, applies params to choice

config.toml에 영구 저장 — 매 시작에 적용되는 제공자 수준 기본값(선택적으로 모델별 하위 테이블 포함):

[models.providers.anthropic.params]
thinking = { type = "enabled", budget_tokens = 10000 }
max_tokens = 16000

[models.providers.openai.params]
reasoning = { effort = "high", summary = "auto" }
output_version = "responses/v1"

[models.providers.ollama.params]
num_ctx = 16384
temperature = 0

# Per-model override—wins over provider-level keys
[models.providers.ollama.params."qwen3:4b"]
temperature = 0.5

CLI 플래그는 config 파일 params를 덮어쓰고 세션 전용이에요(세션 중 변경은 저장되지 않아요). config.toml의 모델별 하위 테이블은 제공자 수준 키를 덮어써요(shallow merge — 자세한 의미는 Model constructor params 참고). --model-params는 --default와 함께 쓸 수 없어요.

재시도 횟수는 --max-retries 또는 최상위 [retries] 구성을 선호해요.

기저 채팅 모델 생성자가 받는 어떤 kwarg든 유효합니다. 전체 목록은 제공자의 레퍼런스 문서를 참고하세요 — 예: ChatAnthropic, ChatOpenAI, ChatOllama. 알려지지 않은 kwarg는 업스트림 API 요청으로 전달되므로, 새로 출시된 파라미터도 CLI 업데이트 없이 동작합니다.

자격 증명(api_key)을 params에 두지 마세요. 대신 api_key_env로 환경 변수를 가리키는 게 좋습니다.

런타임 프로파일(max_input_tokens, tool_calling, 기능 플래그)의 필드를 생성자 파라미터와 별개로 덮어쓰려면 Profile overrides를 참고하세요.

고급 구성

제공자 파라미터, 프로파일 오버라이드, 커스텀 base URL, 호환 API, 임의 제공자, 수명주기 훅의 상세 구성은 Config file과 Hooks 문서를 참고하세요.

더 알아보기 (Learn more)

Config file — 제공자 파라미터와 프로파일 오버라이드의 상세 구성.
Provider credentials — API 키 해석 순서와 자격 증명 관리.
Hooks — 제공자 수명주기 훅 설정.
Configuration — 환경 변수와 DEEPAGENTS_CODE_ prefix 전반.