openclaw/docs/providers/moonshot.md

summary, read_when, title

summary	read_when	title
Configure Moonshot K2 vs Kimi Coding (separate providers + keys)	You want Moonshot K2 (Moonshot Open Platform) vs Kimi Coding setup You need to understand separate endpoints, keys, and model refs You want copy/paste config for either provider	Moonshot AI

Moonshot AI (Kimi)

Moonshot provides the Kimi API with OpenAI-compatible endpoints. Configure the provider and set the default model to moonshot/kimi-k2.5, or use Kimi Coding with kimi/kimi-code.

Moonshot and Kimi Coding are **separate providers**. Keys are not interchangeable, endpoints differ, and model refs differ (`moonshot/...` vs `kimi/...`).

Built-in model catalog

Model ref	Name	Reasoning	Input	Context	Max output
moonshot/kimi-k2.5	Kimi K2.5	No	text, image	262,144	262,144
moonshot/kimi-k2-thinking	Kimi K2 Thinking	Yes	text	262,144	262,144
moonshot/kimi-k2-thinking-turbo	Kimi K2 Thinking Turbo	Yes	text	262,144	262,144
moonshot/kimi-k2-turbo	Kimi K2 Turbo	No	text	256,000	16,384

Getting started

Choose your provider and follow the setup steps.

**Best for:** Kimi K2 models via the Moonshot Open Platform.

<Steps>
  <Step title="Choose your endpoint region">
    | Auth choice            | Endpoint                       | Region        |
    | ---------------------- | ------------------------------ | ------------- |
    | `moonshot-api-key`     | `https://api.moonshot.ai/v1`   | International |
    | `moonshot-api-key-cn`  | `https://api.moonshot.cn/v1`   | China         |
  </Step>
  <Step title="Run onboarding">
    ```bash
    openclaw onboard --auth-choice moonshot-api-key
    ```

    Or for the China endpoint:

    ```bash
    openclaw onboard --auth-choice moonshot-api-key-cn
    ```
  </Step>
  <Step title="Set a default model">
    ```json5
    {
      agents: {
        defaults: {
          model: { primary: "moonshot/kimi-k2.5" },
        },
      },
    }
    ```
  </Step>
  <Step title="Verify models are available">
    ```bash
    openclaw models list --provider moonshot
    ```
  </Step>
</Steps>

### Config example

```json5
{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.5" },
      models: {
        // moonshot-kimi-k2-aliases:start
        "moonshot/kimi-k2.5": { alias: "Kimi K2.5" },
        "moonshot/kimi-k2-thinking": { alias: "Kimi K2 Thinking" },
        "moonshot/kimi-k2-thinking-turbo": { alias: "Kimi K2 Thinking Turbo" },
        "moonshot/kimi-k2-turbo": { alias: "Kimi K2 Turbo" },
        // moonshot-kimi-k2-aliases:end
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          // moonshot-kimi-k2-models:start
          {
            id: "kimi-k2.5",
            name: "Kimi K2.5",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
          {
            id: "kimi-k2-thinking",
            name: "Kimi K2 Thinking",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
          {
            id: "kimi-k2-thinking-turbo",
            name: "Kimi K2 Thinking Turbo",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
          {
            id: "kimi-k2-turbo",
            name: "Kimi K2 Turbo",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 256000,
            maxTokens: 16384,
          },
          // moonshot-kimi-k2-models:end
        ],
      },
    },
  },
}
```

**Best for:** code-focused tasks via the Kimi Coding endpoint.

<Note>
Kimi Coding uses a different API key and provider prefix (`kimi/...`) than Moonshot (`moonshot/...`). Legacy model ref `kimi/k2p5` remains accepted as a compatibility id.
</Note>

<Steps>
  <Step title="Run onboarding">
    ```bash
    openclaw onboard --auth-choice kimi-code-api-key
    ```
  </Step>
  <Step title="Set a default model">
    ```json5
    {
      agents: {
        defaults: {
          model: { primary: "kimi/kimi-code" },
        },
      },
    }
    ```
  </Step>
  <Step title="Verify the model is available">
    ```bash
    openclaw models list --provider kimi
    ```
  </Step>
</Steps>

### Config example

```json5
{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi/kimi-code" },
      models: {
        "kimi/kimi-code": { alias: "Kimi" },
      },
    },
  },
}
```

Kimi web search

OpenClaw also ships Kimi as a web_search provider, backed by Moonshot web search.

```bash openclaw configure --section web ```

Choose **Kimi** in the web-search section to store
`plugins.entries.moonshot.config.webSearch.*`.

Interactive setup prompts for:

| Setting             | Options                                                              |
| ------------------- | -------------------------------------------------------------------- |
| API region          | `https://api.moonshot.ai/v1` (international) or `https://api.moonshot.cn/v1` (China) |
| Web search model    | Defaults to `kimi-k2.5`                                             |

Config lives under plugins.entries.moonshot.config.webSearch:

{
  plugins: {
    entries: {
      moonshot: {
        config: {
          webSearch: {
            apiKey: "sk-...", // or use KIMI_API_KEY / MOONSHOT_API_KEY
            baseUrl: "https://api.moonshot.ai/v1",
            model: "kimi-k2.5",
          },
        },
      },
    },
  },
  tools: {
    web: {
      search: {
        provider: "kimi",
      },
    },
  },
}

Advanced

Moonshot Kimi supports binary native thinking:

- `thinking: { type: "enabled" }`
- `thinking: { type: "disabled" }`

Configure it per model via `agents.defaults.models.<provider/model>.params`:

```json5
{
  agents: {
    defaults: {
      models: {
        "moonshot/kimi-k2.5": {
          params: {
            thinking: { type: "disabled" },
          },
        },
      },
    },
  },
}
```

OpenClaw also maps runtime `/think` levels for Moonshot:

| `/think` level       | Moonshot behavior          |
| -------------------- | -------------------------- |
| `/think off`         | `thinking.type=disabled`   |
| Any non-off level    | `thinking.type=enabled`    |

<Warning>
When Moonshot thinking is enabled, `tool_choice` must be `auto` or `none`. OpenClaw normalizes incompatible `tool_choice` values to `auto` for compatibility.
</Warning>

Native Moonshot endpoints (`https://api.moonshot.ai/v1` and `https://api.moonshot.cn/v1`) advertise streaming usage compatibility on the shared `openai-completions` transport. OpenClaw keys that off endpoint capabilities, so compatible custom provider ids targeting the same native Moonshot hosts inherit the same streaming-usage behavior. | Provider | Model ref prefix | Endpoint | Auth env var | | ---------- | ---------------- | ----------------------------- | ------------------- | | Moonshot | `moonshot/` | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` | | Moonshot CN| `moonshot/` | `https://api.moonshot.cn/v1` | `MOONSHOT_API_KEY` | | Kimi Coding| `kimi/` | Kimi Coding endpoint | `KIMI_API_KEY` | | Web search | N/A | Same as Moonshot API region | `KIMI_API_KEY` or `MOONSHOT_API_KEY` |

- Kimi web search uses `KIMI_API_KEY` or `MOONSHOT_API_KEY`, and defaults to `https://api.moonshot.ai/v1` with model `kimi-k2.5`.
- Override pricing and context metadata in `models.providers` if needed.
- If Moonshot publishes different context limits for a model, adjust `contextWindow` accordingly.

Related

Choosing providers, model refs, and failover behavior. Configuring web search providers including Kimi. Full config schema for providers, models, and plugins. Moonshot API key management and documentation.