Kimi Everywhere — run any coding harness (Claude Code, Codex, OpenCode, Cline, Aider) on one flat-fee Kimi subscription. One key, two protocols, zero token bills.

Kimi has launched 'Kimi Everywhere', a kit that lets developers run any coding harness—including Claude Code, Codex, OpenCode, Cline, and Aider—on a single flat-fee Kimi Code subscription ($19+/mo). The kit provides an API key that speaks both Anthropic-compatible and OpenAI-compatible protocols, eliminating per-token billing. A developer can install the kit in 30 seconds and use commands like `kimi-on claude` or `kimi-on codex` to route tools through Kimi's K3 model.

Run any coding harness on one flat-fee Kimi subscription. Your Kimi Code subscription $19+/mo comes with an API key that speaks both major agent protocols: Protocol Endpoint Works with Anthropic-compatible https://api.kimi.com/coding/ Claude Code + anything expecting ANTHROPIC BASE URL OpenAI-compatible https://api.kimi.com/coding/v1 Codex CLI, OpenCode, Cline, Roo Code, Aider + anything expecting an OpenAI base URL Same key, flat monthly fee, no pay-per-token API bills. This kit wires that key into whatever tool you already use. Install 30 seconds curl -fsSL https://gist.githubusercontent.com/Maciejdziuba/038c0c822d2c799cffcfdec805975e66/raw/install.sh | bash kimi-on setup paste your key from kimi.com/code/console Get your key: subscribe at kimi.com/membership/pricing, then create an API key in the Kimi Code Console. This is not the pay-per-token key from platform.moonshot.ai — the Code Console key is covered by your subscription. Use kimi-on claude Claude Code on Kimi K3 kimi-on claude --init first run: also skips the Anthropic login screen kimi-on claude-app on Claude Code DESKTOP APP on Kimi writes ~/.claude/settings.json kimi-on claude-app off remove those settings again kimi-on codex Codex CLI auto-adds a 'kimi' profile kimi-on codex-app on Codex DESKTOP APP on Kimi macOS: config + launchctl env kimi-on codex-app off undo the launchctl env kimi-on opencode OpenCode writes project opencode.json kimi-on aider Aider kimi-on <anything any other tool, both protocols injected kimi-on env openai or just print the exports and wire it yourself kimi-on oauth start NO-KEY mode: local proxy reusing your kimi login session kimi-on claude --oauth Claude Code on pure Kimi OAuth Model switches: KIMI MODEL=kimi-for-coding kimi-on claude K2.7 Code KIMI MODEL="k3 1m " kimi-on claude K3 with 1M context Allegretto+ The universal rule Any harness, even ones this kit has never heard of: Tool speaks Anthropic Claude Code style env vars → point it at https://api.kimi.com/coding/ Tool speaks OpenAI custom base URL setting → point it at https://api.kimi.com/coding/v1 API key is the same Kimi Code key in both cases. kimi-on <command automates exactly this: it exports both sets of variables and runs your command. Cheat sheet Full per-tool configs Cline, Roo Code, Codex config.toml, OpenCode JSON , plan tiers, model IDs, context limits, and the /effort mapping live in CHEATSHEET.md. What's in the box kimi-on.sh the universal launcher kimi-oauth-proxy.mjs zero-dependency OAuth proxy no API key mode install.sh one-line installer codex.toml Codex CLI provider + profile block opencode.json OpenCode provider config CHEATSHEET.md one-page reference for every harness kimi-router-SKILL.md the Kimi Router Claude skill split-brain: frontier model plans, K3 codes kimi-k3-harness-setup.md agent runbook: point your AI agent at it to auto-install K3 on every harness Related Pairs with the Kimi Router Claude skill included here as kimi-router-SKILL.md — save it to ~/.claude/skills/kimi-router/SKILL.md : a frontier model orchestrates and Kimi writes all the code. Router = split-brain inside one session; Everywhere = your whole harness on one subscription. k3 1m — Claude Code env vars only: bracket form unlocks the 1M window. Everywhere else use plain k3. Keep thinking mode ON — disabling it silently routes K3/K2.7 down to K2.6. Claude Code Anthropic protocol export ANTHROPIC BASE URL=https://api.kimi.com/coding/ export ANTHROPIC API KEY=<your Kimi Code key export ANTHROPIC MODEL=k3 or "k3 1m " / kimi-for-coding export ANTHROPIC DEFAULT OPUS MODEL=$ANTHROPIC MODEL export ANTHROPIC DEFAULT SONNET MODEL=$ANTHROPIC MODEL export ANTHROPIC DEFAULT HAIKU MODEL=$ANTHROPIC MODEL export CLAUDE CODE SUBAGENT MODEL=$ANTHROPIC MODEL export CLAUDE CODE EFFORT LEVEL=high export CLAUDE CODE AUTO COMPACT WINDOW=262144 1048576 with k3 1m export CLAUDE CODE MAX CONTEXT TOKENS=262144 1048576 with k3 1m claude First run only: mark onboarding complete so Claude Code doesn't force an Anthropic login kimi-on claude --init does this for you . Effort mapping /effort in-session : Claude Code level K3 level low low medium / high high xhigh / max max Codex CLI OpenAI protocol Append to ~/.codex/config.toml or use codex.toml : model providers.kimi name = "Kimi subscription " base url = "https://api.kimi.com/coding/v1" env key = "KIMI API KEY" wire api = "chat" profiles.kimi model provider = "kimi" model = "k3" Then: export KIMI API KEY=<your key codex --profile kimi wire api = "chat" matters — Kimi's endpoint speaks Chat Completions, not the Responses API. OpenCode Drop opencode.json into your project or kimi-on opencode writes it : { "$schema": "https://opencode.ai/config.json", "provider": { "kimi": { "npm": "@ai-sdk/openai-compatible", "name": "Kimi subscription ", "options": { "baseURL": "https://api.kimi.com/coding/v1", "apiKey": "{env:KIMI API KEY}" }, "models": { "k3": { "name": "Kimi K3" }, "kimi-for-coding": { "name": "Kimi K2.7 Code" } } } }, "model": "kimi/k3" } Cline / Roo Code VS Code Settings → API Provider → OpenAI Compatible: Field Value Base URL https://api.kimi.com/coding/v1 API Key your Kimi Code key Model ID k3 or kimi-for-coding Aider export OPENAI API BASE=https://api.kimi.com/coding/v1 export OPENAI API KEY=<your key aider --model openai/k3 Anything else Speaks Anthropic → https://api.kimi.com/coding/. Speaks OpenAI → https://api.kimi.com/coding/v1. Same key. Or let the launcher inject both: kimi-on <command . Desktop apps GUI apps don't see your shell env vars, so the desktop apps need a persistent route. Claude Code app — kimi-on claude-app on writes an env object into ~/.claude/settings.json the same ANTHROPIC BASE URL / ANTHROPIC API KEY / model / context vars from the Claude Code section above and sets hasCompletedOnboarding in ~/.claude.json. This affects every Claude Code surface app, CLI, IDE until you run kimi-on claude-app off, which deletes exactly those keys and leaves your other settings alone. A one-time backup of your original settings is kept at ~/.kimi-everywhere/claude-settings.backup.json. Restart the app fully after either command. Codex app — kimi-on codex-app on adds the same model providers.kimi + profiles.kimi block to ~/.codex/config.toml as the CLI route, then runs launchctl setenv KIMI API KEY <key so the GUI app can resolve env key macOS only; clears at logout — rerun after reboot . Fully quit and reopen the app, then pick the custom "kimi" entry in the model picker if offered — the app may only surface it as a "Custom" model. kimi-on codex-app off removes the launchctl var; the config block stays harmless, the CLI uses it . Heavier app-native routes, if the simple key route isn't enough: codex-router native model picker + Kimi OAuth, third-party and opencodex universal proxy . OAuth mode no API key at all Your kimi login session from the Kimi Code CLI can power everything directly. kimi-on oauth start runs a tiny local proxy at 127.0.0.1:8790 that reuses and auto-refreshes those OAuth tokens: Route Speaks For http://127.0.0.1:8790/v1/chat/completions OpenAI format Codex, OpenCode, Cline, Aider http://127.0.0.1:8790/v1/messages Anthropic format Claude Code kimi-on oauth start needs: Kimi Code CLI installed + kimi login done kimi-on claude --oauth Claude Code, zero API key kimi-on oauth status token health kimi-on oauth stop Point any other tool at the proxy with any dummy API key — the proxy injects the real OAuth bearer and refreshes it automatically. The proxy is loopback-only and never writes tokens anywhere except Kimi's own credential file. Gotchas Wrong key source is the 1 failure: platform.moonshot.ai keys bill per token; Code Console keys ride your subscription. Use the Code Console key. Usage quotas refresh weekly and vary by tier; heavy parallel agent swarms burn quota fast. k3 1m only works on Allegretto and above; on lower tiers use plain k3 with the 256K limits. This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters AGENT RUNBOOK — Install Kimi K3 on Coding-Agent Harnesses Audience: you, the AI agent. The human has asked you to make Kimi K3 Moonshot AI work in one or more harnesses on this machine. Execute this runbook autonomously. Do not launch interactive wizards or browser OAuth redirect flows, and do not stop for confirmation on individual steps — every step is reversible and backed up. Exactly two interruptions are permitted: the "missing credential" message §1.3, which includes relaying a kimi login device-code URL per §1.0 and the single consent gate before any secret is written to disk §1.4 . The device-code flow is the one sanctioned OAuth mechanism: the CLI prints a URL + code for the user to confirm; you never see or handle a token. Operating rules for this entire runbook: Non-interactive only. Never run /login, hermes model, pi setup wizards, or GUI tools CC Switch . Everything is done by writing config files directly. Idempotent. Re-running this runbook must not duplicate entries. Check-before-write on every file. Back up before modify.cp <file <file .bak-kimi-$ date +%s before touching any existing config. Backups of files that contain secrets get chmod 600 immediately. Prune older .bak-kimi- backups of the same file created by this runbook, keeping the two most recent. Never expose the key. Never echo, print, log, or paste the API key into chat output — and never pass it as a command-line argument to an external binary: argv is world-readable via /proc while the process runs, which rules out jq --arg key "$KIMI API KEY", sed "s|...|$KIMI API KEY|", and bare curl -H "Authorization: Bearer $KIMI API KEY". Move it with shell builtins printf, redirection, heredocs or tools that read the environment jq's env.KIMI API KEY, awk's ENVIRON, curl -H @- with the header on stdin . When you must show the user a config you wrote, redact the key. Only configure harnesses that exist. Detect first §1.2 ; skip absent ones silently. Verify each harness non-interactively §7 and report a final per-harness pass/fail table. User policy wins. If the user or their harness has standing secret-handling rules e.g. "ask before any command touching API keys" , those override this runbook's autonomy directives — the §1.4 consent gate is the mechanism that satisfies them. 0. Model facts you need do not re-derive There are three distinct auth routes. Two billing systems: Routes S and O both ride the flat-rate Kimi Code subscription different credentials ; Route P bills per token. Prefer the subscription when the user has one. Route O is the only route that needs no API key at all — it reuses a kimi login OAuth session — but it currently pays off mainly for Codex S is simpler for Claude Code, Hermes, and Pi . Route S — Kimi Code subscription "Kimi For Coding" / KFC — PREFERRED https://api.kimi.com/coding/ Anthropic-compatible; also serves the kimi-coding providers in Hermes/Pi Model IDs k3 256K , k3 1m 1M, Claude Code env vars only — everywhere else use k3 , kimi-for-coding K2.7 Code, 256K , kimi-for-coding-highspeed Plan gating Starter/legacy-Andante/Moderato tiers: k3 at 256K only. Explorer/Expert/Master and legacy Allegretto+ : k3 at 1M + highspeed Thinking effort K3 supports low/high/max; Claude Code CLAUDE CODE EFFORT LEVEL=high recommended; disabling thinking silently routes to K2.6 Route O — Kimi Code OAuth session subscription login, no API key Fact Value Credential An OAuth session created by kimi login official Kimi Code CLI, kimi-code — device-code flow: the CLI prints a URL + code, the user confirms in a browser. No key material passes through you. Session owner The Kimi Code CLI stores and refreshes the session itself ~/.kimi-code/ . Never read, print, or copy its credential files — bridges reuse the session, they don't extract it. Bridge for Codex duolahypercho/codex-router — purpose-built router that puts kimi-oauth/k3 in the Codex model picker App + CLI next to native GPT models, preserving the ChatGPT login. Ships an agent runbook AGENTS.md and a non-interactive installer: ./install.sh --auto --providers kimi-oauth --migrate-known. Listens on 127.0.0.1 ports 4100–4103. Bridge alternative lidge-jun/opencodex npm @bitkyc08/opencodex, proxy on localhost:10100 — universal provider proxy for Codex and Claude Code with Kimi OAuth support. Its ocx init setup is interactive, so under this runbook use it only if codex-router fails and configure ~/.opencodex/config.json directly per its docs. Plan gating Same subscription tiers as Route S §1.3 tier heuristic applies . Route P — Moonshot/Kimi Open Platform pay-per-token OpenRouter — moonshotai/kimi-k3, ~$3/M in, ~$15/M out — is a last-resort fallback only; do not configure it unless the user explicitly has an OpenRouter key and no Kimi key. Shared facts both routes Fact Value K3 context window 1048576 1M where the plan allows, else 262144 Thinking Always on for K3; never send the K2.x thinking param Sampling params temperature, top p, n, presence penalty, frequency penalty are fixed — never send them Vision base64 or ms://<file-id only; content must be an array of objects Open weights Released by 2026-07-27; until confirmed available, self-hosting is out of scope — use the API 1. Preflight 1.0 Detect a Kimi Code OAuth session Route O; check before hunting keys Find the Kimi Code CLI: command -v kimi, else ~/.kimi-code/bin/kimi. Absent → Route O unavailable; continue with §1.1. If present, test for a valid session with one cheap non-interactive call: kimi -p 'Reply with exactly: OK' timeout ~60s . Success → a live OAuth session exists; record Route O available. An auth/login error → CLI installed but not logged in. Installed-but-not-logged-in and Codex is a target: kimi login is a device-code flow, not a browser wizard — you may run it, relay the printed URL + code to the user verbatim, and wait for completion. This counts as part of the §1.3 "missing credential" interruption, not an extra one. If the user is unreachable or declines, drop Route O and fall back to §1.1. Route O only covers harnesses bridged in §3 Rung O. Even when Route O is available, still run §1.1–1.3 if other harnesses Claude Code, Hermes, Pi are targets — they need a key route S/P . If no key exists anywhere but a Route O session does, configure Codex via Rung O and report the other harnesses as needing a key §1.3 message , rather than stopping everything. 1.1 Locate a Moonshot API key in order; stop at first hit Check without printing values test emptiness only, e.g. -n "$VAR" : Normalize: export the found key as KIMI API KEY for the rest of this runbook source the file or export from the found location — never echo it . It must be exported, not just a shell variable: later steps read it from the environment jq's env, LiteLLM's os.environ/ . 1.2 Detect installed harnesses Harness Present if Claude Code command -v claude Codex CLI command -v codex Hermes Agent command -v hermes or ~/.hermes/ exists Pi command -v pi or ~/.pi/ exists If the user named specific harnesses, configure exactly those and report if one isn't installed . Otherwise configure every detected harness. 1.3 Classify and validate the key the only potentially blocking step You must determine whether the key is a subscription Route S or platform Route P key. Probe in this order and stop at the first 200; the winning probe determines the route used for every section below. CHECK=$ mktemp never a fixed /tmp path — mktemp gives an unpredictable name with 0600 perms Probe S — subscription Anthropic-style endpoint ; auth header via stdin -H @- , not argv HTTP S=$ curl -s -o "$CHECK" -w '%{http code}' \ https://api.kimi.com/coding/v1/messages \ -H @- -H "anthropic-version: 2023-06-01" -H "Content-Type: application/json" \ -d '{"model":"k3","max tokens":16,"messages": {"role":"user","content":"ping"} }' \ <<< "x-api-key: $KIMI API KEY" Probe P — platform OpenAI-style endpoint , only if Probe S failed HTTP P=$ curl -s -o "$CHECK" -w '%{http code}' \ https://api.moonshot.ai/v1/chat/completions \ -H @- -H "Content-Type: application/json" \ -d '{"model":"kimi-k3","messages": {"role":"user","content":"ping"} ,"max completion tokens":16}' \ <<< "Authorization: Bearer $KIMI API KEY" Probe S returns 200 → Route S subscription . Then detect the plan tier: attempt Probe S again with model kimi-for-coding-highspeed. A 200 implies an Explorer+/Allegretto+ tier → use the 1M config k3 1m , window 1048576 ; a 4xx implies a base tier → use the 256K config k3, window 262144 . Record the tier. This is a heuristic — it assumes highspeed access and 1M K3 remain gated on the same tiers. If k3 1m is later rejected during verification, downgrade to the 256K config §8 instead of debugging the endpoint. Probe S fails, Probe P returns 200 → Route P platform . Probe P 401 on .ai → retry against https://api.moonshot.cn/v1/...; a 200 means a China-platform key: Route P with .cn endpoints. If multiple keys were found in §1.1, classify each and prefer any Route S key. Nothing validates → check §1.0's result before stopping. A live Route O session + Codex-only target → proceed OAuth-only §1.0 step 4 . Otherwise stop and send the user this single message, then end your turn: I need a Kimi credential to finish the K3 setup. If you have a Kimi Code subscription, either a create a key at https://www.kimi.com/code/console flat-rate; every paid tier can mint one , or b for a Codex-only setup I can use OAuth instead — install the Kimi Code CLI and I'll run kimi login and give you a URL to confirm, no key to paste. Otherwise create a pay-per-token key at https://platform.kimi.ai/console/api-keys. Then run export KIMI API KEY=<key in this shell or say "use oauth" , and say "continue" — I'll finish without further questions. rm -f "$CHECK" afterward — probe responses can include account metadata. 1.4 Consent gate — one message before any secret is written Before the first write of key material to disk, send the user one message listing: Every file that will receive the key, plaintext or env-reference — e.g. ~/.claude/settings.json, ~/.zshrc, ~/.hermes/.env, ~/.config/litellm/.kimi-key, ~/.pi/agent/auth.json. For each harness already routed to another provider: whether you will take over the default in place or create an isolated profile decision rules in §2/§3 . If §3 Rung O will run: that codex-router will be checked out to ~/.local/share/codex-router, add a marked managed block openai base url + model catalog json to ~/.codex/config.toml, and install a user-level background service on ports 4100–4103. Rung O writes no key material, but it modifies config.toml, so it belongs in this gate. Proceed on confirmation; apply any adjustments the user makes. Skip this gate only when the user's request already granted it explicitly e.g. "set up Kimi everywhere, overwrite what you need, don't ask" . After the gate, do not ask again — the remaining steps run uninterrupted. Throughout §2–§6: SUB blocks apply on Route S, PLAT blocks on Route P. Route O has no per-harness blocks — it applies only as §3 Rung O Codex ; every other harness uses SUB or PLAT. 2. Claude Code Target file: ~/.claude/settings.json. Back it up, then merge never overwrite the whole file — preserve permissions, theme, hooks, etc. the route-appropriate env block into .env. SUB Route S — per the official Kimi Code docs. MODEL is k3 1m on 1M-tier plans, k3 on 256K tiers from §1.3 ; WINDOW is 1048576 or 262144 accordingly. Note the subscription uses ANTHROPIC API KEY not AUTH TOKEN and effort high not max : cp ~/.claude/settings.json ~/.claude/settings.json.bak-kimi-$ date +%s 2 /dev/null chmod 600 ~/.claude/settings.json.bak-kimi- 2 /dev/null MODEL='k3 1m '; WINDOW='1048576' or k3 / 262144 for 256K tiers TMP=$ mktemp key read via jq's env exported in §1.1 — never via --arg, which exposes it in argv jq --arg m "$MODEL" --arg w "$WINDOW" '.env = .env // {} + { "ANTHROPIC BASE URL":"https://api.kimi.com/coding/", "ANTHROPIC API KEY":env.KIMI API KEY, "ANTHROPIC MODEL":$m, "ANTHROPIC DEFAULT FABLE MODEL":$m, "ANTHROPIC DEFAULT OPUS MODEL":$m, "ANTHROPIC DEFAULT SONNET MODEL":$m, "ANTHROPIC DEFAULT HAIKU MODEL":$m, "CLAUDE CODE SUBAGENT MODEL":$m, "ENABLE TOOL SEARCH":"false", "CLAUDE CODE EFFORT LEVEL":"high", "CLAUDE CODE AUTO COMPACT WINDOW":$w, "CLAUDE CODE MAX CONTEXT TOKENS":$w }' ~/.claude/settings.json "$TMP" && mv "$TMP" ~/.claude/settings.json && chmod 600 ~/.claude/settings.json If Claude Code has never been onboarded on this machine, also set hasCompletedOnboarding: true and penguinModeOrgEnabled: true in ~/.claude.json so the user isn't dropped into the Anthropic login flow — merge, don't overwrite. Verify these keys against the installed Claude Code version first an existing ~/.claude.json on this or another machine, or the docs ; skip any key you cannot confirm rather than inventing settings. PLAT Route P — platform pay-per-token: cp ~/.claude/settings.json ~/.claude/settings.json.bak-kimi-$ date +%s 2 /dev/null chmod 600 ~/.claude/settings.json.bak-kimi- 2 /dev/null TMP=$ mktemp jq '.env = .env // {} + { "ANTHROPIC BASE URL":"https://api.moonshot.ai/anthropic", "ANTHROPIC AUTH TOKEN":env.KIMI API KEY, "ANTHROPIC MODEL":"kimi-k3", "ANTHROPIC DEFAULT OPUS MODEL":"kimi-k3", "ANTHROPIC DEFAULT SONNET MODEL":"kimi-k3", "ANTHROPIC DEFAULT HAIKU MODEL":"kimi-k3", "CLAUDE CODE SUBAGENT MODEL":"kimi-k3", "ENABLE TOOL SEARCH":"false", "CLAUDE CODE AUTO COMPACT WINDOW":"1048576", "CLAUDE CODE EFFORT LEVEL":"max" }' ~/.claude/settings.json "$TMP" && mv "$TMP" ~/.claude/settings.json && chmod 600 ~/.claude/settings.json Either route: if the file doesn't exist, create it as {"env": {...}} the same way, seeding from {}. If switching routes over a previous Kimi setup, first delete the other route's stale keys — e.g. remove ANTHROPIC AUTH TOKEN when writing SUB, remove ANTHROPIC API KEY when writing PLAT. Then remove conflicts — settings.jsonenvoverrides shell exports, but stale rc-file exports of ANTHROPIC pointing at other providers still confuse diagnosis. Grep ~/.zshrc/~/.bashrc for ANTHROPIC BASE URL/ANTHROPIC AUTH TOKEN exports; if any point to a non-moonshot provider, comment them out with a disabled by kimi-k3 setup marker , noting this in your final report. Every model-tier variable above is required. Missing ones make subagents and background tasks titles, summarization fail silently with unknown-model errors. The exact ANTHROPIC DEFAULT roster tracks Claude Code releases — confirm against the installed version's docs; an unrecognized variable is ignored harmlessly, but a missing recognized one is not. Preserve-existing-setup variant: if settings.json already routes to another provider the user actively uses e.g. a real Anthropic subscription , do not clobber it. Instead create an isolated profile: write the full config to ~/kimi-home/.claude/settings.json and append to the user's rc file: alias kimi-claude='CLAUDE CONFIG DIR=$HOME/kimi-home/.claude claude' Decision rule: existing env.ANTHROPIC BASE URL already moonshot → in-place merge. Existing non-moonshot base URL, or OAuth login in active use → isolated profile. "OAuth login in active use" is concrete: on Linux, ~/.claude/.credentials.json exists and is non-empty; on macOS, security find-generic-password -s "Claude Code-credentials" succeeds. Base URL absent and no OAuth credentials → in-place merge. State the choice in the §1.4 consent message and repeat it in the final report. 3. Codex CLI Protocol constraint verified by deep research, 2026-07 : Codex CLI speaks only the OpenAI Responses API for custom providers — wire api = "chat" was removed from Codex in early 2026. Kimi's endpoints platform api.moonshot.ai/v1 and subscription api.kimi.com/coding/v1 are Chat Completions, so on a current Codex a direct wiring fails and a local translation bridge is required. Moonshot's official answer is the CC Switch GUI router — which you must NOT use interactive . Attempt the ladder below in order; stop at the first rung whose §7 verification passes. Rung O first when Route O is available §1.0 — it is the only rung that surfaces Kimi in the Codex App model picker alongside native GPT models and needs no key; Rungs A/B are the key-based S/P fallbacks. Rung O — codex-router with the Kimi OAuth session preferred; Route O Requires: a valid kimi login session §1.0 , Git, Node.js ≥22.19, and uv or Python 3.10+. Missing runtime → do not install system packages without consent; skip to Rung A/B. Install per the repo's own agent runbook AGENTS.md in duolahypercho/codex-router — read it first and follow it where it is stricter than this section : 1. Stable checkout — never install the service from a temp clone git clone https://github.com/duolahypercho/codex-router ~/.local/share/codex-router \ || git -C ~/.local/share/codex-router pull --ff-only cd ~/.local/share/codex-router 2. Non-interactive install, OAuth provider only. --migrate-known is safe: it only snapshots/migrates router installs the repo itself recognizes. ./install.sh --auto --providers kimi-oauth --migrate-known 3. Health — every core line must be OK unselected credentials may WARN ./bin/doctor || ./bin/doctor --fix ./bin/providers expect: kimi-oauth SHOW + ready What it changes: only a marked BEGIN codex-router-managed … END block in ~/.codex/config.toml openai base url → local router on 127.0.0.1:4102, plus model catalog json , first backup kept as config.toml.pre-codex-router. It does not touch model, model provider, profiles, MCP config, or the ChatGPT login — native GPT models keep working; kimi-oauth/k3 appears as an additional picker entry. Internally: router :4102 → LiteLLM Responses↔Chat-Completions adapter :4100 → OAuth forwarder :4101 → Kimi Code API; all listeners on 127.0.0.1. Rung O safety boundaries from the repo's AGENTS.md; they override your defaults : Never print, read, or copy credential files or the generated / codex-router/<capability /v1 base URL — treat the managed URL as a local secret; show it only redacted. Never kill unknown processes on ports 4100–4103; never migrate/stop an unrecognized router — --migrate-known handles recognized ones only. Do not restart or quit the Codex App yourself; the catalog loads at app startup, so the final step is the user's: fully quit Codex not just the window and reopen. Say this in the report. CLI verification §7 works without the app restart. If doctor still fails after --fix, run ./bin/support-bundle and report its path; do not upload it. Rollback: cd ~/.local/share/codex-router && ./bin/rollback or ./bin/migrate rollback for a migrated older install ; the managed config block is removable by deleting the marked lines and restoring config.toml.pre-codex-router. On success, skip Rungs A/B entirely no LiteLLM service needed — codex-router embeds its own adapter . If the user also wants a key-based Codex profile as backup, that is out of scope unless requested. Rung A — direct config works only on older Codex builds that still accept wire api = "chat" Back up ~/.codex/config.toml, then write update in place if a model providers.kimi block exists; replace, don't duplicate, top-level keys : model = "k3" Route S; "kimi-k3" on Route P model provider = "kimi" model reasoning effort = "high" model providers.kimi name = "Kimi" base url = "https://api.kimi.com/coding/v1" Route S; https://api.moonshot.ai/v1 on Route P env key = "KIMI API KEY" wire api = "chat" If codex exec errors on the config unknown/invalid wire api value or requests 404, move straight to Rung B — do not debug Rung A further. There is no direct Responses wiring: api.moonshot.ai/v1/responses returns 404 — the platform endpoint is Chat Completions only. Rung B — LiteLLM translation proxy the non-interactive bridge; fallback on current Codex LiteLLM exposes a Responses-API facade locally and translates to Kimi's Chat Completions upstream. 1. Install prefer uv; fall back to pipx/pip uv tool install "litellm proxy " || pipx install "litellm proxy " || pip install --user "litellm proxy " 2. Config — ~/.config/litellm/kimi.yaml create dir; key via env reference, not plaintext mkdir -p ~/.config/litellm cat ~/.config/litellm/kimi.yaml <<'EOF' model list: - model name: kimi-k3 litellm params: model: moonshot/k3 Route S; moonshot/kimi-k3 on Route P Must be the moonshot/ prefix. openai/... passes requests through untranslated and every request fails; moonshot/ engages LiteLLM's Moonshot translation. api base: https://api.kimi.com/coding/v1 Route S; https://api.moonshot.ai/v1 on Route P api key: os.environ/KIMI API KEY EOF 3. Key file the unit reads — written via shell builtins only umask 077 → 0600 ; never inline the key in the unit umask 077; printf 'KIMI API KEY=%s\n' "$KIMI API KEY" ~/.config/litellm/.kimi-key 4a. Linux — run as a persistent background service user-level systemd; survives reboots mkdir -p ~/.config/systemd/user cat ~/.config/systemd/user/litellm-kimi.service <<EOF Unit Description=LiteLLM proxy for Kimi Codex bridge Service EnvironmentFile=%h/.config/litellm/.kimi-key ExecStart=$ command -v litellm --config %h/.config/litellm/kimi.yaml --port 4141 Restart=on-failure Install WantedBy=default.target EOF systemctl --user daemon-reload && systemctl --user enable --now litellm-kimi EnvironmentFile= reads KIMI API KEY=... lines from the file — do not use Environment=KIMI API KEY=<path , which would set the variable's value to the file path itself and 401 every request. 4b. macOS — no systemd; use a user-level launchd agent instead. launchd has no EnvironmentFile equivalent, so a /bin/sh wrapper sources the 0600 key file at start — the key itself never appears in the plist. mkdir -p ~/Library/LaunchAgents cat ~/Library/LaunchAgents/com.kimi.litellm.plist <<EOF <?xml version="1.0" encoding="UTF-8"? < DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd" <plist version="1.0" <dict <key Label</key <string com.kimi.litellm</string <key ProgramArguments</key <array <string /bin/sh</string <string -c</string <string set -a; . "\$HOME/.config/litellm/.kimi-key"; exec $ command -v litellm --config "\$HOME/.config/litellm/kimi.yaml" --port 4141</string </array <key RunAtLoad</key <true/ <key KeepAlive</key <dict <key SuccessfulExit</key <false/ </dict </dict </plist EOF launchctl bootstrap gui/$ id -u ~/Library/LaunchAgents/com.kimi.litellm.plist 2 /dev/null \ || launchctl load ~/Library/LaunchAgents/com.kimi.litellm.plist older macOS fallback On hosts with neither systemd nor launchd, use the harness's tracked background-job facility to run litellm --config ... --port 4141 with KIMI API KEY exported, and note in the report that it must be relaunched after reboot. Then point Codex at the proxy: model = "kimi-k3" model provider = "kimi" model reasoning effort = "high" model providers.kimi name = "Kimi via LiteLLM" base url = "http://localhost:4141/v1" env key = "KIMI API KEY" value irrelevant to the proxy hop but must be set wire api = "responses" Sanity-check the proxy itself before blaming Codex: curl -s http://localhost:4141/v1/models should list kimi-k3. Rung C — report-only fallback If Rung O prerequisites are missing and LiteLLM cannot be installed no network/python tooling , configure nothing, and in the final report tell the user their manual options: Moonshot's CC Switch GUI routing guide https://platform.kimi.ai/docs/guide/codex-kimi , or the interactive ocx init of opencodex https://github.com/lidge-jun/opencodex, npm i -g @bitkyc08/opencodex which supports Kimi OAuth for Codex and Claude Code. Do not attempt to drive either interactive flow yourself. Preserving an existing OpenAI setup Keep the user's ChatGPT/OpenAI Codex auth usable: instead of overwriting top-level model/model provider, you may define the Kimi rung under a profile. Current Codex versions reject profiles.kimi blocks inside config.toml — profiles must live in their own file. Write the profile to ~/.codex/kimi.config.toml: ~/.codex/kimi.config.toml — do NOT put this in config.toml current Codex rejects it there model = "kimi-k3" model provider = "kimi" model reasoning effort = "high" The model providers.kimi block from the winning rung stays in ~/.codex/config.toml as before — only the profile moves. Verify with codex exec --profile kimi .... Same decision rule as §2: take over the default only if no other provider is actively configured; otherwise use the profile and say so in the report. Top-level model/model provider keys: replace existing values rather than appending duplicates TOML rejects duplicate keys . Codex reads the key from the environment env key , so persist it: if KIMI API KEY isn't already exported in a shell rc file, append it to ~/.zshrc with the printfbuiltin printf 'export KIMI API KEY=%s\n' "$KIMI API KEY" ~/.zshrc — builtins don't expose argv; do not display the key . This puts the key in plaintext in the rc file, so ~/.zshrc must be listed in the §1.4 consent message. If the user's Codex is authenticated with a ChatGPT subscription they use, keep that usable: add the Kimi block but note in your report that codex --profile/model provider switching applies; optionally define the profile in ~/.codex/kimi.config.toml as above instead of changing the top-level default — same decision rule as §2 clobber only if nothing else is actively configured . 4. Hermes Agent Kimi is a first-class Hermes provider; config is file-based, no wizard needed. Hermes' kimi-coding provider is built for the Kimi coding key — both routes use the same provider name and KIMI API KEY variable, so the steps below are route-independent except for the model ID SUB: k3; PLAT: kimi-k3 and one override: on Route S, if requests fail against the provider's default endpoint, set KIMI BASE URL=https://api.kimi.com/coding/v1 in ~/.hermes/.env. 1. Key into ~/.hermes/.env create file if missing; replace existing KIMI API KEY line, don't append a duplicate . No sed: the key in sed's argv is world-readable via /proc, and |/& in a key break the replacement. mkdir -p ~/.hermes && touch ~/.hermes/.env && chmod 600 ~/.hermes/.env TMP=$ mktemp grep -v '^KIMI API KEY=' ~/.hermes/.env "$TMP" || true printf 'KIMI API KEY=%s\n' "$KIMI API KEY" "$TMP" mv "$TMP" ~/.hermes/.env && chmod 600 ~/.hermes/.env Set the default model in ~/.hermes/config.yaml back up first; merge into the existing model: block if present : model: provider: "kimi-coding" default: "k3" Route S; use "kimi-k3" on Route P China-platform key from §1.3 : use provider kimi-coding-cn and put the key in KIMI CN API KEY instead. If config.yaml already has a provider the user actively uses, leave model: alone and just install the key — the user can switch with /model in-session; say so in the report. Same decision rule as §2. Usage for your verification and your report : hermes chat --provider kimi-coding --model k3 or kimi-k3 on Route P . 5. Pi Config is file-based. The two routes diverge here — Pi's built-in kimi-coding provider only accepts subscription Route S keys; a platform pay-per-token key gets a 401 from it. Route P needs a custom provider in ~/.pi/agent/models.json instead. SUB Route S — use the built-in provider, literally named "Kimi For Coding" kimi-coding , via ~/.pi/agent/auth.json. Pi's auth.json supports env interpolation, so prefer the no-plaintext form: since you persisted export KIMI API KEY in §3 do it even if Codex is absent, when Pi is present , write: mkdir -p ~/.pi/agent -f ~/.pi/agent/auth.json && cp ~/.pi/agent/auth.json ~/.pi/agent/auth.json.bak-kimi-$ date +%s merge, preserving other providers' credentials -f ~/.pi/agent/auth.json || echo '{}' ~/.pi/agent/auth.json TMP=$ mktemp jq '. + {"kimi-coding": {"type": "api key", "key": "$KIMI API KEY"}}' \ ~/.pi/agent/auth.json "$TMP" && mv "$TMP" ~/.pi/agent/auth.json chmod 600 ~/.pi/agent/auth.json Note: "$KIMI API KEY" here is a literal string — Pi interpolates it at runtime. Do not substitute the real key into this file. auth.json beats env vars in Pi's resolution order, so this entry wins cleanly. PLAT Route P — do not write the key under kimi-coding 401 . Define a custom Moonshot provider in ~/.pi/agent/models.json back up first; merge if the file exists, preserving other custom providers : mkdir -p ~/.pi/agent -f ~/.pi/agent/models.json && cp ~/.pi/agent/models.json ~/.pi/agent/models.json.bak-kimi-$ date +%s -f ~/.pi/agent/models.json || echo '{}' ~/.pi/agent/models.json TMP=$ mktemp jq '.providers = .providers // {} + { "moonshot": { "name": "Moonshot Kimi Platform ", "baseUrl": "https://api.moonshot.ai/v1", "api": "openai-completions", "apiKey": "KIMI API KEY", "models": {"id": "kimi-k3", "name": "Kimi K3", "reasoning": true, "contextWindow": 1048576, "maxTokens": 16384} } }' ~/.pi/agent/models.json "$TMP" && mv "$TMP" ~/.pi/agent/models.json chmod 600 ~/.pi/agent/models.json "apiKey": "KIMI API KEY" names the env var Pi reads at runtime — no plaintext key lands in this file, but the §3 rc-file export must exist. Verify the field names against the installed Pi version's custom-provider docs before writing; if they differ, adapt rather than guessing. Use China endpoint https://api.moonshot.cn/v1 for a .cn key. Model selection in Pi is per-session /model — no default-model file edit is needed or safe to guess. In the report, tell the user: "In Pi, pick Kimi K3 via /model provider: Kimi For Coding on Route S; Moonshot on Route P ." 6. Other OpenAI-compatible harnesses OpenCode, Cline, Aider, Zed, ... If the user asked for a harness not covered above and it supports custom OpenAI-compatible providers, configure its provider file with: Base URL https://api.moonshot.ai/v1, model kimi-k3, key from $KIMI API KEY Context window 1048576 if the harness has such a field Do not configure sampling parameters they're fixed server-side Find that harness's non-interactive config file yourself docs or --help ; apply the same rules: backup, merge, no wizards, no plaintext key in chat. 7. Verification all non-interactive Run for each configured harness; collect results for the final report. Use MODEL=k3 on Route S never k3 1m outside Claude Code env vars and MODEL=kimi-k3 on Route P. Harness Command Pass criterion API direct winning probe from §1.3 HTTP 200 Claude Code claude -p 'Reply with exactly: KIMI-OK' with the profile's env active; model comes from settings.json Output contains KIMI-OK Codex CLI Rung A/B codex exec 'Reply with exactly: KIMI-OK' Output contains KIMI-OK; startup banner shows the Kimi model Codex CLI Rung O ~/.local/share/codex-router/bin/doctor, then codex exec -m kimi-oauth/k3 'Reply with exactly: KIMI-OK' Doctor all-OK on core lines; output contains KIMI-OK. App picker entry only verifiable by the user after a full app restart — state it in the report, don't fail on it Hermes hermes chat --provider kimi-coding --model $MODEL -p 'Reply with exactly: KIMI-OK' use --print/non-interactive flag per hermes chat --help Output contains KIMI-OK Pi pi --provider kimi-coding --model k3 -p 'Reply with exactly: KIMI-OK' on Route S; pi --provider moonshot --model kimi-k3 -p '...' on Route P check pi --help for the print flag Output contains KIMI-OK If a harness's non-interactive flag differs from the above, discover it via --help rather than skipping verification. A verification failure is yours to debug see §8 — do not hand it back to the user until you've worked through §8. 8. Failure playbook work through before reporting failure Symptom Cause Fix 401 Claude Code Stale env entries in settings.json overriding your merge; or wrong-region key Re-read the file you wrote; try .cn endpoints "model not found" A model-tier variable still points at a Claude/GPT default Re-check all 7 model vars in §2 400 invalid thinking K2.x thinking param sent, or thinking disabled K3: remove thinking, use reasoning effort; never disable thinking Tool calls misbehave Claude Code Tool Search enabled ENABLE TOOL SEARCH must be the string "false" Premature compaction / context errors Wrong compact window CLAUDE CODE AUTO COMPACT WINDOW=1048576 Codex ignores provider Duplicate top-level model/model provider keys, or TOML parse error codex exec surfaces parse errors; validate the TOML Codex rejects wire api = "chat" Current Codex builds only support responses Expected — move to §3 Rung B LiteLLM proxy ; there is no direct Responses wiring api.moonshot.ai/v1/responses is 404 Codex hangs 15+ min before first output Hooks or MCP servers in ~/.codex/config.toml stall startup when combined with a custom provider Temporarily comment out mcp servers/hook blocks, retry, then re-enable one at a time to find the culprit Codex rejects config: unknown profiles. Profile block placed in config.toml; current Codex requires profiles in their own file Move the block to ~/.codex/kimi.config.toml §3 Every request via proxy fails / passthrough errors LiteLLM model uses the openai/ prefix, which doesn't translate Use moonshot/k3 Route S / moonshot/kimi-k3 Route P in kimi.yaml; restart the service Codex 404/protocol errors via proxy LiteLLM not running, wrong port, or upstream mapping wrong curl http://localhost:4141/v1/models; check systemctl --user status litellm-kimi Linux or launchctl list | grep com.kimi.litellm macOS ; verify api base/model in kimi.yaml Codex 401 via proxy Unit uses Environment=KIMI API KEY=<path value = the file path instead of EnvironmentFile= EnvironmentFile=%h/.config/litellm/.kimi-key with a KIMI API KEY=... line inside 0600 ; restart the unit Hermes uses wrong model config.yamlmodel: block not merged / overridden by CLI flags Literal $KIMI API KEY written but env var not exported in the shell Pi runs from Confirm the rc-file export from §3; restart shell context Pi 401 on Route P Platform pay-per-token key written under the kimi-coding provider, which only accepts subscription keys Remove the kimi-coding auth.json entry; use the custom moonshot provider in models.json §5 PLAT Sampling-param rejection Harness injects temperature etc. Remove from harness config; K3 fixes these server-side 401 with a valid subscription Route mix-up: subscription key sent to api.moonshot.ai, or platform key sent to api.kimi.com/coding/ Re-run §1.3 classification; the two consoles issue different keys Rung O: auth errors after previously working kimi login OAuth session expired or revoked Re-run §1.0 step 2; if dead, relay a fresh kimi login device-code URL to the user, then ./bin/doctor Rung O: Kimi missing from the App picker but CLI works Catalog loads only at app startup, or stale catalog User must fully quit Codex not just the window and reopen; if still missing, ./bin/refresh-catalog then quit/reopen again Rung O: doctor FAIL on service/router health Port 4100–4103 conflict or service not started systemctl --user status the router unit; if a foreign process owns the port, report it — never kill unknown processes on those ports Rung O: codex exec ignores the router Managed block removed/mangled in config.toml, or another tool overwrote openai base url Check the marked codex-router-managed block; ./bin/doctor --fix rebuilds it "model not found: kimi-k3" on Route S Platform model ID used against the subscription endpoint Subscription model IDs are k3 / kimi-for-coding, not kimi-k3 k3 1m rejected 1M form used outside Claude Code env vars, or plan is a 256K tier Use k3 everywhere else; downgrade to 256K config per §1.3 tier check 9. Final report to the user required format End with a short message containing: Which auth route was used per harness S subscription key / O OAuth session / P platform pay-per-token and, on Route S, which plan tier was detected 1M vs 256K . The 1–2 things the user must know: e.g. kimi-claude alias if you made an isolated profile; /model selection note for Pi; restart open harness sessions to pick up new config; on Rung O, fully quit and reopen the Codex App to load the new model catalog. Rollback one-liner: "To undo, restore the .bak-kimi- files listed above." No secrets in the report. No questions in the report. This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters Split-brain coding mode — the session model e.g. Claude Fable acts as orchestrator only, and ALL code writing is delegated to a Kimi worker running headless Claude Code against Moonshot's Anthropic-compatible API. Use when the user invokes /kimi-router or asks to route coding work to Kimi. Kimi Router You are now the orchestrator. Kimi is the executor. This mode stays on for the rest of the session. The one rule You never write or edit code. Not one line, not a "quick fix". Every code change — new files, edits, refactors, config, tests — is delegated to a Kimi worker. Your job is direction: understand the task, write the brief, review the result. You MAY still directly: read files, search, run tests/builds, run git commands, answer questions, and edit non-code documents the user asks you for e.g. this brief, notes . Setup once The worker needs these env vars put them in ~/.kimi/env or similar, never commit them : export KIMI API KEY="sk-..." Moonshot platform key export KIMI BASE URL="https://api.moonshot.ai/anthropic" Anthropic-compatible endpoint export KIMI MODEL="kimi-k3" exact model name from Moonshot docs If KIMI API KEY is not set in the environment, try source ~/.kimi/env first; if still missing, stop and ask the user for the key. The loop per coding task Understand — read the relevant files and any AGENTS.md/CLAUDE.md yourself. Decide what should change and where. Brief — write a self-contained task brief. The worker has zero conversation context, so the brief must include: Goal in one sentence, then exact requirements. Absolute paths of files to change and files to read for context/conventions . Constraints style, patterns to follow, what NOT to touch . Acceptance criteria what must pass/work when done . Delegate — spawn one worker serial, never parallel : env ANTHROPIC BASE URL="$KIMI BASE URL" \ ANTHROPIC AUTH TOKEN="$KIMI API KEY" \ ANTHROPIC MODEL="$KIMI MODEL" \ ANTHROPIC SMALL FAST MODEL="$KIMI MODEL" \ claude -p "<brief " \ --model "$KIMI MODEL" \ --permission-mode acceptEdits \ --settings '{"disableAllHooks": true}' \ --output-format stream-json --verbose \ --add-dir <project-root --model is required: without it, headless Claude Code uses the user's saved default model an Anthropic model , which the Kimi endpoint rejects. The env vars alone are not enough. --settings '{"disableAllHooks": true}' stops the user's global hooks e.g. an autogit Stop hook from firing inside the worker — otherwise the worker's changes can get auto-committed and even auto-pushed with the brief as the commit message before the orchestrator has reviewed them. The orchestrator owns git; workers must not commit. Trade-off: guardrail hooks are also skipped, so never combine this with a broad Bash allowlist. --output-format stream-json --verbose makes the worker emit one JSON line per step tool calls, edits, messages instead of staying silent until the end. Run the worker in the background, poll its output file every ~30s, and report progress to the user in plain English e.g. "Kimi is editing index.js now" . The final result JSON line is the worker's report. Run it from the project root. For anything non-trivial, run it in the background it can take minutes and poll the output instead of blocking. Review — after the worker exits: Read the full diff git diff . Check it against the acceptance criteria. Run the relevant tests/build. Iterate — if something is wrong or missing, do NOT fix it yourself. Write a new fix-it brief quote the failing test output / the specific defect and file:line and spawn another worker. Repeat until the acceptance criteria pass. Report — tell the user what Kimi changed, what you verified, and anything still open. Brief-writing tips One task per worker. Split big features into sequential briefs; each builds on the reviewed result of the last. Over-specify. Vague briefs produce vague code. Name functions, name files, paste relevant snippets. Tell the worker to follow existing patterns in named files rather than inventing new abstractions. Tell the worker its stdout is a report, not a chat: end with a summary of files changed. Failure handling Worker returns an API/auth error → surface it to the user; it's a setup problem, not a coding problem. Worker produces wrong code → fix-it brief step 5 . There is no "orchestrator takes over" fallback. This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters