OpenClaw + Kimi K3: Setup and Migration from Retired K2.5

Kimi retired kimi-k2.5 from its own API on August 31, 2026, and names kimi-k3 as the replacement (Kimi model list). If your OpenClaw agent still points at moonshot/kimi-k2.5, move it to moonshot/kimi-k3. With a pay-as-you-go key from the international Kimi Open Platform, the switch takes the official Moonshot provider plugin and five commands:

openclaw plugins install @openclaw/moonshot-provider
openclaw gateway restart
openclaw onboard --auth-choice moonshot-api-key
openclaw models set moonshot/kimi-k3
openclaw models list --provider moonshot

The steps follow Kimi's OpenClaw guide, written against OpenClaw 2026.7.1, and OpenClaw's Moonshot page. Three situations call for something else:

• You pay for a Kimi Code membership. Use the separate Kimi Coding provider with its own key. Moonshot keys and Kimi Code keys are not interchangeable.
• You need K2.5 itself. Kimi's API no longer serves it, but as of September 24, 2026, five third-party hosts still do through OpenRouter.
• You don't want to keep a machine running. Kimi Claw hosts OpenClaw in Kimi's cloud with K3 preconfigured, but one-click deployment requires an Allegretto membership or above.

Pick the setup that matches your Kimi account

The key you hold decides most of the configuration. Each row is a separate provider in OpenClaw, with its own endpoint and model refs:

A few details can change the choice between the first rows:

• Reasoning effort. On the direct Moonshot route, OpenClaw always sends K3 requests with reasoning_effort: "max" and offers only /think max. The Kimi Coding provider maps /think levels to low, high or max effort and defaults to high.
• Price. K3 is Kimi's most expensive current model, at $3.00 input and $15.00 output per million tokens. The coding-focused moonshot/kimi-k2.7-code costs $0.95 and $4.00. Full prices are further down.
• Durability. K2.5 on OpenRouter depends on third parties that can drop it at any time.
• Uptime. A self-hosted OpenClaw runs only while its machine is on. Kimi Claw closes that gap for Allegretto members.

If OpenClaw isn't installed yet, start with the OpenClaw installation guide, which also covers connecting WhatsApp, Telegram and Discord. If you're still deciding whether Kimi is the right model for your agent, DeepSeek V4 Flash vs Kimi K3 vs GLM-5.2 compares it with two alternatives.

Set up Kimi K3 with the Moonshot provider

Before you start

You need:

• A working OpenClaw install with its gateway running.
• An API key from the international Kimi Open Platform. Keys from Kimi's China edition work only with the China endpoint, covered below.
• Account balance. Kimi unlocks K3 after a successful top-up of at least $1, and your cumulative top-up sets your rate-limit tier (Kimi K3 docs).
• An allowlist entry for your gateway's public IPv4 address, if your Kimi organization restricts API access by IP.

Install the plugin and run onboarding

The Moonshot provider ships as an external plugin, so install it before onboarding:

openclaw plugins install @openclaw/moonshot-provider
openclaw gateway restart
openclaw onboard --auth-choice moonshot-api-key

Kimi's guide walks through these wizard choices:

1. Auth provider: Moonshot
2. Auth method: Kimi API key (.ai)
3. Moonshot API key (.ai): paste your international key
4. Default model: moonshot/kimi-k3

Then set the model explicitly and confirm it's in the catalog:

openclaw models set moonshot/kimi-k3
openclaw models list --provider moonshot

According to OpenClaw's docs, fresh onboarding selects K3, while an existing install keeps its old default until you change it with models set. Type the key only into the wizard or a terminal. Kimi's guide warns against putting it in docs, screenshots, repositories or chat messages.

Where MOONSHOT_API_KEY and the model setting live

Neither OpenClaw's Moonshot docs nor Kimi's guide uses a settings.yaml or config.yaml. The key and the model live in different places.

The key. Onboarding asks for it and saves the connection. To manage it yourself, OpenClaw reads MOONSHOT_API_KEY from the gateway's environment. On a gateway install, that means a line in ~/.openclaw/.env:

MOONSHOT_API_KEY=sk-...

