모델 설정

모델 설정 (Set Up a Model)

대부분의 에이전트는 생각할 모델이 필요해요: 내장 클라우드 제공자를 연결하거나, Docker Model Runner로 모델을 로컬에서 실행하거나, 커스텀 OpenAI 호환 엔드포인트를 등록해요. 이 페이지는 각 경로를 끝에서 끝까지 안내해요 — 더하기 예외: Claude 구독에서 Claude Code CLI로 위임하는 에이전트는 전혀 모델이 필요하지 않아요.

출처: 문서

본문

경로 선택 (Pick a Path)

	Built-in cloud provider (Path A)	Local model (Path B)
필요	계정과 자격 증명 (보통 API 키)	Model Runner가 활성화된 Docker Desktop
비용	토큰당 지불	모델 다운로드 후 무료
데이터	제공자에게 전송	당신의 머신을 떠나지 않음
모델 품질	프런티어 모델 (Claude, GPT-5, Gemini)	하드웨어에 맞는 오픈 모델

둘 다 설정할 수 있어요. 모델을 이름 짓지 않으면 Docker Agent의 자동 선택이 구성된 자격 증명을 가진 첫 클라우드 제공자를 고르고 로컬로 풀린 Docker Model Runner 모델로 폴백해요.

두 가지 경로가 나머지 경우를 다뤄요: 모델이 자신의 OpenAI 호환 엔드포인트(vLLM, LiteLLM, 기업 게이트웨이) 뒤에 있다면 base URL과 함께 커스텀 엔드포인트로 등록하고(Path C), Claude 구독 을 갖고 있다면 Claude Code harness(Path D)가 API 키도 로컬 모델도 필요 없이 공식 claude CLI를 에이전트로 실행해요.

Tip 마법사가 더 좋으세요? docker agent setup 은 같은 선택을 대화형으로 안내해요: 내장 제공자를 고르고 자격 증명을 저장하고, Docker Model Runner를 확인해 로컬 모델을 풀고, 커스텀 OpenAI 호환 엔드포인트를 등록하거나, Claude Code harness를 설정. 이 페이지는 수동 버전이에요. CLI reference 참고.

경로 A: 내장 클라우드 제공자 (Path A: Built-in Cloud Provider)

Docker Agent는 많은 클라우드 제공자(Anthropic, OpenAI, Google Gemini, Groq, Hugging Face, AWS Bedrock, GitHub Copilot 등)를 내장 지원해요. 커스텀 제공자를 등록하는 대신 이름으로 선택할 수 있어요. docker agent setup 이 나열하는 제공자(Groq, Hugging Face 포함)는 미리 정의된 엔드포인트와 함께 와서, 제공자의 자격 증명을 설정하는 것으로 충분해요; 일부 다른 내장 별칭은 Azure OpenAI를 base_url 로 하는 리소스 엔드포인트 같은 수동 구성이 필요해요. 자격 증명은 보통 API 키이지만 항상 그런 건 아니에요: Hugging Face는 HF_TOKEN 토큰을, GitHub Copilot은 GITHUB_TOKEN 을, AWS Bedrock은 당신의 AWS 자격 증명을, 그리고 chatgpt 는 docker agent setup 을 통해 브라우저에서 ChatGPT 계정으로 로그인하며 붙여넣을 키가 없어요. 아래 단계들은 대부분의 제공자가 따르는 API 키 흐름을 보여줘요.

1. API 키 받기

제공자의 콘솔에서 키를 만들어요:

Provider	Environment variable	Get a key at
Anthropic	ANTHROPIC_API_KEY	console.anthropic.com
OpenAI	OPENAI_API_KEY	platform.openai.com
Google Gemini	GOOGLE_API_KEY	aistudio.google.com

API 키가 있는 다른 모든 제공자도 같은 방식으로 동작해요. 전체 목록, 각 제공자의 자격 증명 변수, 위에서 언급한 예외는 Model Providers 참고.

2. 키 저장

가장 빠른 옵션은 셸의 환경 변수예요:

$ export ANTHROPIC_API_KEY=sk-ant-...

그러면 현재 셸 세션 동안 지속돼요. 키를 한 번 설정하려면 다른 내장 시크릿 소스를 사용해요:

