Running Kimi K3.1 Pro in Claude Code and Codex: The Config, the Silent Failures, and the One-Line Switch

Kimi K3.1 Pro speaks three protocols: OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. That is the whole reason it can drop into Claude Code and Codex without a translation proxy — each tool already speaks one of the three, and Moonshot serves that protocol natively. The setup is a handful of environment variables in one case and a five-line TOML block in the other. The part that costs people an afternoon is not the config; it is the failure mode. Claude Code uses four different model tiers for different jobs, and any tier left unset fails silently rather than loudly.

This guide is written from Moonshot's own integration documentation, checked on 24 October 2026, with the caveats the documentation buries. Where a value differs when you point the same tools at a routing gateway rather than at Moonshot directly, that is called out.

Why no proxy is needed

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.

One consequence is worth stating before the config: the model always reasons. There is no thinking toggle, and the depth is set with a top-level reasoning_effort field that accepts low, high and max, defaulting to max. Sampling parameters are fixed — temperature 1.0, top-p 0.95, n at 1 — and passing other values returns an error. If your previous setup tuned temperature, that tuning does not survive the switch.

Claude Code: the environment block

Claude Code reads its configuration from the env block of ~/.claude/settings.json. Variables written there override the same names exported in your shell, which is a feature and a trap: a stale export in your terminal will not save you if the file says something else.

• 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 — your Kimi API key. This is the variable Claude Code actually uses for the bearer token; an API key placed in ANTHROPIC_API_KEY instead is the most common reason a correct-looking config returns 401.

• ANTHROPIC_MODEL — the main conversation model: kimi-k3.1-pro.

• ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL — one per tier. Set the first three at minimum, and point HAIKU at a cheap fast model rather than at the flagship; Moonshot's own example maps that tier to its coding model.

• CLAUDE_CODE_SUBAGENT_MODEL — what sub-agents use. Unset, sub-agent work degrades or fails.

• CLAUDE_CODE_AUTO_COMPACT_WINDOW — set to 1000000, matching the context window. Too small compacts early and throws away context; too large produces context-length errors.

• CLAUDE_CODE_EFFORT_LEVEL — Moonshot's guide sets this to max, which is also the model's default. Lowering it reduces quality on complex tasks, and changing it mid-session invalidates prefix-cache hits.

The four tiers that fail silently

This is the failure worth planning for. Claude Code uses different models for the main conversation, background summarisation, sub-agents and small utility calls. Configure only ANTHROPIC_MODEL and the other paths do not error — they quietly do nothing useful, or fall back in ways that make the tool feel broken without naming a cause. Moonshot's reference table is explicit that each unset tier causes the corresponding task to fail, and the symptoms look like a slow or confused agent rather than a configuration error.

The practical checklist is to set all four tier variables plus the sub-agent variable in one edit, restart Claude Code, and then confirm in a session that a sub-agent actually runs. If it stalls, the tier is the first thing to check, not the model.

Codex: one TOML block

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.

The key itself belongs in the environment, not in the file. Codex reads it from the variable named in env_key, so keep config.toml free of secrets and set the variable in your shell profile or system environment.

Two limits to know before you file a bug. Codex CLI does not accept video as input even though the model does — that is a limitation of Codex's input layer, so video work has to go through the API directly. And Codex's own context management still applies: a 1M-token window does not mean every session should use one.

Pointing both tools at one gateway instead

Everything above works unchanged if you replace Moonshot's base URLs with a gateway's, which is useful when the same codebase also calls models from other vendors. OrcaRouter exposes all three surfaces for Kimi K3.1 Pro — /v1/chat/completions, /v1/responses and /v1/messages — and publishes the model under the id kimi/kimi-k3.1-pro.

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.

What you get for the substitution is one credential for every model in the catalogue and a routing policy that can move a request between vendors without changing application code — the thing that makes a fallback plan possible when a new model's endpoint rate-limits on launch week. What you give up is the vendor's own console and any vendor-specific beta surface. Prices are passed through at the provider's list: $2.00 per million input tokens and $10.00 per million output for Kimi K3.1 Pro, with no markup added.

A five-minute verification

• Hit the endpoint directly before touching the client: a POST to the Messages or Chat Completions route with a one-token request should return JSON, and a 401 means the key is wrong or belongs to the other platform.

• In Claude Code, ask a question that forces a sub-agent — a search across several files — and watch whether it completes. That is the fastest test of the tier configuration.

• In Codex, start a session on a small repository and check that the model reports the 1M window; if it reports a smaller default, model_context_window did not take.

• Set effort deliberately, once, at the start of the session: max for hard debugging, high for ordinary edits, low for extraction and formatting. The default is max, and on this model that is the expensive choice.