Preecha

Posted on Nov 2

How to Use Kimi K2.5 with Claude Code

What if you could keep Claude Code's agentic workflow while tapping Kimi K2.5's trillion-parameter reasoning engine? By routing Claude Code's Anthropic Messages API calls through Moonshot's compatible endpoint, you combine one of the best coding interfaces with one of the most capable open-source models available today.

Try Apidog today

The Opportunity: Breaking Vendor Lock-in

Claude Code has established itself as a premier agentic coding tool — sophisticated repository scanning, intelligent file editing, seamless terminal integration. But proprietary model providers come with constraints: rate limits, geographic restrictions, pricing concerns. Meanwhile, Moonshot AI's Kimi K2.5 delivers comparable coding performance with its 15 trillion-token training dataset, native multimodal capabilities, and full API compatibility.

The integration works because Claude Code communicates via the Anthropic Messages API specification, and Moonshot exposes an identical endpoint at /anthropic/v1/messages. You redirect Claude Code's backend traffic to Kimi K2.5 without modifying the CLI tool itself — keeping your existing muscle memory while unlocking an alternative model provider.

💡 Want a great API testing tool that generates beautiful API Documentation? Want an integrated, all-in-one platform for your developer team to work together with maximum productivity? Apidog delivers all your demands and replaces Postman at a much more affordable price!

How the Anthropic Compatibility Layer Works

Before configuring anything, understand what happens under the hood. Claude Code expects an Anthropic-style API response structure: specific message formatting, streaming protocols, and tool-calling conventions. Moonshot's compatibility layer translates between these formats, letting Kimi K2.5 respond to prompts as if it were Claude Sonnet or Opus.

Moonshot operates two primary domains depending on your location:

Global: https://api.moonshot.ai/anthropic
China: https://api.moonshot.cn/anthropic

Both endpoints route to the same underlying infrastructure but optimize for regional latency and compliance requirements. Moonshot also supports OpenAI-compatible (/v1/chat/completions) and Anthropic-compatible (/anthropic/v1/messages) endpoints simultaneously — Claude Code specifically requires the latter.

When configured correctly, Claude Code sends its standard payload — system prompts, conversation history, tool definitions — to Moonshot's endpoint. Kimi K2.5 processes these requests and returns responses Claude Code interprets natively, so file editing, bash command execution, and codebase analysis all work without modification.

Quick Setup: Environment Variables

For immediate testing or temporary usage, environment variables are the fastest path — no file modifications, works in any terminal session.

Prerequisite: a valid Moonshot API key from the Moonshot Open Platform.

Export the following variables, then launch Claude Code:

# Route Claude Code to Moonshot's Anthropic-compatible endpoint
export ANTHROPIC_BASE_URL="https://api.moonshot.ai/anthropic"

# Authenticate using your Moonshot key (Claude Code interprets this as Anthropic auth)
export ANTHROPIC_AUTH_TOKEN="YOUR_MOONSHOT_API_KEY"

# Specify Kimi K2.5 as the primary model
export ANTHROPIC_MODEL="kimi-k2.5"

# Ensure fast operations also use K2.5 (avoids model switching errors)
export ANTHROPIC_SMALL_FAST_MODEL="kimi-k2.5"

# Optional: reduce non-essential API traffic for cleaner logs
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# Optional: extend timeout for complex reasoning tasks (10 minutes)
export API_TIMEOUT_MS=600000

# Launch Claude Code
claude

If you operate within mainland China, substitute the base URL:

export ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic"

These variables direct all API traffic to Moonshot's servers rather than Anthropic's infrastructure. ANTHROPIC_AUTH_TOKEN accepts your Moonshot key because Claude Code sends it in the Authorization header, which Moonshot validates against its own key database.

💡 Pro Tip: Test your API key in Apidog before editing configuration files. This prevents downtime from authentication errors.

Persistent Configuration with settings.json

Environment variables work for single sessions, but maintaining them across terminal restarts is tedious. Claude Code supports hierarchical JSON configuration through settings.json files — persistent, project-specific, or user-global.

Create or edit ~/.claude/settings.json in your home directory:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.ai/anthropic",
    [REDACTED CREDENTIAL],
    "ANTHROPIC_MODEL": "kimi-k2.5",
    "ANTHROPIC_SMALL_FAST_MODEL": "kimi-k2.5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "API_TIMEOUT_MS": "600000"
  }
}

