LiteLLM

LiteLLM 是一个开源 LLM 网关，提供统一 API 以连接 100 多个模型提供商。通过 LiteLLM 路由 OpenClaw，可在不更改 OpenClaw 配置的情况下实现集中式成本跟踪、日志记录、带消费限额的虚拟密钥以及后端故障转移。

快速开始¶

入门（推荐）手动设置

openclaw onboard --auth-choice litellm-api-key

对于针对远程代理的非交互式设置，请显式传入代理 URL：

openclaw onboard --non-interactive --accept-risk --skip-health --auth-choice litellm-api-key \
  --litellm-api-key "$LITELLM_API_KEY" --custom-base-url "https://litellm.example/v1"

1. 启动 LiteLLM 代理

LiteLLM 会代表你调用上游提供商，因此在启动之前请导出该提供商的密钥——下方模型使用 ANTHROPIC_API_KEY。有关多后端设置，请参阅模型路由。

pip install 'litellm[proxy]'
export ANTHROPIC_API_KEY=sk-ant-...
litellm --model claude-opus-4-6

2. 将 OpenClaw 指向 LiteLLM

export LITELLM_API_KEY="your-litellm-key"
openclaw

配置¶

{
  models: {
    providers: {
      litellm: {
        baseUrl: "http://localhost:4000",
        apiKey: "${LITELLM_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "claude-opus-4-6",
            name: "Claude Opus 4.6",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 200000,
            maxTokens: 64000,
          },
          {
            id: "gpt-6-astra",
            name: "GPT-6 Astra",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1050000,
            maxTokens: 128000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "litellm/claude-opus-4-6" },
    },
  },
}

入门写入的默认模型是 litellm/claude-opus-4-6。

在合并模式下，使用显式代理 URL 进行入门会保留任何已编写的提供商模型，否则将提供商模型列表留空以便发现。运行 openclaw models list --provider litellm --refresh --json 以列出代理的模型。对于 models.mode: "replace"，发现功能被禁用，因此入门会在提供商模型列表中保留文档中的默认值，同时保留现有模型定义。

图像生成¶

LiteLLM 可以通过 OpenAI 兼容的 /images/generations 和 /images/edits 路由为 image_generate 工具提供支持。默认图像模型是 gpt-image-2；可在 agents.defaults.mediaModels.image 下配置其他模型：

{
  models: {
    providers: {
      litellm: {
        baseUrl: "http://localhost:4000",
        apiKey: "${LITELLM_API_KEY}",
      },
    },
  },
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "litellm/gpt-image-2",
          timeoutMs: 180000,
        },
      },
    },
  },
}

回环 LiteLLM URL（http://localhost:4000、127.0.0.1、::1、host.docker.internal）无需全局私有网络覆盖即可工作。对于托管在局域网中的代理，请设置 models.providers.litellm.request.allowPrivateNetwork: true，因为 API 密钥会发送到该主机。

高级¶

虚拟密钥

为 OpenClaw 创建一个带消费限额的专用密钥：

curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key_alias": "openclaw",
    "max_budget": 50.00,
    "budget_duration": "monthly"
  }'

将生成的密钥用作 LITELLM_API_KEY。

模型路由

LiteLLM 可以将模型请求路由到不同后端。在你的 LiteLLM config.yaml 中配置：

model_list:
  - model_name: claude-opus-4-6
    litellm_params:
      model: claude-opus-4-6
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: gpt-6-astra
    litellm_params:
      model: gpt-6-astra
      api_key: os.environ/OPENAI_API_KEY

OpenClaw 继续请求 claude-opus-4-6；LiteLLM 负责路由。

查看使用情况

# Key info
curl "http://localhost:4000/key/info" \
  -H "Authorization: Bearer sk-litellm-key"

# Spend logs
curl "http://localhost:4000/spend/logs" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

代理行为说明

LiteLLM 默认运行在 http://localhost:4000。
OpenClaw 通过 LiteLLM 的代理式 OpenAI 兼容 /v1 端点连接。
仅适用于原生 OpenAI 的请求塑形不会通过已配置的 LiteLLM 基础 URL 应用：没有 service_tier、没有 Responses store、没有提示缓存提示、没有 OpenAI 推理努力负载塑形。
隐藏的 OpenClaw 归属头（originator、version、User-Agent）只会发送到经过验证的原生 OpenAI 端点，因此不会在自定义 LiteLLM 基础 URL 上注入。