The model. Model and provider settings live in ~/.openclaw/openclaw.json, with the default model under agents.defaults.model.primary:

{
  "agents": {
    "defaults": {
      "model": { "primary": "moonshot/kimi-k3" }
    }
  }
}

OpenClaw's config example also shows the key inline under env.vars in openclaw.json. That works, but it adds one more file that holds the secret.

China-edition accounts

If your key comes from Kimi's China edition (platform.kimi.com), onboard with openclaw onboard --auth-choice moonshot-api-key-cn. That points the provider at https://api.moonshot.cn/v1. The China edition is a separate account system with its own keys and a CNY price list, so the USD prices below don't apply to it.

What OpenClaw sends to K3

K3 always reasons. Kimi's API accepts reasoning_effort values of low, high and max, but on the direct Moonshot route OpenClaw sends max every time and ignores stale lower or off settings. K3 also fixes temperature (1.0), top_p (0.95), n (1) and both penalties (0). OpenClaw strips overrides for those fields, so a temperature you tuned for K2.5 no longer does anything.

K3 takes text, images and video with a 1,048,576-token context window. To send image and video inputs through K3 as well, Kimi's guide adds this to openclaw.json:

{
  "agents": {
    "defaults": {
      "imageModel": "moonshot/kimi-k3"
    }
  },
  "tools": {
    "media": {
      "image": { "models": [{ "type": "provider", "provider": "moonshot", "model": "kimi-k3", "capabilities": ["image"] }] },
      "video": { "models": [{ "type": "provider", "provider": "moonshot", "model": "kimi-k3", "capabilities": ["video"] }] }
    }
  }
}

Migrate an old moonshot/kimi-k2.5 setup

Kimi retired these models on its API and points each of them to kimi-k3:

If any of them is still your default, a fallback, an alias or your image model, work through these steps.

1. Update the provider and restart the gateway. Older setups that never installed the plugin need openclaw plugins install @openclaw/moonshot-provider instead of update.

openclaw plugins update @openclaw/moonshot-provider
openclaw gateway restart

2. Find every reference to a retired model.

grep -nE 'kimi-k2\.5|kimi-k2-(0905|0711|turbo|thinking)|moonshot-v1|kimi-latest' ~/.openclaw/openclaw.json

Hits can include the default model, aliases under agents.defaults.models, agents.defaults.imageModel, fallback entries and hand-added rows under models.providers.moonshot.models.

3. Set K3 as the default.

openclaw models set moonshot/kimi-k3

4. Replace or delete the remaining hits. Swap each retired ref for moonshot/kimi-k3, or for moonshot/kimi-k2.7-code where a cheaper coding model is enough. Delete per-model params written for K2.5, such as a thinking block. OpenClaw drops the K2-only thinking field for K3 anyway, so leftovers only obscure what's actually in effect.

5. Restart the gateway and verify with the checks in the next section. If K3 still doesn't appear after the update, "K3 is missing from the model list" under Troubleshooting gives the manual config entry.

Two kinds of K2.5-era configs keep resolving without edits:

• Kimi Coding refs kimi/k2p5 and kimi/kimi-code are legacy aliases that OpenClaw normalizes to kimi/kimi-for-coding.
• openrouter/moonshotai/kimi-k2.5 still routes as of September 24, 2026, because third-party hosts serve it. The OpenRouter section below covers what that depends on.

Confirm OpenClaw is really using K3

Check three places after the restart:

1. Control UI. Open the address that onboarding or the gateway printed. The bottom of the Control UI should read kimi-k3 · moonshot.
2. Catalog. openclaw models list --provider moonshot should include kimi-k3.
3. A live call. OpenClaw's docs give a smoke test that runs in a throwaway config and state directory, so your normal sessions stay untouched:

OPENCLAW_CONFIG_PATH=/tmp/openclaw-kimi/openclaw.json \
OPENCLAW_STATE_DIR=/tmp/openclaw-kimi \
openclaw agent --local \
  --session-id live-kimi-cost \
  --message 'Reply exactly: KIMI_LIVE_OK' \
  --thinking max \
  --json

