User Guide: Providers

This guide explains provider configuration using the current cliproxyapi++ config schema.

Core Model

• Client sends requests to OpenAI-compatible endpoints (/v1/*).
• cliproxyapi++ resolves model -> provider/credential based on prefix + aliases.
• Provider blocks in config.yaml define auth, base URL, and model exposure.

Current Provider Configuration Patterns

Direct provider key

claude-api-key:
  - api-key: "sk-ant-..."
    prefix: "claude-prod"

Aggregator provider

openrouter:
  - api-key: "sk-or-v1-..."
    base-url: "https://openrouter.ai/api/v1"
    prefix: "or"

OpenAI-compatible provider registry

openai-compatibility:
  - name: "openrouter"
    prefix: "or"
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: "sk-or-v1-..."

OAuth/session provider

kiro:
  - token-file: "~/.aws/sso/cache/kiro-auth-token.json"

Operational Best Practices

• Use force-model-prefix: true to enforce explicit routing boundaries.
• Keep at least one fallback provider for each critical workload.
• Use models + alias to keep client model names stable.
• Use excluded-models to hide risky/high-cost models from consumers.

Validation Commands

curl -sS http://localhost:8317/v1/models \
  -H "Authorization: Bearer <api-key>" | jq '.data[:10]'

curl -sS http://localhost:8317/v1/metrics/providers | jq

Deep Dives

• Provider Usage
• Provider Catalog
• Provider Operations
• Routing and Models Reference