코딩 에이전트 설정하기

코딩 에이전트 설정하기 (Set up coding agents)

LLM 호출이 LLM Gateway를 통해 라우팅되도록 Claude Code, Codex, Gemini CLI, Deep Agents Code를 구성해요.

참고: LLM Gateway는 베타 단계예요.

중앙 집중식 비용 제어, 관측성, 감사 추적을 위해 코딩 에이전트가 표준 LLM Gateway 엔드포인트를 사용하도록 구성하세요. 게이트웨이는 각 호출자를 인증하고, 모델 ID로 라우팅하며, 정책을 집행하고, 각 호출을 추적해요.

Claude Code는 표준 Anthropic Messages 형식을 사용할 수 있고, Codex와 Deep Agents Code는 표준 OpenAI 호환 형식을 사용할 수 있어요. Gemini CLI는 Google의 네이티브 API를 사용하며 직접 모델 접근이 필요해요.

사전 준비사항 (Prerequisites)

클라이언트를 구성하기 전에 LangSmith API 키를 설정하세요:

export LANGSMITH_API_KEY="lsv2_..._....cbed3e"

Claude Code CLI

Claude Code는 두 가지 별도 인증 방법을 지원해요. 구성 전에 하나를 선택하세요:

  • 워크스페이스 프로바이더 시크릿: 조직이 워크스페이스 시크릿에 저장된 프로바이더 키로 청구와 정책을 관리해요. 조직 관리 사용량에는 이 방법을 사용하세요.
  • Claude 구독 OAuth: Anthropic이 워크스페이스 프로바이더 시크릿 대신 사용자의 개인 Claude Plus 또는 Max 구독에 LLM 호출을 청구하면서도, LangSmith가 게이트웨이 권한, 정책, 추적을 여전히 집행해요. 개발자가 자신의 구독을 갖고 있을 때 이 방법을 사용하세요.

워크스페이스 프로바이더 시크릿 사용하기 (Use a workspace provider secret)

ANTHROPIC_API_KEY를 LangSmith API 키로 설정하세요. Claude Code는 셸 환경 또는 --settings로 전달된 설정 파일의 env 블록에서 이 변수들을 읽어요.

LangSmith 배포가 리전 또는 셀프 호스팅 인스턴스에 있다면 아래 예시의 게이트웨이 호스트명을 여러분의 리전 게이트웨이 호스트명으로 교체하세요.

Anthropic 모델만 사용하기 (Use Anthropic models only)

ANTHROPIC_BASE_URL을 Anthropic 형식 게이트웨이 엔드포인트로 설정하세요. 게이트웨이는 엔드포인트에서 anthropic/ 프로바이더 접두사를 추론해요.

설정 파일 (권장)

--settings 파일에 선언된 변수는 셸에 이미 export된 어떤 것보다 우선하므로, 게이트웨이 URL과 API 키가 여러분의 환경에 이미 설정되어 있을 수 있는 주변 ANTHROPIC_* 값(예: 전역 셸 프로파일이나 다른 도구에서 온 것)을 확실히 덮어써요.

touch ~/.claude/langsmith_gateway.settings.json
echo '{"env": {"ANTHROPIC_BASE_URL": "https://gateway.smith.langchain.com/anthropic/","ANTHROPIC_API_KEY": "YOUR_LANGSMITH_KEY_HERE"}}' > ~/.claude/langsmith_gateway.settings.json
claude --settings ~/.claude/langsmith_gateway.settings.json

YOUR_LANGSMITH_KEY_HERE를 LangSmith API 키로 교체하세요.

환경 변수

export ANTHROPIC_BASE_URL="https://gateway.smith.langchain.com/anthropic/"
export ANTHROPIC_API_KEY="$LANGSMITH_API_KEY"

claude

프로바이더 전반에 모델 티어 라우팅하기 (Route model tiers across providers)

ANTHROPIC_BASE_URL을 게이트웨이 루트로 설정한 다음 각 Claude 모델 티어를 프로바이더 접두사가 붙은 게이트웨이 모델 ID에 매핑하세요.

설정 파일 (권장)