The JSON output should report provider: "moonshot" and model: "kimi-k3". If the isolated run can't authenticate, export MOONSHOT_API_KEY in the same shell and run it again.

For cost, /usage cost (like /status and /usage full) turns streamed usage into a local USD estimate at the catalog's K3 rates. The estimate covers input, output and cache reads. The catalog prices cache writes at $0, while Kimi bills them, so your Kimi account's billing is the number to trust.

Once K3 answers, connecting a chat app is a separate step. OpenClaw Telegram Setup walks through Telegram.

What K3 costs compared with Kimi's cheaper models

K3 is Kimi's most capable model, with 2.8 trillion parameters, native visual understanding and a 1M-token context window. It's also the priciest. Prices on the international platform as of September 24, 2026, in USD per million tokens and excluding tax (Kimi pricing):

K3 also bills cache writes separately: $3.00 per million tokens with the default 5-minute TTL, or $6.00 with a 1-hour TTL. Input that hits the cache is billed only at the cached-input rate.

Kimi positions K2.7 Code as its dedicated coding model and says the HighSpeed variant outputs about 180 tokens per second, up to 260 in short contexts. K2.6 handles images and text, supports thinking and non-thinking modes, and is the default model behind Kimi web search in OpenClaw.

A worked example. Suppose a day of agent work sends 2,000,000 input tokens, of which 1,600,000 hit the cache, and gets 200,000 output tokens back. Cost per model is (uncached input × input price + cached input × cached price + output × output price) ÷ 1,000,000:

• K3: (400,000 × $3.00 + 1,600,000 × $0.30 + 200,000 × $15.00) ÷ 1,000,000 = $1.20 + $0.48 + $3.00 = $4.68
• K2.7 Code: (400,000 × $0.95 + 1,600,000 × $0.19 + 200,000 × $4.00) ÷ 1,000,000 = $0.38 + $0.304 + $0.80 = $1.48

Both totals leave out tax and K3's separate cache-write charge. Output makes up most of the K3 total in this mix, and K3's output rate is 3.75 times K2.7 Code's, so agents that write long replies widen the gap. Plug in your own token counts for a closer estimate.

Use a Kimi Code membership with the Kimi Coding provider

Kimi Coding is a different provider from Moonshot. It has its own plugin, a key from the Kimi Code Console, its own endpoint and kimi/ model refs. An Open Platform key fails here, and a Kimi Code key fails on the Moonshot provider.

openclaw plugins install @openclaw/kimi-provider
openclaw onboard --auth-choice kimi-code-api-key
openclaw models list --provider kimi

Set the default model in ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": { "primary": "kimi/kimi-for-coding" }
    }
  }
}

The current refs are kimi/kimi-for-coding, kimi/kimi-for-coding-highspeed, kimi/k3 (up to 1,048,576 tokens of context, depending on your membership tier) and kimi/k3-256k (262,144 tokens, lighter on quota). On this provider K3 uses adaptive thinking and defaults to high effort: /think minimal or low maps to low effort; medium, high or adaptive map to high; xhigh or max map to max; and /think off disables thinking.

The plugin talks to https://api.kimi.com/coding/ in the Anthropic Messages format and reads KIMI_API_KEY. Membership prices and quotas are on Kimi's own pricing page, and your plan may enforce a lower live context limit than the catalog shows (OpenClaw Moonshot and Kimi Coding docs).

Keep Kimi K2.5 through OpenRouter

As of September 24, 2026, OpenRouter still lists moonshotai/kimi-k2.5, but Moonshot AI isn't among its providers. Five third-party endpoints serve it:

These are OpenRouter's listed prices, rounded to the cent, not Moonshot's. Hosts can drop the model at any time, so check OpenRouter's Kimi K2.5 page before depending on it.

Route OpenClaw there with an OpenRouter key:

openclaw onboard --auth-choice openrouter-api-key
openclaw models set openrouter/moonshotai/kimi-k2.5

Create the key at openrouter.ai/keys, or run openclaw onboard --auth-choice openrouter-oauth to sign in through the browser instead. Onboarding defaults to openrouter/auto, so the models set step matters. OpenClaw reads the key from OPENROUTER_API_KEY (OpenClaw OpenRouter docs).

