# Kimi Code CLI Setup

> **Last verified**: 2026-10-13 · 📄 Per official docs (Kimi Code CLI 2.1.1)

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (`type = "anthropic"`) · GPT ✅ · Chinese models ✅ (`type = "openai"`) · Gemini ❌ — QCode does not offer the Gemini family, please use Claude, GPT or a Chinese model |
| Protocol & Base URL | Anthropic Messages: `https://api.qcode.cc/api` · OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` |
| Where to configure | `~/.kimi-code/config.toml` — one `[providers.<name>]` table per protocol, one `[models.<alias>]` entry per model |
| Official docs | [moonshotai.github.io/kimi-code](https://moonshotai.github.io/kimi-code/en/) |

[Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) is Moonshot AI's coding agent that runs in the terminal. Its own documentation describes three ways to supply a model: the Kimi Code managed service with one-click login, "connecting Claude with an Anthropic API key, or connecting third-party inference services via the OpenAI-compatible protocol". Those last two are exactly the endpoints QCode exposes, so one QCode key covers Claude, GPT and the Chinese families inside the same tool. The latest release at the time of writing is 2.1.1 (2026-09-24).

## Which protocol

The `type` field in the `[providers.<name>]` table selects the protocol implementation. The official reference lists six values — `kimi`, `anthropic`, `openai`, `openai_responses`, `google-genai`, `vertexai` — and you need two of them:

| Models you want | `type` | `base_url` |
|---|---|---|
| `claude-sonnet-5`, `claude-opus-5`, `claude-haiku-5-5` | `anthropic` | `https://api.qcode.cc/api` |
| `gpt-6.1-sol`, `gpt-6-sol`, and the Chinese families | `openai` | `https://api.qcode.cc/openai/v1` |

