Claude Code와 Codex에서 Kimi K3.1 Pro 실행하기: 설정, 조용한 실패, 그리고 한 줄 전환

Kimi K3.1 Pro는 세 가지 프로토콜을 지원합니다: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages. 이것이 번역 프록시 없이 Claude Code와 Codex에 그대로 투입될 수 있는 이유 전부입니다. 각 도구는 이미 세 가지 중 하나를 사용하고, Moonshot은 해당 프로토콜을 기본으로 제공합니다. 설정은 한쪽의 경우 환경 변수 몇 개이고, 다른 쪽은 다섯 줄짜리 TOML 블록입니다. 사람들이 반나절을 허비하는 부분은 설정이 아니라 실패 방식입니다. Claude Code는 작업별로 네 가지 모델 티어를 사용하며, 설정하지 않은 티어는 크게 실패하지 않고 조용히 실패합니다.

이 가이드는 Moonshot 자체 통합 문서를 바탕으로 2026년 10월 24일에 확인하여 작성했으며, 문서가 묻어두는 주의사항도 담고 있습니다. 동일한 도구를 Moonshot에 직접 연결하지 않고 라우팅 게이트웨이에 연결할 때 값이 달라지는 경우에는 그 사실을 별도로 명시합니다.

프록시가 필요 없는 이유

Claude Code talks to Anthropic's Messages API; Codex talks to the Responses API. Moonshot exposes both. Its Anthropic-compatible surface lives at https://api.moonshot.ai/anthropic and its Responses API at https://api.moonshot.ai/v1, and the model id is kimi-k3.1-pro on both. Nothing in either client needs to know it is not talking to the vendor it was built for.

설정에 앞서 짚고 넘어갈 점이 하나 있습니다: 이 모델은 항상 추론합니다. 사고 토글은 없으며, 깊이는 최상위 reasoning_effort 필드로 설정하는데 low, high, max를 받고 기본값은 max입니다. 샘플링 매개변수는 고정되어 있습니다 — temperature 1.0, top-p 0.95, n은 1 — 다른 값을 전달하면 오류가 반환됩니다. 이전 설정에서 temperature를 조정했다면, 그 조정은 이번 전환 후에도 유지되지 않습니다.

Claude Code: 환경 블록

Claude Code는 구성을 env 블록에서 읽습니다: ~/.claude/settings.json. 거기에 기록된 변수는 셸에서 내보낸 동일한 이름의 변수를 덮어씁니다. 이는 기능이자 함정입니다. 터미널의 오래된 export는 파일이 다른 값을 담고 있다면 구해 주지 못합니다.

• ANTHROPIC_BASE_URL — the Kimi endpoint root. Set it to https://api.moonshot.ai/anthropic. If you leave it unset, requests go to Anthropic and fail authentication.

• ANTHROPIC_AUTH_TOKEN — 사용자의 Kimi API 키입니다. Claude Code가 베어러 토큰에 실제로 사용하는 변수이며, API 키를 ANTHROPIC_API_KEY에 대신 넣는 것이 올바르게 보이는 구성이 401을 반환하는 가장 흔한 이유입니다.

• ANTHROPIC_MODEL — 주요 대화 모델: kimi-k3.1-pro.

• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL — 각 티어당 하나씩입니다. 최소한 처음 세 개를 설정하고, HAIKU는 플래그십이 아니라 저렴하고 빠른 모델로 지정하세요. Moonshot의 자체 예시에서는 해당 티어를 코딩 모델에 매핑합니다.

• CLAUDE_CODE_SUBAGENT_MODEL — 서브에이전트가 사용하는 모델입니다. 설정하지 않으면 서브에이전트 작업이 저하되거나 실패합니다.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW — 컨텍스트 창에 맞춰 1000000(으)로 설정하세요. 너무 작으면 일찍 압축되어 컨텍스트를 버리게 되고, 너무 크면 컨텍스트 길이 오류가 발생합니다.

• CLAUDE_CODE_EFFORT_LEVEL — Moonshot의 가이드에서는 이 값을 max로 설정하는데, 이는 모델의 기본값이기도 합니다. 값을 낮추면 복잡한 작업에서 품질이 저하되고, 세션 도중에 변경하면 프리픽스 캐시 적중이 무효화됩니다.

조용히 실패하는 네 가지 계층

이것은 대비할 가치가 있는 실패입니다. Claude Code는 기본 대화, 배경 요약, 하위 에이전트, 소규모 유틸리티 호출에 서로 다른 모델을 사용합니다. ANTHROPIC_MODEL만 구성하면 다른 경로들은 오류를 내지 않습니다 — 조용히 아무 유용한 일도 하지 않거나, 원인을 밝히지 않은 채 도구가 고장 난 것처럼 느껴지는 방식으로 폴백합니다. Moonshot의 참조 표는 설정되지 않은 각 계층이 해당 작업을 실패하게 만든다고 분명히 밝히며, 증상은 구성 오류라기보다 느리거나 혼란스러운 에이전트처럼 보입니다.