# Env file, passed at run time
$ echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env
$ docker agent run --env-from-file .env

# Docker Agent env file, read automatically on every run
# (`docker agent setup` writes it for you with owner-only permissions)
$ echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.config/cagent/.env
$ chmod 600 ~/.config/cagent/.env

항목 이름은 제공자가 기대하는 환경 변수와 일치해야 해요. Managing Secrets가 모든 소스(Docker Compose 시크릿, 자격 증명 헬퍼, 1Password 참조)와 그것들이 확인되는 순서를 다뤄요.

Important 키는 절대 agent.yaml 에 들어가지 않아요. env 파일을 쓰면 .gitignore 에 추가하세요.

3. 확인

docker agent doctor 는 키가 보이는지와 어디서 오는지 보여줘요:

$ docker agent doctor

User configuration
~/.config/cagent/config.yaml: ok

Model provider credentials
PROVIDER  STATUS    CREDENTIAL         SOURCE
anthropic found     ANTHROPIC_API_KEY  environment
openai    not set   OPENAI_API_KEY     -
...

Docker Model Runner
Status: not installed (https://docs.docker.com/ai/model-runner/get-started/)

Model auto-selection
auto -> anthropic/claude-sonnet-4-6

No issues found.

4. 실행

$ docker agent run

구성 파일이 없으면 기본 에이전트가 구성한 제공자를 골라요. 모델을 명시적으로 이름 지으려면 --model 또는 구성의 model 필드를 사용해요:

$ docker agent run --model anthropic/claude-sonnet-4-5

agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: A helpful coding assistant
    instruction: You are an expert software developer.

경로 B: 로컬 모델 (Docker Model Runner) — Path B: Local Model

Docker Model Runner (DMR)는 오픈 모델을 당신 자신의 머신에서 실행해요: API 키 없음, 토큰당 비용 없음, 프롬프트가 컴퓨터를 떠나지 않음.

1. Docker Model Runner 설치

Model Runner는 Docker Desktop에 포함되어 있어요(Settings > AI에서 활성화) Docker Engine에서도 사용 가능해요. 응답하는지 확인해요:

$ docker model status

명령이 없거나 실패하면 Model Runner get-started 가이드를 따르세요.

2. 모델 풀

$ docker model pull ai/qwen3

ai/qwen3 는 Docker Agent가 기본적으로 손을 대는 모델이지만, Docker Hub ai 카탈로그의 어떤 모델이든 동작해요. 머신 메모리에 맞는 크기를 고르세요. 로컬로 무엇이 있는지 나열해요:

$ docker model ls

3. 확인

$ docker agent doctor

User configuration
~/.config/cagent/config.yaml: ok

Model provider credentials
PROVIDER  STATUS   CREDENTIAL         SOURCE
anthropic not set  ANTHROPIC_API_KEY  -
...

Docker Model Runner
Status: reachable, 1 model(s) pulled:
- ai/qwen3:latest

Model auto-selection
auto -> dmr/ai/qwen3:latest

No issues found.

4. 실행

$ docker agent run --model dmr/ai/qwen3

또는 구성에서:

agents:
  root:
    model: dmr/ai/qwen3
    description: A local assistant
    instruction: You are a helpful assistant.

클라우드 키가 구성되지 않으면, 아무 플래그 없이 간단한 docker agent run 이 풀린 로컬 모델을 자동 선택하므로, docker model pull 후 플래그 없이 실행할 수 있어요. Docker Model Runner 제공자 페이지가 컨텍스트 크기, 런타임 플래그, 기타 튜닝 옵션을 다뤄요.

경로 C: 커스텀 OpenAI 호환 엔드포인트 (Path C: Custom OpenAI-compatible Endpoint)

모델이 자신의 엔드포인트(vLLM, LiteLLM, 기업 게이트웨이, API 프록시)에서 제공된다면 커스텀 제공자로 등록해요: base URL, API 형식, 필요하다면 API 키를 담는 환경 변수를 제공해요. Groq나 Hugging Face 같은 내장 제공자는 이게 필요 없어요; Path A를 쓰고 그 자격 증명을 설정하세요.

대화형 마법사가 가장 빠른 방법이에요:

$ docker agent setup # pick "Custom OpenAI-compatible endpoint"

또는 사용자 구성(~/.config/cagent/config.yaml)에서 제공자를 한 번 정의해요:

providers:
  myprovider:
    base_url: https://llm.corp.example.com/v1
    api_type: openai_chatcompletions
    token_key: MYPROVIDER_API_KEY

그 모델들은 모든 명령에서 동작해요:

$ docker agent models --provider myprovider
$ docker agent run --model myprovider/<model>

Per-agent-file 제공자와 게이트웨이 동작을 포함한 전체 참조는 Provider Definitions 참고.

경로 D: Claude Code Harness (Claude 구독) — Path D: Claude Code Harness (Claude Subscription)

이미 Claude 구독을 지불하고 있다면, 에이전트가 모델 API를 호출하는 대신 공식 Claude Code CLI로 작업을 위임할 수 있어요. 이것은 제공자 API 접근이 아닌 외부 CLI 이에요: Docker Agent가 claude 를 실행하고, claude 가 자신의 구독 로그인으로 인증해요 — ANTHROPIC_API_KEY 없음, Docker Model Runner 없음, 어떤 토큰도 Docker Agent를 통과하지 않아요.

1. 설치 및 로그인

Claude Code 를 설치하고, docker agent 를 실행하는 것과 같은 OS 사용자 및 환경으로 로그인해요:

$ claude auth login --claudeai # interactive, opens a browser
$ claude auth status --text # verify

2. harness 에이전트 생성

docker agent setup("Claude Code harness" 선택)이 이 파일을 생성하거나, 직접 써도 돼요:

# claude-code-agent.yaml
agents:
  root:
    description: Claude Code running on your Claude subscription
    harness:
      type: claude-code
      effort: medium # low | medium | high | xhigh | max; omit for the Claude Code default

3. 확인 및 실행

$ docker agent doctor claude-code-agent.yaml # checks the CLI is installed and logged in
$ docker agent run claude-code-agent.yaml

harness는 CLI를 비대화형으로 실행하고 Claude Code의 권한 프롬프트를 우회하므로, 신뢰하는 저장소에서만 사용하세요 — 보안 참고와 전체 필드 참조는 Coding Harnesses 참고.

언제든 설정 확인 (Check Your Setup Anytime)

docker agent doctor 는 어떤 제공자가 (어느 소스에서) 자격 증명을 가졌는지, Docker Model Runner가 도달 가능한지와 어떤 모델이 풀렸는지, auto 가 어떤 모델을 고를지 보고해요. 시크릿 값은 절대 출력되지 않아요.

$ docker agent doctor # credential, DMR, and auto-selection state
$ docker agent doctor ./agent.yaml # also check that file's requirements

실행을 막을 무언가가 있으면 0이 아닌 코드로 종료해 CI 프리플라이트로 사용할 수 있어요. CLI reference 참고.

다음은 무엇인가? (What's Next?)

Quick Start — 모델이 마련됐으니 첫 에이전트 실행.
Models — 인라인 vs. 이름 있는 모델, 폴백, 자동 선택.
Managing Secrets — 자격 증명을 저장하는 모든 방법 비교.
Troubleshooting — "no model available"과 자격 증명 에러 해석.

모델 설정

모델 설정 (Set Up a Model)

본문

경로 선택 (Pick a Path)

경로 A: 내장 클라우드 제공자 (Path A: Built-in Cloud Provider)

1. API 키 받기

2. 키 저장

3. 확인

4. 실행

경로 B: 로컬 모델 (Docker Model Runner) — Path B: Local Model

1. Docker Model Runner 설치

2. 모델 풀

3. 확인

4. 실행

경로 C: 커스텀 OpenAI 호환 엔드포인트 (Path C: Custom OpenAI-compatible Endpoint)

경로 D: Claude Code Harness (Claude 구독) — Path D: Claude Code Harness (Claude Subscription)

1. 설치 및 로그인

2. harness 에이전트 생성

3. 확인 및 실행

언제든 설정 확인 (Check Your Setup Anytime)

다음은 무엇인가? (What's Next?)

더 알아보기 (Learn more)