147 lines
4.0 KiB
Markdown
147 lines
4.0 KiB
Markdown
---
|
|
summary: "Proposal: model config, auth profiles, and fallback behavior"
|
|
read_when:
|
|
- Designing model selection, auth profiles, or fallback behavior
|
|
- Migrating model config schema
|
|
---
|
|
|
|
# Model config proposal
|
|
|
|
Goals
|
|
- Multi OAuth + multi API key per provider
|
|
- Model selection via `/model` with sensible fallback
|
|
- Global (not per-session) fallback logic
|
|
- Keep last-known-good auth profile when switching models
|
|
- Profile override only when explicitly requested
|
|
- Image routing override only when explicitly configured
|
|
|
|
Non-goals (v1)
|
|
- Auto-discovery of provider capabilities beyond catalog input tags
|
|
- Per-model auth profile order (see open questions)
|
|
|
|
## Proposed config shape
|
|
|
|
```json
|
|
{
|
|
"auth": {
|
|
"profiles": {
|
|
"anthropic:default": {
|
|
"provider": "anthropic",
|
|
"mode": "oauth"
|
|
},
|
|
"anthropic:work": {
|
|
"provider": "anthropic",
|
|
"mode": "api_key"
|
|
},
|
|
"openai:default": {
|
|
"provider": "openai",
|
|
"mode": "oauth"
|
|
}
|
|
},
|
|
"order": {
|
|
"anthropic": ["anthropic:default", "anthropic:work"],
|
|
"openai": ["openai:default"]
|
|
}
|
|
},
|
|
"agent": {
|
|
"models": {
|
|
"anthropic/claude-opus-4-5": {
|
|
"alias": "Opus"
|
|
},
|
|
"openai/gpt-5.2": {
|
|
"alias": "gpt52"
|
|
}
|
|
},
|
|
"model": {
|
|
"primary": "anthropic/claude-opus-4-5",
|
|
"fallbacks": ["openai/gpt-5.2"]
|
|
},
|
|
"imageModel": {
|
|
"primary": "openai/gpt-5.2",
|
|
"fallbacks": ["anthropic/claude-opus-4-5"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Notes
|
|
- Canonical model keys are full `provider/model`.
|
|
- `alias` optional; used by `/model` resolution.
|
|
- `auth.profiles` is keyed. Default CLI login creates `provider:default`.
|
|
- `auth.order[provider]` controls rotation order for that provider.
|
|
|
|
## CLI / UX
|
|
|
|
Login
|
|
- `clawdbot login anthropic` → create/replace `anthropic:default`.
|
|
- `clawdbot login anthropic --profile work` → create/replace `anthropic:work`.
|
|
|
|
Model selection
|
|
- `/model Opus` → resolve alias to full id.
|
|
- `/model anthropic/claude-opus-4-5` → explicit.
|
|
- Optional: `/model Opus@anthropic:work` (explicit profile override for session only).
|
|
|
|
Model listing
|
|
- `/model` list shows:
|
|
- model id
|
|
- alias
|
|
- provider
|
|
- auth order (from `auth.order`)
|
|
- auth source for the current provider (env/auth.json/models.json)
|
|
|
|
## Fallback behavior (global)
|
|
|
|
Fallback list
|
|
- Use `agent.model.fallbacks` globally.
|
|
- No per-session fallback list; last-known-good is per-session but uses global ordering.
|
|
|
|
Auth profile rotation
|
|
- If provider auth error (401/403/invalid refresh):
|
|
- advance to next profile in `auth.order[provider]`.
|
|
- if all fail, fall back to next model.
|
|
|
|
Rate limiting
|
|
- If rate limit / quota error:
|
|
- rotate auth profile first (same provider)
|
|
- if still failing, fall back to next model.
|
|
|
|
Model not found / capability mismatch
|
|
- immediate model fallback.
|
|
|
|
## Image routing
|
|
|
|
Rule
|
|
- Only use `agent.imageModel` when explicitly configured.
|
|
- If `agent.imageModel` is configured and the current text model lacks image input, use it.
|
|
|
|
Support detection
|
|
- From model catalog `input` tags when available (e.g. `image` in models.json).
|
|
- If unknown: treat as text-only and use `agent.imageModel`.
|
|
|
|
## Migration (doctor + gateway auto-run)
|
|
|
|
Inputs
|
|
- `agent.model` (string)
|
|
- `agent.modelFallbacks` (string[])
|
|
- `agent.imageModel` (string)
|
|
- `agent.imageModelFallbacks` (string[])
|
|
- `agent.allowedModels` (string[])
|
|
- `agent.modelAliases` (record)
|
|
|
|
Outputs
|
|
- `agent.models` map with keys for all referenced models
|
|
- `agent.model.primary/fallbacks`
|
|
- `agent.imageModel.primary/fallbacks`
|
|
- `auth.profiles` seeded from current auth.json + env (as `provider:default`)
|
|
- `auth.order` seeded with `["provider:default"]`
|
|
|
|
Auto-run
|
|
- Gateway start detects legacy keys and runs doctor migration.
|
|
|
|
## Decisions
|
|
|
|
- Auth order is per-provider (`auth.order`).
|
|
- Doctor migration is required; gateway will auto-run on startup when legacy keys detected.
|
|
- `/model Opus@profile` is explicit session override only.
|
|
- Image routing override only when `agent.imageModel` is explicitly configured.
|