| name | litellm |
| description | LiteLLM proxy configuration, model routing, virtual keys, and admin UI. Use when working with LiteLLM config files, adding or removing models, troubleshooting routing errors, managing virtual keys, configuring callbacks, or diagnosing proxy issues. Covers both general LiteLLM knowledge and admin operations. |
| allowed-tools | Read, Bash, Edit, Grep, Glob |
LiteLLM
Quick Reference
Read references/config-guide.md for config file format, model routing, and provider setup.
Read references/admin-operations.md for admin UI, virtual keys, and operational tasks.
When Invoked
If $ARGUMENTS mentions a specific topic, read the relevant reference file and answer directly.
If no arguments, summarize available operations and ask what the user needs help with.
Key Concepts
- Model list: Maps friendly
model_name aliases to provider-specific litellm_params.model IDs
- Virtual keys: Scoped API keys created in the admin UI for per-app access control and spend tracking
- Callbacks: Plugins for logging, metrics, and tracing (prometheus, otel, etc.)
forward_client_headers_to_llm_api: Forwards client auth headers to the upstream provider — required for Claude Max subscription OAuth passthroughSTORE_MODEL_IN_DB: Persists runtime model changes to Postgres so they survive restarts
Common Troubleshooting
| Symptom | Likely Cause |
|---|
| "Not connected to DB!" on login | No DATABASE_URL configured; LiteLLM needs Postgres for the admin UI |
| "Invalid model name passed in model=X" | The alias the client sent isn't in this key's model list. GET <gateway>/v1/models with the key as Authorization: Bearer lists the exact aliases available; match model_name to one of those |
| Config changes not taking effect | Container wasn't restarted after config file update on disk |
| Auth error with Max subscription | Missing forward_client_headers_to_llm_api: true in general_settings |
| OTEL export failures in logs | OTEL_EXPORTER_OTLP_ENDPOINT has a placeholder IP instead of a real address |