--settings 파일에 선언된 변수는 셸에 이미 export된 어떤 것보다 우선하므로, 게이트웨이 URL, API 키, 모델 매핑이 주변 ANTHROPIC_* 값을 확실히 덮어써요.

touch ~/.claude/langsmith_gateway.settings.json
echo '{"env": {"ANTHROPIC_BASE_URL": "https://gateway.smith.langchain.com","ANTHROPIC_API_KEY": "YOUR_LANGSMITH_KEY_HERE","ANTHROPIC_DEFAULT_OPUS_MODEL": "anthropic/claude-opus-5","ANTHROPIC_DEFAULT_SONNET_MODEL": "openai/gpt-5.6-terra","ANTHROPIC_DEFAULT_HAIKU_MODEL": "fireworks/accounts/fireworks/models/glm-5p2"}}' > ~/.claude/langsmith_gateway.settings.json
claude --settings ~/.claude/langsmith_gateway.settings.json

YOUR_LANGSMITH_KEY_HERE를 LangSmith API 키로 교체하세요.

환경 변수

export ANTHROPIC_BASE_URL="https://gateway.smith.langchain.com"
export ANTHROPIC_API_KEY="$LANGSMITH_API_KEY"
export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="openai/gpt-5.6-terra"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="fireworks/accounts/fireworks/models/glm-5p2"

claude

모델 ID는 예시예요. 각 티어를 워크스페이스 시크릿에 구성된 또는 Gateway Credits로 사용 가능한 모든 모델에 매핑하세요; 게이트웨이가 프로바이더 전반의 요청 번역을 처리해요. 자세한 내용은 API 형식을 참고하세요.

Claude 구독 OAuth 사용하기 (Use Claude subscription OAuth)

참고: Claude 구독 OAuth는 활성 Claude Code Plus 또는 Max 구독이 필요해요. 워크스페이스 Anthropic API 키를 사용한다면 대신 워크스페이스 프로바이더 시크릿 방법을 사용하세요.

Claude Code Plus 및 Max 사용자는 저장된 Anthropic OAuth 자격 증명을 게이트웨이를 통해 보낼 수 있어요. 이 모드는 워크스페이스 프로바이더 시크릿에 ANTHROPIC_API_KEY가 필요하지 않아요.

구독으로 Claude Code에 로그인한 다음 게이트웨이를 구성하세요.

설정 파일 (권장)

--settings 파일에 선언된 변수는 셸에 이미 export된 어떤 것보다 우선하므로, 게이트웨이 URL과 커스텀 헤더가 주변 ANTHROPIC_* 값을 확실히 덮어써요. 설정 파일은 또한 LangSmith API 키를 셸 히스토리와 dotfiles에서 벗어나게 유지해요.

touch ~/.claude/langsmith_gateway.settings.json
echo '{"env": {"ANTHROPIC_BASE_URL": "https://gateway.smith.langchain.com/anthropic","ANTHROPIC_CUSTOM_HEADERS": "X-Api-Key: YOUR_LANGSMITH_KEY_HERE"}}' > ~/.claude/langsmith_gateway.settings.json
claude --settings ~/.claude/langsmith_gateway.settings.json

YOUR_LANGSMITH_KEY_HERE를 LangSmith API 키로 교체하세요.

환경 변수

export ANTHROPIC_BASE_URL="https://gateway.smith.langchain.com/anthropic"
export ANTHROPIC_CUSTOM_HEADERS="X-Api-Key: $LANGSMITH_API_KEY"

claude

ANTHROPIC_CUSTOM_HEADERS 값을 시크릿으로 취급하세요: LangSmith API 키를 포함하므로 셸 히스토리, dotfiles, 공유 구성에서 벗어나게 유지하세요.

Claude Code는 저장된 로그인에서 OAuth 자격 증명을 사용하고 갱신하며, anthropic-beta 헤더에 필요한 OAuth capability를 포함해요.

LangSmith API 키는 게이트웨이 요청을 인증하고 게이트웨이 권한과 정책의 적용을 받아요. 게이트웨이는 OAuth 베어러를 Anthropic으로 전달하므로 Anthropic은 호출을 워크스페이스 프로바이더 시크릿 대신 사용자의 Claude 구독에 청구해요. 호출이 게이트웨이를 통해 라우팅되는지 확인하려면 설정 검증에 설명된 대로 gateway 추적 프로젝트에 추적이 나타나는지 확인하세요.