This configuration applies globally across all projects. For granular control, use Claude Code's configuration hierarchy:

Managed settings (/etc/claude-code/ or /Library/Application Support/ClaudeCode/) — organization-wide policies
User settings (~/.claude/settings.json) — your personal defaults
Project settings (.claude/settings.json) — shared team configuration
Local project settings (.claude/settings.local.json) — personal project overrides

For team environments, commit .claude/settings.json to your repository with the shared configuration, and keep individual API keys in .claude/settings.local.json (which Claude Code automatically gitignores). For example:

.claude/settings.json (committed):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.moonshot.ai/anthropic",
    "ANTHROPIC_MODEL": "kimi-k2.5",
    "ANTHROPIC_SMALL_FAST_MODEL": "kimi-k2.5"
  }
}

.claude/settings.local.json (gitignored, personal):

{
  "env": {
    [REDACTED CREDENTIAL]
  }
}

After modifying these files, completely exit Claude Code and restart your terminal so the configuration loads fresh. Unlike environment variables, settings.json changes persist across system reboots and apply automatically whenever you launch claude.

Verification and Troubleshooting

Verify the integration before trusting it with production code. Launch Claude Code and start a test conversation:

What model you are currently running, and which API endpoint are you connected to?

Kimi K2.5 should respond with its model identifier and confirm the Moonshot endpoint. If you receive errors, work through these common issues systematically.

Authentication Failures (401 errors)

Use ANTHROPIC_AUTH_TOKEN (not ANTHROPIC_API_KEY) when using third-party endpoints
Confirm your Moonshot API key is active and has available credits
Ensure the base URL ends with /anthropic — not /v1, and no trailing slashes

Model Recognition Errors

Check that ANTHROPIC_MODEL and ANTHROPIC_SMALL_FAST_MODEL both specify kimi-k2.5
If Claude Code defaults to Anthropic's models, your environment variables aren't loading — verify your shell exports or JSON syntax

Timeouts During Long Operations

Increase API_TIMEOUT_MS beyond 600000 for extensive refactoring tasks
Set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 to reduce background API calls competing with your primary requests

Permission and Context Issues

If Claude Code prompts for login despite configuration, check that hasCompletedOnboarding is set to true in ~/.claude.json (a known issue on Windows)
Verify no conflicting ANTHROPIC_API_KEY environment variable overrides your ANTHROPIC_AUTH_TOKEN

For debugging, launch Claude Code with verbose logging or run the /doctor command within the CLI to inspect which configuration files loaded and their precedence order.

Optimizing Performance and Reliability with Kimi K2.5

Kimi K2.5 supports a 256,000-token context window, matching Claude's capabilities for large codebase analysis. Network latency between your location and Moonshot's servers may differ from Anthropic's infrastructure.

To minimize latency:

Use the geographic endpoint closest to your location (api.moonshot.ai for global, api.moonshot.cn for China)
Enable CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC to prevent background model calls from consuming bandwidth
Configure appropriate timeout values — Kimi K2.5's reasoning capabilities sometimes require longer processing for complex architectural tasks

Additionally, Kimi K2.5 offers a "thinking mode" you can control through the same interface. Claude Code doesn't natively expose thinking budget controls for third-party models, but you can adjust the MAX_THINKING_TOKENS environment variable if Moonshot's compatibility layer supports extended reasoning parameters.

For teams managing multiple projects, script the configuration. Create a shell alias that sets these variables on demand:

alias claude-kimi='export ANTHROPIC_BASE_URL="https://api.moonshot.ai/anthropic" && export ANTHROPIC_MODEL="kimi-k2.5" && claude'

This lets you switch between Anthropic and Moonshot backends by choosing different aliases or launch scripts depending on project requirements.

Conclusion

Integrating Kimi K2.5 with Claude Code demonstrates the power of API compatibility standards — swap the underlying model while preserving superior tooling. By routing Claude Code's Anthropic-compatible requests through Moonshot's infrastructure, you gain Kimi K2.5's advanced reasoning capabilities without sacrificing Claude Code's agentic workflow, repository management, or terminal integration.

When working with APIs — whether testing Moonshot's endpoints, debugging Claude Code configurations, or building integrations — streamline your development workflow with Apidog. It provides visual API testing, automatic documentation generation, and collaborative debugging tools that eliminate boilerplate code. Download Apidog today to accelerate your API development and testing processes.

DEV Community