To keep every K2.5 request on one host, add a provider preference for that model in ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "models": {
        "openrouter/moonshotai/kimi-k2.5": {
          "params": {
            "provider": { "order": ["novita"], "allow_fallbacks": false }
          }
        }
      }
    }
  }
}

Copy the exact slug with the copy button next to the host's name on OpenRouter's model page (OpenRouter provider routing). With allow_fallbacks: false, requests fail instead of moving to another host when yours goes down or stops serving K2.5. That's noisier, but you notice right away instead of silently landing on a host with different limits.

The same OpenRouter key reaches K3 as openrouter/moonshotai/kimi-k3. As of September 24, 2026, OpenRouter lists 20 K3 endpoints, including Moonshot AI's own at $3 input and $15 output per million tokens, and some third-party endpoints list lower prices.

The case for staying on K2.5 is price: output at $2.25–$3.33 per million tokens against $15.00 for K3 on Kimi's API. The trade-off is a model that its remaining hosts can drop without notice.

Kimi Claw: OpenClaw hosted by Kimi

Kimi Claw runs OpenClaw in Kimi's cloud. Click Create on the Kimi Claw page and Kimi deploys it in about a minute, with Kimi K3 configured automatically (Kimi Claw). Kimi lists 24/7 uptime, 40GB of cloud storage, more than 5,000 ClawHub skills, scheduled tasks and a web-based SSH terminal under Settings → Open Terminal.

The condition is the plan. One-click cloud deployment requires an Allegretto membership or above, and Kimi publishes the price on its membership plans page. If you already run OpenClaw on your own machine, Link existing OpenClaw connects it to Kimi for free by installing Kimi's plugin on that device. The agent still runs on your hardware, so it stops when the machine does.

Choose Kimi Claw when you want an always-on agent without running a server and the Allegretto plan is acceptable. Self-host when you already have a machine that stays on, or when you'd rather pay per token with your own key.

Optional: use Kimi as OpenClaw's web search provider

The Moonshot plugin also registers Kimi as a web_search provider backed by Moonshot's native web search (OpenClaw Kimi search docs). It returns one synthesized answer with inline citations rather than a ranked list of results.

openclaw configure --section web

Choose Kimi, then pick the API region (https://api.moonshot.ai/v1 or https://api.moonshot.cn/v1 ) and the search model, which defaults to kimi-k2.6. Settings land under plugins.entries.moonshot.config.webSearch, and the key comes from KIMI_API_KEY or MOONSHOT_API_KEY. If chat already uses the China host and the search baseUrl is unset, search reuses the China host, so a .cn key doesn't hit the international endpoint by mistake. If several search providers have credentials, set tools.web.search.provider to kimi. Kimi lists web search pricing on a separate page from the chat model prices above.

Two cautions apply. If Kimi answers without search grounding, OpenClaw returns a kimi_web_search_ungrounded error instead of passing the text along; retry, switch to a structured provider such as Brave, or use web_fetch when you already have the URL. And Kimi's K3 documentation currently says its web search "is being updated and is not recommended for production workflows in the near term."

Troubleshooting Kimi K3 and K2.5 in OpenClaw

401 or "Invalid Authentication"

This is usually a mismatch between the key and the provider:

• Wrong kind of key. A Kimi Code key on the Moonshot provider fails, and so does an Open Platform key on Kimi Coding.
• Wrong region. International keys go with moonshot-api-key and api.moonshot.ai; China-edition keys go with moonshot-api-key-cn and api.moonshot.cn. A .cn key sent to the international endpoint gets a 401.
• An old key in the environment. Rerun onboarding with the auth choice for your region and enter the right key again. Check that ~/.openclaw/.env or your shell doesn't still export an old MOONSHOT_API_KEY.

For key and rate-limit errors outside Kimi, see OpenClaw API Key Errors and Rate Limiting.

The Moonshot option is missing from onboarding

The plugin isn't installed, or the gateway hasn't picked it up yet:

openclaw plugins install @openclaw/moonshot-provider
openclaw gateway restart

K3 is missing from the model list

Work down this list and run openclaw models list --provider moonshot after each step:

1. Finish authentication, then run openclaw models set moonshot/kimi-k3.
2. Run openclaw plugins update @openclaw/moonshot-provider, then openclaw gateway restart.
3. Add K3 by hand to models.providers.moonshot.models in ~/.openclaw/openclaw.json, then run openclaw models set moonshot/kimi-k3 again.

This is Kimi's entry for step 3. If that models array already has entries, add the K3 object next to them instead of replacing the array. China-edition accounts use https://api.moonshot.cn/v1 as baseUrl.

{
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.ai/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-k3",
            "name": "Kimi K3",
            "reasoning": true,
            "input": ["text", "image", "video"],
            "contextWindow": 1048576,
            "maxTokens": 8192,
            "thinkingLevelMap": {
              "off": null,
              "minimal": "max",
              "low": "max",
              "medium": "max",
              "high": "max",
              "xhigh": "max",
              "max": "max"
            },
            "compat": {
              "maxTokensField": "max_tokens",
              "supportsUsageInStreaming": false,
              "requiresStringContent": true,
              "supportsReasoningEffort": true,
              "supportedReasoningEfforts": ["minimal", "low", "medium", "high", "xhigh", "max"]
            }
          }
        ]
      }
    }
  }
}

