将 OpenClaw 路由到 LiteLLM Proxy 后，可实现 100+ 模型统一 API 访问、费用追踪和自动故障转移。支持 onboarding 一键设置（推荐）或手动配置 LITELLM_API_KEY 和 baseUrl；还可为 OpenClaw 创建带月消费上限的虚拟 Key。注意：LiteLLM 默认运行在 localhost:4000，远程代理需启用 allowPrivateNetwork；OpenAI 原生 payload 特性（如 prompt-cache 提示）不会透传。

LiteLLM 接入 OpenClaw 配置指南

LiteLLM 是一个开源 LLM 网关，为 100+ 模型提供商提供统一 API。将 OpenClaw 路由到 LiteLLM，可以获得集中费用追踪、请求日志，以及在 Claude、GPT-4、Gemini、Bedrock 之间切换后端而不用改 OpenClaw 配置的能力。

为什么在 OpenClaw 中使用 LiteLLM？

• 费用追踪 — 精确查看 OpenClaw 在各模型上的花费
• 模型路由 — 更换模型提供商无需修改 OpenClaw 配置
• 虚拟 Key — 为 OpenClaw 创建带消费上限的专用 Key
• 请求日志 — 完整请求/响应日志，方便调试
• 自动故障转移 — 主提供商不可用时自动切换备用

快速开始

方式一：通过 onboarding（推荐）

最快到达可用状态，适合首次配置。

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

如果连接远程 LiteLLM Proxy，需要显式传入代理 URL（非交互模式）：

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

方式二：手动配置

适合需要完全控制安装和配置的情况。

1. 启动 LiteLLM Proxy

   pip install 'litellm[proxy]'
   litellm --model claude-opus-4-6

2. 让 OpenClaw 指向 LiteLLM

   export LITELLM_API_KEY="your-litellm-key"
   openclaw

   完成，OpenClaw 现在所有请求都通过 LiteLLM 路由。

配置

环境变量

export LITELLM_API_KEY="sk-litellm-key"

配置文件（openclaw.yml 或 JSON）

{
  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-4o",
            name: "GPT-4o",
            reasoning: false,
            input: ["text", "image"],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "litellm/claude-opus-4-6" },
    },
  },
}

高级配置

图片生成代理

LiteLLM 也可以为 OpenClaw 的 image_generate 工具提供 OpenAI 兼容的 /images/generations 和 /images/edits 路由。在 agents.defaults.imageGenerationModel 中配置 LiteLLM 图片模型：

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

如果 LiteLLM 运行在 localhost:4000，不需要额外配置。如果代理在局域网另外一台机器上，需要设置 models.providers.litellm.request.allowPrivateNetwork: true，因为 API Key 会发送到该代理机器。

虚拟 Key

为 OpenClaw 创建专用 Key 并设置消费上限：

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"
  }'

将生成的 Key 设为环境变量 LITELLM_API_KEY。

模型路由

在 LiteLLM 的 config.yaml 中配置后端映射，OpenClaw 始终请求同一个模型 ID（如 claude-opus-4-6），LiteLLM 负责路由到不同后端：

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-4o
    litellm_params:
      model: gpt-4o
      api_key: os.environ/OPENAI_API_KEY

查看用量

通过 LiteLLM 仪表板或 API：

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

# 消费日志
curl "http://localhost:4000/spend/logs" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

代理行为说明

• LiteLLM 默认运行在 http://localhost:4000。
• OpenClaw 通过 LiteLLM 的 OpenAI 兼容 /v1 端点连接。
• OpenAI 原生请求形塑（如 service_tier、Responses store、prompt-cache 提示、OpenAI 推理兼容 payload）不会透传。
• 当使用自定义 LiteLLM base URL 时，OpenClaw 不会添加隐藏归属头（originator、version、User-Agent）。

INFO

关于一般提供商配置和故障转移行为，参见 模型提供商。

相关参考

• LiteLLM 官方文档 — API 参考与详细配置。
• 模型选择 — 所有提供商、模型引用及故障转移行为概览。
• 完整配置参考 — 所有配置项说明。
• 模型选择指南 — 如何选择和配置模型。

常见问题

LiteLLM 虚拟 Key 不生效或报错怎么办？

确认 LITELLM_API_KEY 环境变量正确指向通过 /key/generate 创建的 key。同时检查 LITELLM_MASTER_KEY 是否有权限创建和管理 key。虚拟 Key 的消费限制在 max_budget 和 budget_duration 中定义，如果超出限制 LiteLLM 会拒绝请求。

图片生成工具怎么配置 LiteLLM？

需在 agents.defaults.imageGenerationModel 中指定一个 LiteLLM 支持的图片生成模型（如 litellm/gpt-image-2），并确保该模型已在 LiteLLM 代理后端可用。另外 timeoutMs 建议设为 180000（3分钟），因为图片生成通常较慢。

LiteLLM 代理在局域网时，allowPrivateNetwork 什么时候必须设成 true？

当 LiteLLM 代理部署在非 localhost 的私有网络地址（如 192.168.1.100:4000）时，OpenClaw 默认不会将 API Key 发送到私有 IP 主机。需要在 models.providers.litellm.request 中设置 allowPrivateNetwork: true 来放行。