# Custom Model Switching Fix — 2026-03-02

## The Problem

Changing an agent's primary model to a non-built-in model (MiniMax M2.5, Kimi K2.5, etc.) crashes Clawdbot or returns auth errors. This has been broken for ~1 month.

**Two bugs found:**

### Bug 1: `model.api` undefined → crash
`buildInlineProviderModels()` in Clawdbot's model resolution code spreads model properties from the provider config but does NOT inherit the `api` field from the parent provider. So when the streaming layer calls `mapOptionsForApi(model, ...)`, `model.api` is `undefined` and it throws:
```
Error: Unhandled API in mapOptionsForApi: undefined
```
This crashes the entire agent process, triggering a restart loop.

**Location:** `/usr/lib/node_modules/clawdbot/dist/agents/pi-embedded-runner/model.js`
```js
// Bug: only spreads model fields, doesn't copy provider.api
return (entry?.models ?? []).map((model) => ({ ...model, provider: trimmed }));
// Should be: ({ ...model, provider: trimmed, api: entry.api })
```

**Fix:** Add `"api": "<type>"` directly on each model definition in the provider config, not just the provider level.

### Bug 2: Anthropic SDK headers rejected by MiniMax
MiniMax offers an Anthropic-compatible endpoint (`api.minimax.io/anthropic`), but Clawdbot's Anthropic SDK sends extra headers that MiniMax rejects:
- `anthropic-beta: fine-grained-tool-streaming-2025-05-14, interleaved-thinking-2025-05-14`
- `anthropic-dangerous-direct-browser-access: true`
- OAuth stealth headers mimicking Claude Code

Result: `HTTP 401 authentication_error: invalid x-api-key` — even though the key is valid (confirmed via curl).

**Fix:** Use `openai-completions` API type instead of `anthropic-messages`. Route through `api.minimax.io/v1` (OpenAI-compatible endpoint).

### Bug 3: Auth profile cooldown cascade
After the first 401, Clawdbot puts the auth profile into cooldown. Even after restarting the service, if a heartbeat fires before your test message and hits the same error, the cooldown re-triggers. All subsequent requests fail with:
```
FailoverError: No available auth profile for minimax (all in cooldown or unavailable)
```

**Fix:** Set heartbeat model separately (e.g., `anthropic/claude-sonnet-4-20250514`) so heartbeats don't burn the custom provider's auth profile.

## The Solution (Working Config)

Per-agent config at `/root/.clawdbot-<agent>/clawdbot.json`:

```json
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "minimax/MiniMax-M2.5",
        "fallbacks": ["anthropic/claude-sonnet-4-20250514"]
      },
      "heartbeat": {
        "every": "30m",
        "model": "anthropic/claude-sonnet-4-20250514",
        "includeReasoning": false
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimax.io/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "MiniMax-M2.5",
            "name": "MiniMax M2.5",
            "api": "openai-completions",
            "reasoning": false,
            "input": ["text"],
            "cost": {"input": 15, "output": 60, "cacheRead": 2, "cacheWrite": 10},
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
```

**Key rules:**
1. `api` field MUST be on each model definition (not just the provider)
2. Use `openai-completions` for MiniMax (not `anthropic-messages`)
3. Use `api.minimax.io/v1` endpoint (not `/anthropic`)
4. Set heartbeat model separately to avoid burning custom provider cooldowns
5. Auth profiles handle API keys — don't put `apiKey` on the provider
6. Clear auth cooldowns after failed attempts: edit `agents/main/agent/auth-profiles.json`, set `usageStats: {}`

## How to Apply to Other Agents

Each agent has its own config: `/root/.clawdbot-<name>/clawdbot.json`

Same pattern works for any OpenAI-compatible provider:
- **Kimi K2.5:** `baseUrl: https://api.moonshot.ai/v1`, `api: openai-completions`
- **DeepSeek:** `baseUrl: https://api.deepseek.com/v1`, `api: openai-completions`

## Status
- **Cog:** Running MiniMax M2.5 ✅ (confirmed responding)
- **Other agents:** Still on Opus 4.6 (pending rollout)
- **Clawdbot bug:** Should be reported on GitHub (model.api inheritance)