실용적인 체크리스트는 네 가지 티어 변수와 서브 에이전트 변수를 한 번의 편집으로 모두 설정하고, Claude Code를 재시작한 다음, 세션에서 서브 에이전트가 실제로 실행되는지 확인하는 것입니다. 멈춘다면 가장 먼저 확인할 것은 모델이 아니라 티어입니다.

Codex: TOML 블록 하나

Codex reads ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml). The connection is defined by four values in a provider block: the model id kimi-k3.1-pro, a provider named kimi, base_url pointing at https://api.moonshot.ai/v1, the environment-variable name that holds the key, and — the setting that makes the direct connection work — wire_api = "responses". Set model_context_window to 1048576 as well; without it Codex falls back to default model metadata, which degrades behaviour on long inputs.

키 자체는 파일이 아니라 환경에 있어야 합니다. Codex는 env_key에 지정된 변수에서 키를 읽으므로, config.toml에는 비밀을 두지 말고 셸 프로필이나 시스템 환경에서 해당 변수를 설정하세요.

버그를 제출하기 전에 알아야 할 두 가지 제한이 있습니다. Codex CLI는 모델이 지원하는데도 비디오를 입력으로 받지 않습니다. 이는 Codex 입력 계층의 한계이므로 비디오 작업은 API를 직접 거쳐야 합니다. 또한 Codex 자체의 컨텍스트 관리도 여전히 적용됩니다. 1M 토큰 창이 있다고 해서 모든 세션이 그 창을 다 써야 하는 것은 아닙니다.

대신 두 도구를 하나의 게이트웨이로 향하게 하기

위의 모든 내용은 Moonshot의 기본 URL을 게이트웨이의 URL로 바꿔도 그대로 작동하며, 동일한 코드베이스에서 다른 공급업체의 모델도 호출하는 경우에 유용합니다. OrcaRouter는 Kimi K3.1 Pro를 위한 세 가지 인터페이스를 모두 제공합니다 — /v1/chat/completions, /v1/responses 및 /v1/messages — 그리고 해당 모델을 kimi/kimi-k3.1-pro라는 id로 게시합니다.

For Claude Code, that means ANTHROPIC_BASE_URL set to the gateway root (https://api.orcarouter.ai) with the provider-prefixed model id in the four tier variables. For Codex, the same TOML block with the base URL pointing at https://api.orcarouter.ai/v1 and the model id kimi/kimi-k3.1-pro. The key variable stays the same shape; it just holds a gateway key instead of a vendor key.

이 대체로 얻는 것은 카탈로그의 모든 모델에 사용할 수 있는 하나의 자격 증명과, 애플리케이션 코드를 변경하지 않고도 공급업체 간에 요청을 이동할 수 있는 라우팅 정책입니다 — 새 모델의 엔드포인트가 출시 주간에 속도 제한을 걸 때 폴백 계획을 가능하게 해 주는 바로 그 요소입니다. 포기하는 것은 공급업체 자체 콘솔과 공급업체별 베타 표면입니다. 가격은 공급자의 목록 가격으로 그대로 전달됩니다: Kimi K3.1 Pro의 경우 입력 토큰 100만 개당 $2.00, 출력 토큰 100만 개당 $10.00이며, 마크업은 추가되지 않습니다.

5분 검증

• 클라이언트를 건드리기 전에 엔드포인트를 직접 호출하세요. Messages 또는 Chat Completions 라우트에 1토큰 요청으로 POST를 보내면 JSON이 반환되어야 하며, 401이 나온다면 키가 잘못되었거나 다른 플랫폼에 속한 키입니다.

• Claude Code에서 여러 파일을 검색하는 하위 에이전트를 반드시 실행하게 만드는 질문을 던지고, 그것이 완료되는지 지켜보세요. 이것이 티어 구성을 가장 빠르게 테스트하는 방법입니다.

• Codex에서 작은 저장소로 세션을 시작하고 모델이 1M 윈도를 보고하는지 확인하세요. 더 작은 기본값을 보고한다면, model_context_window가 적용되지 않은 것입니다.

• 세션 시작 시 단 한 번, 의도적으로 에포트(effort) 수준을 설정하세요: 어려운 디버깅에는 max, 일반적인 편집에는 high, 추출 및 포맷팅에는 low. 기본값은 max이며, 이 모델에서는 그것이 비용이 많이 드는 선택입니다.