Claude Agent SDK

SDK에서 base_url 옵션을 검색해도 아무것도 나오지 않습니다. 문서에서 빠진 것이 아니라 해당 옵션이 존재하지 않기 때문입니다. SDK는 Claude Code CLI를 하위 프로세스로 실행하며, ANTHROPIC_BASE_URL와 ANTHROPIC_AUTH_TOKEN을 읽는 것은 CLI입니다. 이 두 변수를 설정하면 에이전트 코드를 변경하지 않아도 에이전트의 모든 호출이 해당 경로로 전달됩니다.

# The SDK has no base_url option. The CLI it spawns reads these, and the
# SDK passes the parent environment straight through — so exporting them
# before your program starts is enough.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Pin models Kunavo serves: the CLI's default and its opus/sonnet aliases
# follow Anthropic's newest models, and the sonnet alias asks for Sonnet 5.5,
# which Kunavo does not serve — unpinned, those requests 404.
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

python my_agent.py

환경 변수가 CLI에 전달되는 이유

이 부분은 한 문단을 할애할 만합니다. 작동이 멈출 수도 있는 요령인지, 문서화된 속성이라 믿고 기반을 구축할 수 있는지의 차이이기 때문입니다. Python SDK의 하위 프로세스 전송은 부모의 os.environ에서 키 하나를 제외한 환경을 자식 환경으로 구성합니다. CLAUDECODE를 제외해 자식이 Claude Code 세션 안에서 실행 중이라고 판단하지 않게 한 뒤, CLAUDE_CODE_ENTRYPOINT, ClaudeAgentOptions.env를 병합하고 SDK 버전을 추가합니다.

여기서 두 가지를 알 수 있으며, 두 번째는 자주 오해하는 부분입니다. 셸에 있는 모든 항목이 CLI에 전달되므로 두 변수를 export해도 됩니다. 또한 options.env는 상속된 환경 위에 병합되므로 명시적으로 지정한 값이 오래된 export 값보다 우선합니다. 오래된 값에 밀리지 않습니다. 코드는 subprocess_cli.py에 있습니다.

명시적 설정 방식과 이를 반드시 사용해야 하는 경우

내보낸 변수는 개인 컴퓨터에서는 괜찮지만 다른 환경에서는 불안정합니다. 에이전트의 엔드포인트가 프로세스 실행 방식에 따라 달라져, 프로필을 불러오지 않는 스케줄러, 컨테이너 또는 CI 작업에서 처음 실행할 때 문제가 발생합니다. 옵션 객체에 env를 전달하면 라우팅이 프로그램의 일부가 됩니다.

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# The explicit form. options.env is merged ON TOP of the inherited
# environment, so this wins over whatever the shell happens to hold —
# which is what you want in anything that is not your own laptop.
options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
        "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
        "ANTHROPIC_MODEL": "claude-sonnet-5",
        "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
        "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
        "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5",
    },
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Summarise the open TODOs in this repo")
    async for message in client.receive_response():
        print(message)

단계별 안내

1. /app/keys에서 키를 생성해 복사하세요. 키는 한 번만 표시됩니다.
2. 라우팅을 어디에 둘지 정하세요. 로컬 작업에는 내보낸 변수를, 무인 실행 작업에는 ClaudeAgentOptions(env=…)를 사용하세요.
3. ANTHROPIC_BASE_URL를 https://api.kunavo.com로 설정하고, ANTHROPIC_AUTH_TOKEN를 sk-kn-… 키로 설정하세요.
4. ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL 및 ANTHROPIC_DEFAULT_SONNET_MODEL를 제공되는 ID로 설정하세요. CLI의 내장 기본값과 opus, sonnet 별칭은 Anthropic의 최신 모델을 따르며, Kunavo가 제공하지 않는 모델인 Sonnet 5.5를 sonnet 별칭이 요청하면 404가 반환됩니다.
5. 선택적으로 ANTHROPIC_DEFAULT_HAIKU_MODEL를 설정하면 CLI가 실행하는 백그라운드 하위 작업을 가장 저렴한 티어로 보낼 수 있습니다.
6. 프로그램을 실행하세요. 에이전트 코드에는 변경 사항이 없습니다.

하위 작업별 티어 선택

에이전트는 여러 작업을 동시에 수행합니다. 하나의 요청이 청구 대상 왕복 호출 여러 건으로 늘어나므로, 티어 매핑은 채팅 앱보다 여기서 더 중요합니다. 요금은 카탈로그에서 실시간으로 가져온 토큰 1M개당 USD 기준이며, 입력/출력 순서입니다.

SDK 문제를 디버깅하기 전에 확인하세요

요청 한 번이면 문제가 키, 엔드포인트 또는 SDK 중 어디에 있는지 판단할 수 있습니다. 이 요청이 200을 반환하면 SDK가 실행하는 CLI에서도 같은 자격 증명이 작동합니다. 그래도 문제가 있다면 변수의 값이 아니라 변수가 설정된 위치를 확인해야 합니다.

# Settles whether a failure is the key, the endpoint, or the SDK.
# 200 here means the same credential works for the CLI the SDK spawns.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

참고 자료

SDK는 anthropics/claude-agent-sdk-python에서 오픈 소스로 제공됩니다. 여기에 설명된 환경 동작은 자체 하위 프로세스 전송 코드에서 확인했으며, 확인 날짜는 2026-09-04입니다. TypeScript SDK도 같은 아키텍처로 작동합니다. API를 직접 호출하지 않고 CLI를 구동하므로 라우팅 변수도 CLI가 읽습니다. README에는 옵션이나 동작 방식이 설명되어 있지 않으므로, 명시적 설정 방식에 의존하기 전에 해당 SDK의 타입 정의에서 옵션 이름을 확인하세요. Kunavo는 Messages API를 제공하며, 같은 방식으로 라우팅하는 다른 클라이언트는 통합 허브에서 확인할 수 있습니다.