🔴 **Never point a Claude model at the OpenAI-compatible endpoint.** QCode serves the Claude family only on the Anthropic Messages endpoint; a `claude-*` id sent to `https://api.qcode.cc/openai/v1` is refused. The two endpoints are not interchangeable — see [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

Write the Base URL exactly as above: stop at `/api` or `/openai/v1`, do **not** append `/v1/messages` or `/chat/completions`, and do **not** leave a trailing slash.

## Install

The docs offer two routes: the official install script, recommended because it needs no pre-installed Node.js, and a global npm install.

```sh
# macOS / Linux
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

# Windows (PowerShell)
irm https://code.kimi.com/kimi-code/install.ps1 | iex

# npm — check your runtime first with: node --version
npm install -g @moonshot-ai/kimi-code
```

The npm route **requires Node.js 22.19.0 or later**. The script downloads the latest release, verifies the checksum and places the `kimi` executable on your `PATH`. Confirm the binary, then move into your project directory and run `kimi` to open the interactive UI:

```sh
kimi --version
cd your-project
kimi
```

## Configure Claude (`type = "anthropic"`)

Credentials live in the config file only. The docs are explicit that the CLI "does **not** fall back to shell environment variables automatically: running `export KIMI_API_KEY` in the terminal does not give any provider its key" — either the key is written into the file, or `api_key_env` names a variable the CLI reads on every request.

```toml
# ~/.kimi-code/config.toml
default_model = "claude-sonnet-5"

[providers.qcode]
type = "anthropic"
base_url = "https://api.qcode.cc/api"
api_key_env = "QCODE_API_KEY"

[models."claude-sonnet-5"]
provider = "qcode"
model = "claude-sonnet-5"
max_context_size = 262144
```

```sh
export QCODE_API_KEY=cr_your_qcode_key
```

`qcode` is just the provider name you invent for it — every `[models.<alias>]` entry points back at it through its required `provider` field. If you would rather keep no environment variable, replace `api_key_env` with `api_key = "cr_your_qcode_key"`; the docs note that value is stored as plain text in the config file, and the two fields are mutually exclusive alternatives — set exactly one.

| Field | Table | What goes in it |
|---|---|---|
| `type` | providers | `anthropic`, the provider documented "For connecting to the Claude API" |
| `base_url` | providers | `https://api.qcode.cc/api`; left out, the type follows the Anthropic SDK default |
| `api_key` / `api_key_env` | providers | the key itself, or the name of the variable holding it |
| `custom_headers` | providers | optional table of extra HTTP headers attached to each request |
| `provider` | models | required — the provider name defined above |
| `model` | models | required — the id sent to the server, e.g. `claude-sonnet-5` |
| `max_context_size` | models | required, at least 1 token — the `262144` in the example above is a placeholder; use the context length your model actually documents |
| `max_output_size` | models | optional output cap that maps to `max_tokens`; currently only the `anthropic` provider reads it |

> **Mainland China**: the Anthropic endpoint also answers on `https://asia.qcode.cc/api` and `https://us.qcode.cc/api`, with the same key — swap the host in `base_url` and nothing else.
> **Capabilities**: standard Claude model names get vision, tool use and Thinking on their own; a name the CLI does not cover needs `capabilities` declared explicitly on `[models.<alias>]` (`thinking`, `image_in`, `tool_use`, …), and those tags are only ever added, never removed.

## Configure GPT and Chinese models (`type = "openai"`)

The same file, the other endpoint. The `openai` type is documented for the OpenAI Chat Completions protocol "as well as any third-party service compatible with that protocol (override `base_url` as needed)" — overriding it is what makes this a QCode connection instead of an OpenAI one, since the built-in default is `https://api.openai.com/v1`.

```toml
[providers.qcode-openai]
type = "openai"
base_url = "https://api.qcode.cc/openai/v1"
api_key_env = "QCODE_API_KEY"

[models."gpt-6.1-sol"]
provider = "qcode-openai"
model = "gpt-6.1-sol"
max_context_size = 262144

[models."deepseek-v4.1-flash"]
provider = "qcode-openai"
model = "deepseek-v4.1-flash"
max_context_size = 262144

[models."qwen3.8-max"]
provider = "qcode-openai"
model = "qwen3.8-max"
max_context_size = 262144
```

- **Quote aliases that contain a dot.** `gpt-6.1-sol` and `qwen3.8-max` must be written `[models."qwen3.8-max"]`; unquoted, TOML reads the dot as a nested-table separator. Field names themselves are snake_case throughout (`default_model`, `max_context_size`).
- The numbers above are placeholders for a required field — use the context length that the model itself documents. Billing is per token; per-model rates are listed on [qcode.cc/models](https://qcode.cc/models).
- Both providers can coexist in one config. Pick the model per session with `-m <alias>`, which the docs rank above the config file but valid for that startup only, or switch inside the TUI with `/model`. `default_model` has to be one of the aliases you defined.
- Reasoning output: the CLI handles the `reasoning_content` field and `reasoning_effort` injection itself for third-party reasoning models; if a gateway returns that content under a non-standard field name, set `reasoning_key` on the model alias.
- More ids for this endpoint are in [Chinese Models](/docs/usage/cn-models). `claude-*` ids do **not** work here.

## Verify

Check the files without launching the TUI:

```sh
kimi doctor
kimi doctor config
```

`kimi doctor` validates `config.toml` and `tui.toml` without starting the TUI or modifying either file, and exits `0` when every checked file is valid or skipped, `1` when one is missing or invalid. The documented scope is validating those two files; the docs do not describe it as testing whether the endpoint answers.

Check what the CLI actually registered:

```sh
kimi provider list
```

Then open the TUI and type `/provider`. That is the interactive provider manager, where you can view, add and remove configured providers; `kimi provider` is its non-interactive equivalent for scripts and CI.

Finally, exercise the endpoint directly (substitute your own key):

```bash
KEY="cr_your_qcode_key"
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

This page was assembled from the documentation, and **no request here was run against a live key**, so no status code is promised. Read the JSON error body: it separates a wrong path or wrong key from a model that is not offered on that endpoint.

> There is a third-party shortcut, `kimi provider catalog add anthropic --api-key sk-ant-... --default-model claude-opus-4-7`, where the catalog supplies protocol, base URL and model list and `--base-url` overrides the endpoint (`--default-model` writes `default_model` as `<providerId>/<modelId>`). The id in that example comes from the public catalog, not from QCode, and this page has not verified whether QCode is listed there, so the TOML route above is what this page recommends.

## Troubleshooting and known limitations

| Symptom | What the docs say | What to do |
|---|---|---|
| Startup fails, complaining a provider has no credentials | Priority is `api_key` or `api_key_env` (set exactly one), then the `[providers.<name>.env]` key, and if all are absent startup fails with an error | The conventional names for this type are `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL`, written inside `[providers.qcode.env]` — they are config-file keys, not shell lookups. During a `/models` refresh a provider with an unset variable is reported as failed without affecting the others |
| `export ANTHROPIC_API_KEY=…` appears to be ignored | Shell variables are not a general fallback; the two channels that do read the shell are a provider's `api_key_env` and the `KIMI_MODEL_*` family | Use `api_key_env`. `KIMI_MODEL_PROVIDER_TYPE` accepts `kimi`, `anthropic`, `openai`, and setting `KIMI_MODEL_NAME` builds a temporary provider in memory that disappears on restart |
| Editing the file seems to do nothing | Startup options outrank the file for the current session; the file is read at startup | Restart `kimi`, or run `/reload` to apply the latest `config.toml` in the running session |
| Config error or alias not found when a dotted alias is left unquoted | `default_model` must be defined in `models`, and an unquoted dotted alias becomes a nested table | Quote the alias: `[models."qwen3.8-max"]` |
| `404` or a path error | The docs say nothing about how a third-party gateway assembles the path | `base_url` must stop at `/api` (Claude) or `/openai/v1` (GPT, Chinese), with no trailing slash and no API path appended |
| Claude refused on the `openai` provider | — | QCode does not serve the Claude family there; move it to `type = "anthropic"` |
| One project needs a different endpoint | There is no project-level config file mechanism — Kimi Code reads a single user-level file, named `config.toml` wherever it lives | Point `KIMI_CODE_HOME` at a per-project data directory before launching |

Beyond the tool itself:

- **Gemini**: Kimi Code has a `google-genai` type for direct Google Gemini access, but QCode does not offer the Gemini family. Use Claude, GPT or a Chinese model.
- **luna**: QCode does not offer `gpt-6-luna` or `gpt-5.6-luna`; pick another GPT id such as `gpt-6.1-sol`, `gpt-6-sol` or `gpt-5.6-terra`.
- `max_output_size` is read by the `anthropic` provider only, so an output cap set on an `openai` alias has no effect.
- Which model to pick for which job is covered in [Model Selection](/docs/usage/model-selection); if the request fails for reasons outside this tool, work through [Troubleshooting](/docs/reference/troubleshooting).

## Related

- [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) — protocol against model family
- [Tool Compatibility](/docs/ide/tool-compatibility) — which tools speak which protocol
- [Chinese Models](/docs/usage/cn-models) — ids and paths for the OpenAI endpoint
- [Model Selection](/docs/usage/model-selection) — matching model to task
- [OpenCode Setup](/docs/ide/opencode) — another terminal agent on the same two endpoints