kimi-integration

# Kimi Model Integration

Complete guide for adding Moonshot AI (Kimi) and Kimi Code models to Clawdbot.

## Overview

Kimi offers two separate model families:

1. **Moonshot AI (Kimi K2)** - General-purpose models via OpenAI-compatible API
2. **Kimi Code** - Specialized coding model with dedicated endpoint

Both require API keys from different sources.

## Prerequisites

- Clawdbot installed and configured
- API keys (see Getting API Keys section)

## Getting API Keys

### Moonshot AI (Kimi K2)

1. Visit https://platform.moonshot.cn
2. Register an account
3. Navigate to API Keys section
4. Create a new API key
5. Copy the key (starts with `sk-...`)

### Kimi Code

1. Visit https://api.kimi.com/coding
2. Register an account  
3. Navigate to API Keys section
4. Create a new API key
5. Copy the key (starts with `sk-...`)

**Note:** Moonshot and Kimi Code use separate keys and endpoints.

## Integration Steps

### Option 1: Moonshot AI (Kimi K2 models)

#### Step 1: Set environment variable

```bash
export MOONSHOT_API_KEY="sk-your-moonshot-key-here"
```

Or add to `.env` file:

```bash
echo 'MOONSHOT_API_KEY="sk-your-moonshot-key-here"' >> ~/.env
```

#### Step 2: Add provider configuration

Edit your `clawdbot.json` config:

```json5
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.5"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "apiKey": "${MOONSHOT_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "moonlight-v1-32k",
            "name": "Moonlight V1 32K",
            "contextWindow": 32768
          },
          {
            "id": "moonshot-v1-8k",
            "name": "Moonshot V1 8K",
            "contextWindow": 8192
          },
          {
            "id": "moonshot-v1-32k",
            "name": "Moonshot V1 32K",
            "contextWindow": 32768
          },
          {
            "id": "moonshot-v1-128k",
            "name": "Moonshot V1 128K",
            "contextWindow": 131072
          },
          {
            "id": "kimi-k2.5",
            "name": "Kimi K2.5",
            "contextWindow": 200000
          }
        ]
      }
    }
  }
}
```

#### Step 3: Restart Clawdbot

```bash
clawdbot gateway restart
```

#### Step 4: Verify integration

```bash
clawdbot models list
```

You should see Moonshot models in the list.

#### Step 5: Use the model

Set as default:
```bash
clawdbot models set moonshot/kimi-k2.5
```

Or use model aliases in chat:
```bash
/model moonshot/kimi-k2.5
```

### Option 2: Kimi Code (specialized coding model)

#### Step 1: Set environment variable

```bash
export KIMICODE_API_KEY="sk-your-kimicode-key-here"
```

Or add to `.env`:

```bash
echo 'KIMICODE_API_KEY="sk-your-kimicode-key-here"' >> ~/.env
```

#### Step 2: Add provider configuration

Edit your `clawdbot.json` config:

```json5
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "kimicode/kimi-for-coding"
      },
      "models": {
        "kimicode/kimi-for-coding": {
          "alias": "kimi"
        }
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "kimicode": {
        "baseUrl": "https://api.kimi.com/coding/v1",
        "apiKey": "${KIMICODE_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "kimi-for-coding",
            "name": "Kimi For Coding",
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
```

#### Step 3: Restart Clawdbot

```bash
clawdbot gateway restart
```

#### Step 4: Verify integration

```bash
clawdbot models list
```

You should see `kimicode/kimi-for-coding` in the list.

#### Step 5: Use the model

Set as default:
```bash
clawdbot models set kimicode/kimi-for-coding
```

Or use model alias in chat:
```bash
/model kimi
```

## Using Both Providers

You can configure both Moonshot and Kimi Code simultaneously:

```json5
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.5"
      },
      "models": {
        "kimicode/kimi-for-coding": {
          "alias": "kimi"
        },
        "moonshot/kimi-k2.5": {
          "alias": "k25"
        }
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "moonshot": {
        "baseUrl": "https://api.moonshot.cn/v1",
        "apiKey": "${MOONSHOT_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "kimi-k2.5", "name": "Kimi K2.5", "contextWindow": 200000 }
        ]
      },
      "kimicode": {
        "baseUrl": "https://api.kimi.com/coding/v1",
        "apiKey": "${KIMICODE_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "kimi-for-coding", "name": "Kimi For Coding", "contextWindow": 200000 }
        ]
      }
    }
  }
}
```

Switch between models using aliases:
- `/model k25` - Kimi K2.5 (general)
- `/model kimi` - Kimi for Coding (specialized)

## Troubleshooting

### Model not appearing in list

Check config syntax:
```bash
clawdbot gateway config.get | grep -A 20 moonshot
```

Verify API key is set:
```bash
echo $MOONSHOT_API_KEY
echo $KIMICODE_API_KEY
```

### Authentication errors

- Verify API key starts with `sk-`
- Check key is valid on provider dashboard
- Ensure correct base URL for each provider

### Connection issues

Test API endpoint directly:
```bash
curl -X POST "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "kimi-k2.5", "messages": [{"role": "user", "content": "test"}]}'
```

## Model Recommendations

- **Kimi K2.5** (`moonshot/kimi-k2.5`) - Best for general tasks, 200K context
- **Kimi for Coding** (`kimicode/kimi-for-coding`) - Specialized for code generation
- **Moonshot V1 128K** (`moonshot/moonshot-v1-128k`) - Legacy model, 128K context

## References

- Moonshot AI Docs: https://platform.moonshot.cn/docs
- Kimi Code API: https://api.kimi.com/coding/docs
- Clawdbot Model Providers: /home/eyurc/clawdbot/docs/concepts/model-providers.md