Kimi sets maxTokens to 8,192 as OpenClaw's per-reply limit, so the 1M input window isn't mistaken for a 1M output limit. The three compat flags stay because K3 handles max_completion_tokens, streaming usage and array-form text content differently. Use this entry only when the updated plugin still lacks K3.

You still see the "Moonshot AI (Kimi K2.5)" preset

That's the historical preset, retired together with K2.5. It may still appear in screenshots of the old onboarding flow. Don't select it or keep it as the default. Set moonshot/kimi-k3 as above.

OpenRouter K2.5 requests start failing

Check the host list on OpenRouter's Kimi K2.5 page. If your pinned host is gone, point order at one that's still listed, remove the pin, or move to openrouter/moonshotai/kimi-k3 or the Moonshot provider.

Kimi Claw doesn't respond

Refresh the page first, since the connection may have dropped. If that doesn't help, go to Settings and click Restart Kimi Claw. If it still won't answer, use Auto-fix Kimi Claw in the same place. Restarting the OpenClaw gateway from the web terminal also cuts the terminal's connection, because the terminal and the plugins share one channel.

For other OpenClaw errors, see the OpenClaw Error Troubleshooting Center.

FAQ

Is Kimi free to use in OpenClaw?

OpenClaw itself is free, open-source software, but Kimi's models are not. The Kimi API bills per token, and K3 unlocks only after a successful top-up of at least $1 on the Kimi Open Platform. Kimi Claw's one-click cloud deployment needs an Allegretto membership or above. Linking an OpenClaw you already run to Kimi is free.

Can I still use Kimi K2.5 in OpenClaw?

Not through Kimi's API, which retired kimi-k2.5 on August 31, 2026. As of September 24, 2026, openrouter/moonshotai/kimi-k2.5 can still be routed to five third-party hosts at $0.45–$0.60 input and $2.25–$3.33 output per million tokens, with no guarantee that they keep serving it.

Where do I put MOONSHOT_API_KEY: settings.yaml or config.yaml?

Neither OpenClaw's docs nor Kimi's guide uses a YAML file for this. Onboarding saves the key for you. To set it yourself, put MOONSHOT_API_KEY in the gateway's environment, which on a gateway install means ~/.openclaw/.env. The default model lives in ~/.openclaw/openclaw.json under agents.defaults.model.primary.

Is Kimi Claw the same as OpenClaw?

Kimi Claw is OpenClaw run for you in Kimi's cloud, with K3 configured automatically. OpenClaw itself, formerly called Clawdbot and Moltbot, is the open-source agent you install and configure on your own machine.

Why does OpenClaw ignore /think low with K3?

On the direct Moonshot route, OpenClaw sends every K3 request at max effort and ignores lower or off settings. If you want lower effort inside OpenClaw, the Kimi Coding provider maps /think minimal and /think low to K3's low effort.