How to Use Kimi K3 with Claude Code: Full Setup Guide
What Kimi K3 is, and why plug it into Claude Code
Kimi K3 is Moonshot AI's flagship model, released on July 16, 2026. It is a 2.8 trillion parameter Mixture of Experts model with a 1,048,576 token context window and native vision. Moonshot markets it as the first open 3T-class model, and says the full weights land by July 27, 2026.
The detail that matters most in daily use is that K3 always reasons. Right now reasoning_effort only accepts max, and there is no non-thinking variant. Moonshot has said low and high effort modes are coming, but at launch every request thinks at full depth. That makes it strong on hard problems and slow and expensive on easy ones.
Pay-per-token pricing is $0.30 per million tokens for cache hits, $3.00 for cache misses and $15.00 for output, flat across the whole 1M context with no long-context surcharge. That 10x cache-hit discount matters a lot for an agent that resends a big repo context on every turn.
So why run it through Claude Code instead of Moonshot's own CLI? Because Claude Code is a harness you have already configured. Your hooks, your MCP servers, your CLAUDE.md, your skills and your slash commands all keep working. Switching the model is an environment variable. Switching the harness is a weekend.
Do not confuse the model with the CLI. Kimi K3 is the model. Kimi Code CLI is Moonshot's own terminal agent, a separate product that competes with Claude Code. This guide is about running the K3 model inside Claude Code, which needs no new CLI at all.
Pick your endpoint first: subscription or pay per token
This is the step people skip, and it is the reason most setup failures happen. Moonshot runs two separate Anthropic-compatible endpoints. They have different hosts, different auth variable names and different model ids. A key from one returns a 401 on the other. Decide which one you are on before you copy any config.
Option A: the Kimi Code subscription
You pay a flat monthly fee and get a quota. The endpoint is https://api.kimi.com/coding/, you authenticate with ANTHROPIC_API_KEY using a key from the Kimi Code Console, and the model id is k3[1m]. Quota refreshes every 7 days from your subscription date and does not roll over, and there is also a rolling 5 hour rate window on top, so you can hit a wall even with quota left.
Option B: the Moonshot Open Platform
You pay per token with no monthly commitment. The endpoint is https://api.moonshot.ai/anthropic, you authenticate with ANTHROPIC_AUTH_TOKEN using a key from platform.kimi.ai, and the model id is kimi-k3. Rate limits are tiered by how much you have topped up in total, and the entry tier is genuinely unusable for agent work: at Tier 0 you get 1 concurrent request and 3 requests per minute. You need at least $10 of cumulative top-up to reach Tier 1 and its 50 concurrent requests.
The auth variable is different on purpose and they fight each other. The platform endpoint uses ANTHROPIC_AUTH_TOKEN, and Moonshot explicitly says to remove ANTHROPIC_API_KEY if you have one set, because the two conflict. If you have ever exported an Anthropic key in your shell profile, unset it before you test.
Setup A: Kimi K3 in Claude Code on a Kimi Code subscription
Get a key from the Kimi Code Console, then export these before launching Claude Code:
export ANTHROPIC_BASE_URL=https://api.kimi.com/coding/
export ANTHROPIC_API_KEY=your_kimi_code_key
export ANTHROPIC_MODEL="k3[1m]"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1048576
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=1048576
export CLAUDE_CODE_EFFORT_LEVEL=maxThen run claude and type /status. The base URL it reports should be https://api.kimi.com/coding/. If it still shows Anthropic, your exports did not reach the process, which usually means you set them in a different shell than the one that launched the CLI.
The 1M context is gated by your plan. K3 gives you 256k on Moderato and the full 1M only on Allegretto and above. If you are on the cheaper tier and you copy CLAUDE_CODE_MAX_CONTEXT_TOKENS=1048576 anyway, you are telling Claude Code about a context window your plan does not grant, and Moonshot warns this causes premature compaction and errors. On Moderato, use 262144 instead.
That gating is worth understanding before you subscribe, because the 1M context is the main selling point and it is not on the entry tier. Moonshot's own pages currently disagree about whether Kimi Code access starts at Moderato or at Allegretto, so check what your plan actually includes at checkout rather than trusting any table you read in a blog post, this one included.
Setup B: Kimi K3 in Claude Code paying per token
Get a key from platform.kimi.ai, make sure no ANTHROPIC_API_KEY is set, and export this:
unset ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic
export ANTHROPIC_AUTH_TOKEN=your_platform_key
export ANTHROPIC_MODEL=kimi-k3
export ANTHROPIC_DEFAULT_OPUS_MODEL=kimi-k3
export ANTHROPIC_DEFAULT_SONNET_MODEL=kimi-k3
export ANTHROPIC_DEFAULT_HAIKU_MODEL=kimi-k3
export CLAUDE_CODE_SUBAGENT_MODEL=kimi-k3
export ENABLE_TOOL_SEARCH=false
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=1048576The three ANTHROPIC_DEFAULT_* lines matter more than they look. Claude Code picks different models for different jobs, and if you only set ANTHROPIC_MODEL it can still try to reach for a Haiku or Sonnet id that does not exist on Moonshot's endpoint. Pointing all of them at kimi-k3, plus CLAUDE_CODE_SUBAGENT_MODEL for subagents, keeps every internal call on the same model.
Once it runs, remember the tier ladder is keyed to your cumulative top-up, not to a plan you choose. Tier 0 at 3 requests per minute will make an agentic session feel broken rather than slow, so if you are testing this seriously, top up to at least Tier 1 first.
What stops working: the honest list
An Anthropic-compatible endpoint is compatible, not identical. Some Claude Code features do not survive the switch, and it is better to know now than to debug it at midnight.
Keep Tool Search off
Moonshot's docs for the platform endpoint literally say the Kimi endpoint does not support this feature yet and that ENABLE_TOOL_SEARCH must be set to false, otherwise tool calls misbehave. In practice you usually do not need to touch anything: Claude Code already disables Tool Search by default when ANTHROPIC_BASE_URL points to a non-Anthropic host. The real danger is forcing ENABLE_TOOL_SEARCH=true by hand: there is an open, unanswered report on Moonshot's tracker claiming that on the subscription endpoint tool_reference blocks leave the session returning HTTP 400 on every following request, with starting a new session as the only practical way out. It is a single unconfirmed user report, but there is no reason to gamble. The explicit false in the setup above is belt and braces.
WebFetch errors out
WebFetch does not work on Kimi's endpoint right now. When called, it either returns a "temporarily unavailable" error or comes back with no content. Moonshot admits this in their FAQ: it is a platform limitation, not your configuration, and it will work once they add support. In the meantime the official workaround is pasting the page content into the chat, or using an MCP scraping tool. Do not confuse it with WebSearch, which does work with kimi-k3.
Images depend on which endpoint you chose
This one is murkier than most posts make it sound. There is an open request asking Moonshot to support image input on the subscription endpoint from third-party tools, and it names Claude Code, Roo Code and Cursor as affected. But that is a single user request with no official reply, and the real-world evidence cuts against a total block: there are documented sessions of that same endpoint decoding base64 PNG and JPEG just fine, with only webp and gif rejected. When a third-party client cannot get images through, the culprit tends to be on the client side, not the endpoint refusing images outright.
The pay-per-token platform endpoint does document vision, because K3 is natively multimodal. But for now it only accepts base64 images or files uploaded by file id (ms:// ids), not public image URLs.
If screenshots are part of how you work, test image paste with your own client on your chosen endpoint before committing. The platform endpoint has documented vision support; the subscription endpoint is where third-party image reports get murky.
Every request thinks, and you pay for it
Because K3 only supports max reasoning effort today, cheap questions cost real money. Simon Willison's launch test spent 13,241 reasoning tokens to produce 3,417 tokens of answer, and called it out as expensive. For a coding agent that fires a lot of small tool calls, this adds up in a way a raw price-per-token comparison hides.
Run Kimi K3 and Claude side by side instead of choosing
The honest answer to "is Kimi K3 better than Claude for my work" is that nobody knows yet. K3 is days old, every quality signal in circulation is a first impression, and the thing that actually matters for a coding agent, reliable tool calling as a conversation gets long, has no public data behind it at all. Willison made exactly that point at launch: the benchmarks going around do not touch it.
Which means the only useful test is your own repo, your own tasks, both models, at the same time. That is awkward with one terminal, because the setup is a set of environment variables you have to keep swapping. It stops being awkward when each terminal owns its own agent and its own environment.
That is what CodeAgentSwarm does. You give one terminal the Kimi env and one terminal your normal Claude setup, point both at the same task, and watch. Every terminal gets live diffs of what its agent touched, a desktop notification when it needs you, and searchable history afterwards, so comparing two runs is reading two histories instead of trusting your memory of what happened twenty minutes ago.
If you want the wider picture, the Claude Code vs Cursor vs Codex comparison covers how the harnesses differ, and running multiple Claude Code sessions covers the parallel workflow this builds on.
Troubleshooting the setup
- 401 Unauthorized: you are almost certainly using a key from the wrong platform. Keys from platform.kimi.ai and platform.kimi.com are completely independent, and a key from one returns 401 on the other. Same story if you mix a Kimi Code Console key with the platform endpoint.
- /status still shows the Anthropic base URL: your exports did not reach the process. Export them in the same shell that launches the CLI, or put them in your shell profile and open a new terminal.
- Persistent HTTP 400 that never recovers: check whether something in your setup forced ENABLE_TOOL_SEARCH=true (Claude Code disables it by default on non-Anthropic hosts). There is an unconfirmed report of tool_reference blocks leaving subscription-endpoint sessions permanently on 400. Set it to false and start a fresh session.
- Context gets compacted way too early: your context setting does not match what your plan grants. On Moderato use 262144, not 1048576.
- Both an API key and an auth token set: on the platform endpoint, unset ANTHROPIC_API_KEY. Moonshot documents the conflict explicitly.
FAQ
Yes. Moonshot ships an Anthropic-compatible endpoint, so Claude Code talks to Kimi K3 with only environment variables and no new CLI. Set ANTHROPIC_BASE_URL to https://api.kimi.com/coding/ with a Kimi Code subscription key, or to https://api.moonshot.ai/anthropic with a pay-per-token platform key, then set ANTHROPIC_MODEL to k3[1m] or kimi-k3 respectively.
Almost always because the key and the endpoint do not match. Moonshot runs two independent platforms, and a key from platform.kimi.ai returns 401 on platform.kimi.com and the other way around. The subscription endpoint also uses ANTHROPIC_API_KEY while the pay-per-token endpoint uses ANTHROPIC_AUTH_TOKEN, and Moonshot says to unset ANTHROPIC_API_KEY on the platform endpoint because the two conflict.
Only on the right plan. K3 gives 256k context on Moderato and the full 1,048,576 tokens on Allegretto and above. Setting CLAUDE_CODE_MAX_CONTEXT_TOKENS=1048576 on a plan that only grants 256k causes premature compaction and errors, so use 262144 on the lower tier.
Tool Search must stay off — Claude Code already disables it by default on non-Anthropic hosts, and Moonshot documents that the endpoint does not support it yet. WebFetch is not available on the Kimi endpoint and returns a visible "temporarily unavailable" error (WebSearch does work). Image support from third-party clients on the subscription endpoint is inconsistent, and on the pay-per-token endpoint vision works only as base64 or ms:// file ids, not public URLs.
Per token it looks much cheaper at $0.30 per million for cache hits, $3.00 for cache misses and $15.00 for output. But K3 only supports max reasoning effort right now, so every request thinks at full depth and burns reasoning tokens even on simple questions. The real cost depends on your workload, which is why running it in one terminal next to your normal setup for a few days tells you more than any price table.
No. Kimi K3 is the model, and you can run it inside Claude Code as this guide describes. Kimi Code CLI is Moonshot's own terminal agent, a separate product that competes with Claude Code and has its own config, hooks and sessions. You do not need it to use K3.
Running Kimi K3 in one terminal and Claude in another is the fastest way to find out which model suits which job. CodeAgentSwarm runs both side by side, each in its own terminal, with live diffs, desktop notifications and searchable history across all of them.
Try CodeAgentSwarm