경고: 이 모드에서는 ANTHROPIC_AUTH_TOKEN과 ANTHROPIC_API_KEY를 설정 해제로 두세요. 두 변수 중 하나라도 저장된 구독 로그인보다 우선해요.

경고: 게이트웨이가 구성되면 Claude Desktop 플러그인이 깨져요.

Codex CLI

Codex는 Responses API를 사용해요. 표준 엔드포인트를 통해 Gateway Credits로 호스팅 Kimi K3 모델을 호출하려면 ~/.codex/config.toml에 다음을 추가하세요:

model = "moonshotai/kimi-k3"
model_provider = "langsmith-gateway"

[model_providers.langsmith-gateway]
name = "LangSmith Gateway"
base_url = "https://gateway.smith.langchain.com/v1"
env_key = "LANGSMITH_API_KEY"
wire_api = "responses"
supports_websockets = false

그런 다음 실행:

codex

bring-your-own-key 모델을 사용하려면 model을 프로바이더 접두사가 붙은 ID(예: openai/gpt-5.4-mini)로 교체하세요.

경고: 게이트웨이가 구성되면 Codex Desktop 플러그인이 깨져요. TOML 구성이 게이트웨이를 통한 인증을 강제하므로 OpenAI가 더 이상 플러그인 인증을 직접 처리하지 않아요.

Gemini CLI

Gemini CLI는 표준 엔드포인트가 노출하지 않는 Google의 네이티브 Generate Content 요청을 보내요. /gemini 라우트를 구성하려면 직접 모델 접근을 따르세요. 그런 다음 실행:

gemini

Deep Agents Code

표준 엔드포인트로 OpenAI 호환 클라이언트를 사용한 다음 openai 통합을 통해 호스팅 모델 슬러그를 전달하세요:

export OPENAI_BASE_URL="https://gateway.smith.langchain.com/v1"
export OPENAI_API_KEY="$LANGSMITH_API_KEY"

dcode --model openai:moonshotai/kimi-k3

bring-your-own-key 모델을 사용하려면 표준 기본 URL을 유지하고 openai: 뒤에 프로바이더 접두사 모델을 전달하세요. 예: openai:anthropic/claude-opus-5. 프로바이더 네이티브 통합과 모델 ID는 직접 모델 접근을 참고하세요.

회사 전역 배포 (Company-wide deployment)

게이트웨이를 모든 개발자에게 롤아웃하는 조직의 경우 모바일 디바이스 관리 또는 공유 셸 프로파일을 통해 구성을 배포하세요. 다음을 배포하세요:

  1. 각 클라이언트에 대한 표준 게이트웨이 기본 URL.
  2. 정책 세밀도에 따라 사용자 또는 팀별 워크스페이스 범위 LangSmith API 키.
  3. 각 코딩 에이전트에 승인된 모델 ID.
  4. 조직이 Codex를 사용한다면 Codex config.toml.

프로바이더 API 키는 LangSmith 워크스페이스 시크릿에 중앙 집중화됩니다. Gateway Credits 모델은 프로바이더 API 키가 필요 없어요.

설정 검증 (Verify the setup)

코딩 에이전트를 구성한 후 테스트 호출을 만들고 다음을 확인하세요:

  1. 호출이 성공하고 에이전트가 응답을 받는다.
  2. LangSmith 워크스페이스의 gateway 또는 gateway-<short_api_key>-<api_key_id> 추적 프로젝트에 추적이 나타난다.

403으로 호출이 실패하면 API 키의 역할에 gateway:invoke와 workspaces:read가 포함되어 있는지 확인하세요. 프로바이더 키 누락을 언급하는 400으로 bring-your-own-key 호출이 실패하면 조직 관리자에게 프로바이더 키를 워크스페이스 시크릿에 추가하도록 요청하세요.

다음 단계 (Next steps)

출처: 문서

더 알아보기 (Learn more)