OpenClaw 自定义模型添加完整指南：从云端 API 到本地部署（2026）

OpenClaw 内置了对 OpenAI、Anthropic、Google Gemini 和 OpenRouter 等十四家提供商的开箱即用支持，但真正的强大之处在于你可以自行添加新的提供商。无论你需要接入公司防火墙内的私有 vLLM 部署、通过 LiteLLM 实现跨多家 AI 供应商的统一计费，还是在官方版本正式支持之前就接入全新的提供商（比如 Moonshot AI 的 Kimi K2.5），openclaw.json 文件中的 models.providers 配置都能通过几行 JSON 轻松实现。本指南将逐一讲解每个配置参数的含义，演示五种不同类型提供商（从云端 API 到本地推理服务器）经过测试验证的完整配置示例，并涵盖其他任何单一资源都未能汇总的常见错误排查步骤。读完本文后，你将完全掌握如何为 OpenClaw 添加任何 OpenAI 兼容或 Anthropic 兼容模型、配置多模型路由以优化成本，以及在问题出现时进行调试。

OpenClaw 中的自定义模型提供商是什么？

OpenClaw 的模型系统将提供商分为两类。内置提供商属于每次安装都会附带的 pi-ai 目录的一部分，包括 OpenAI、Anthropic、Google Gemini、Google Vertex、OpenCode Zen、Z.AI（GLM）、Vercel AI Gateway、OpenRouter、xAI、Groq、Cerebras、Mistral 和 GitHub Copilot。对于这些提供商，你只需设置身份验证凭据并选择模型即可，无需额外配置。一条简单的命令如 openclaw onboard --auth-choice openai-api-key 就能完成整个设置。

自定义模型提供商则是内置目录之外的所有内容，需要通过 openclaw.json 文件中的 models.providers 部分进行显式配置。这包括 Moonshot AI（Kimi）、MiniMax 和阿里云模型工作室等云端 API 服务；也包括 Ollama、vLLM、LM Studio 和 text-generation-webui 等本地推理运行时；LiteLLM 这类将多个提供商聚合到单一端点的代理和网关服务同样属于此类；暴露 OpenAI 兼容或 Anthropic 兼容端点的企业级部署也是如此。

判断是否需要自定义提供商非常简单。如果你的目标提供商出现在上述内置列表中，直接使用内置配置路径即可——不需要 models.providers 条目，只需设置身份验证和选择模型。如果你的提供商暴露的是 OpenAI 兼容的 chat completions API，就用 api: "openai-completions" 将其配置为自定义提供商。如果使用的是 Anthropic 兼容的 messages API，则用 api: "anthropic-messages"。如果你的提供商原生不使用这两种格式，可以通过 OpenRouter 或 LiteLLM 作为中间层进行路由，它们会自动完成请求格式的转换。如需深入了解初始提供商设置（包括 Ollama 和云端提供商），请参阅我们的 OpenClaw LLM 设置完整指南。

自定义提供商的实际用途远不止于添加新模型。团队经常使用自定义配置来接入内部 API 网关，以便在组织范围内执行统一的速率限制和审计日志。初创公司利用它们通过成本优化的代理服务将多家 AI 提供商的计费整合到一张发票中。注重隐私的开发者则配置本地推理端点，确保数据完全不出网。先行者们还利用自定义提供商在新版本正式支持之前就能访问最新发布的模型——例如 Moonshot AI 的 Kimi K2.5 或 MiniMax M2.1。models.providers 配置正是让 OpenClaw 真正实现模型无关性（而非锁定在固定支持服务集合中）的关键机制。

OpenClaw 的模型系统运作原理

理解三个核心概念将在配置自定义提供商时为你节省大量调试时间。第一个概念是模型引用格式。OpenClaw 中的每个模型都使用 provider/model-id 的模式，系统在第一个斜杠处分割以区分提供商名称和模型标识符。当你在聊天会话中输入 /model moonshot/kimi-k2.5 时，OpenClaw 会将请求路由到 "moonshot" 提供商并请求 "kimi-k2.5" 模型。对于 ID 中包含额外斜杠的模型（例如 OpenRouter 风格的标识符如 openrouter/anthropic/claude-sonnet-4-5），分割仍然发生在第一个斜杠处——"openrouter" 成为提供商，"anthropic/claude-sonnet-4-5" 成为模型 ID。

第二个概念是模型选择优先级。OpenClaw 通过特定的级联方式来确定使用哪个模型。它首先从 agents.defaults.model.primary 中定义的主模型开始。如果该模型因身份验证失败或速率限制而不可用，就会按照 agents.defaults.model.fallbacks 中的有序回退列表依次尝试。如果主模型无法接受图像但当前任务需要视觉能力，OpenClaw 会自动切换到 agents.defaults.imageModel.primary 中定义的图像模型。这种级联意味着你可以为大多数任务配置一个经济实惠的主模型，同时保留一个高端模型作为复杂推理的后备。

第三个概念是模型白名单。当你在 openclaw.json 中配置了 agents.defaults.models 时，它就变成了一个严格的白名单。任何未列出的模型都会被拒绝，并报错 "Model 'provider/model' is not allowed"。这种行为在企业环境中是有意设计的，管理员可以借此控制用户能访问哪些模型。如果在添加自定义提供商后遇到此错误，需要将新模型添加到这个白名单中。或者，完全移除 agents.defaults.models 键即可禁用白名单限制，允许使用任何已配置的模型。openclaw models status 命令会显示已解析的主模型、回退模型、图像模型和身份验证概况，是诊断配置问题的最佳起点。

CLI 提供了一套完整的命令集，用于在运行时管理模型而无需手动编辑配置文件。openclaw models list 命令显示所有已配置的模型，--all 标志会显示完整目录，--provider <name> 则按特定提供商进行过滤。openclaw models set <provider/model> 命令可立即更改主模型，而 openclaw models set-image <provider/model> 则配置在需要视觉输入时使用的图像模型。通过 openclaw models aliases list|add|remove 进行别名管理，你可以创建诸如 "opus" 或 "kimi" 之类的快捷方式来映射到完整的提供商/模型引用，减少日常操作中的输入量。通过 openclaw models fallbacks list|add|remove|clear 和 openclaw models image-fallbacks list|add|remove|clear 进行回退管理，让你对故障转移链拥有完全控制权。对于自定义提供商调试而言，openclaw models scan 命令尤其有用，它可以检查可用模型，并通过可选的实时探测来测试工具调用支持和图像处理能力。

完整的 models.providers 配置参考

openclaw.json 中的 models.providers 部分是所有自定义提供商定义的所在位置。配置遵循特定的结构，包含必填和可选参数。理解每个参数的含义可以避免最常见的配置错误。

顶层结构将提供商定义包裹在 models.providers 内，还有一个可选的 mode 字段控制自定义提供商与内置目录的交互方式。设置 mode: "merge" 会将你的自定义提供商与内置提供商合并，这是大多数用户的推荐做法。如果不设置此字段，自定义提供商会完全替换内置目录——这很少是你想要的结果。

每个提供商定义需要三个必填参数。baseUrl 参数指定 OpenClaw 发送请求的 API 端点，例如 Moonshot AI 使用 https://api.moonshot.ai/v1，本 地 LM Studio 实例则使用 http://localhost:1234/v1。apiKey 参数处理身份验证，支持使用 ${VAR_NAME} 语法引用环境变量，因此 "${MOONSHOT_API_KEY}" 会让 OpenClaw 从 MOONSHOT_API_KEY 环境变量中读取密钥，而不是在配置中以明文形式存储凭据。api 参数声明协议兼容性，接受 "openai-completions"（用于 OpenAI 兼容端点）或 "anthropic-messages"（用于 Anthropic 兼容端点）。

每个提供商内的 models 数组定义了可用的模型。每个模型条目只需要 id 和 name，但可选字段可以声明 OpenClaw 用于路由决策的能力。reasoning 字段（布尔值，默认为 false）表示模型是否支持思维链推理。input 字段（数组，默认为 ["text"]）声明接受的输入类型——为视觉模型添加 "image"。cost 对象包含 input、output、cacheRead 和 cacheWrite 字段（均默认为 0），当你设置准确的每 token 价格时，可以启用成本跟踪和优化。contextWindow 字段（默认为 200000）设置最大上下文长度（以 token 计），maxTokens（默认为 8192）控制最大输出长度。虽然这些可选字段有合理的默认值，但设置与你模型实际能力匹配的显式值可以避免上下文截断或成本计算错误等微妙问题。

以下是带有所有参数注释的完整配置结构：

json5
{
  models: {
    mode: "merge",
    providers: {
      "provider-name": {
        baseUrl: "https://api.example.com/v1",
        apiKey: "${API_KEY_ENV_VAR}",
        api: "openai-completions",
        models: [
          {
            id: "model-id",
            name: "Display Name",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

选择正确的 api 类型至关重要，完全取决于你的提供商端点格式。对于任何接受 OpenAI chat completions 请求格式的提供商，使用 "openai-completions"——这涵盖了绝大多数第三方提供商，包括 Moonshot AI、vLLM、LM Studio、LiteLLM、Ollama、Groq 兼容端点以及大多数自托管推理服务器。专门针对实现了 Anthropic messages API 格式的提供商（目前包括 Kimi Coding 和 Synthetic），使用 "anthropic-messages"。如有疑问，请查看你的提供商文档，看他们是否将 API 描述为 "OpenAI 兼容" 或 "Anthropic 兼容"——如果使用 /v1/chat/completions 端点路径，就选 openai-completions。

以下快速参考表将常见提供商映射到正确的 API 类型，帮你避免最常见的配置错误：

配置云端和 API 提供商（分步指南）

本节提供五种不同云端和 API 提供商场景经过测试验证的完整配置。每个示例都包含完整的 openclaw.json 代码片段、所需的环境变量以及验证命令。

Moonshot AI(Kimi K2.5) 使用 OpenAI 兼容端点，提供开源生态中最强大的推理模型之一。Kimi K2.5 支持标准模式和思考模式，模型变体包括 kimi-k2.5、kimi-k2-thinking 和 kimi-k2-turbo-preview。来自 OpenClaw 官方文档（docs.openclaw.ai，2026 年 2 月）的配置如下：

json5
{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.5", name: "Kimi K2.5" }],
      },
    },
  },
}

保存配置后，在 shell 配置文件中导出你的 API 密钥 export MOONSHOT_API_KEY='sk-...'（macOS 追加到 ~/.zshrc，Linux 追加到 ~/.bash_profile），然后通过 source ~/.zshrc 使其生效。使用 openclaw models list --provider moonshot 验证设置以确认模型出现在可用列表中，并运行 openclaw models status --probe 执行实时连接测试，确认 API 密钥有效且模型正常响应。这两步验证可以在你实际使用模型之前，同时捕获配置错误（错误的提供商名称、缺失的模型条目）和身份验证错误（无效密钥、过期凭据）。

Synthetic(Anthropic 兼容) 通过 Anthropic 兼容的 API 端点提供 MiniMax M2.1 等模型的访问。这是使用 anthropic-messages API 类型的典型案例。配置结构相同但使用了不同的 API 协议：

json5
{
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.1", name: "MiniMax M2.1" }],
      },
    },
  },
}

阿里云模型工作室(通义千问) 需要选择区域端点，这会影响响应速度、可用模型和速率限制。有三个可用区域：新加坡（ap-southeast-1）、弗吉尼亚（us-east-1）和北京（cn-beijing），每个区域需要在模型工作室控制台获取单独的 API 密钥。对于海外用户，https://coding-intl.dashscope.aliyuncs.com/v1 提供的 OpenAI 兼容端点可实现中国以外地区的最低延迟。配置中包含了显式的成本和上下文窗口值以实现精确的成本跟踪：

json5
{
  models: {
    mode: "merge",
    providers: {
      dashscope: {
        baseUrl: "https://coding-intl.dashscope.aliyuncs.com/v1",
        apiKey: "${DASHSCOPE_API_KEY}",
        api: "openai-completions",
        models: [{
          id: "qwen3-max-2026-01-23",
          name: "Qwen3 Max",
          contextWindow: 262144,
          maxTokens: 32768,
        }],
      },
    },
  },
}

像 laozhang.ai 这样的 API 代理服务 提供统一端点，通过单个 API 密钥路由到多个上游提供商。这简化了计费流程，省去了为每个提供商单独管理凭据的麻烦。由于大多数代理服务实现了 OpenAI 兼容格式，配置遵循标准模式——只需将 baseUrl 替换为代理的端点并使用其统一 API 密钥即可。如果你正在比较不同提供商的模型成本，请参阅我们的 Claude Opus 4 与 Sonnet 4 详细对比指南，了解性能-成本的权衡关系。

通义千问 OAuth(免费层) 提供了一种无需 API 密钥的独特认证路径。通义千问通过内置插件提供设备码 OAuth 流程。只需两条命令即可启用并完成认证：

bash
openclaw plugins enable qwen-portal-auth
openclaw models auth login --provider qwen-portal --set-default

这将免费提供对 qwen-portal/coder-model 和 qwen-portal/vision-model 的访问，非常适合开发和测试工作流。基于 OAuth 的方式意味着无需管理或轮换 API 密钥，降低了个人开发者在无需承诺付费计划的情况下试用通义千问模型的安全开销。需要注意的是，免费层的使用限制适用于开发场景——生产工作负载应使用上文介绍的基于 API 密钥的 DashScope 配置，以获得更高的吞吐量和可用性保障。

连接本地模型（Ollama、vLLM、LM Studio、LiteLLM）

在本地运行模型可以消除 API 费用、将数据保留在本机，并完全避免速率限制问题。代价是硬件要求——本地推理需要足够的内存，最好还有 GPU。OpenClaw 支持四种主要的本地推理运行时，各有其独特优势以服务不同的工作流。

Ollama 是实现本地推理的最快途径，也是 OpenClaw 唯一会自动检测的运行时。当 Ollama 在 http://127.0.0.1:11434/v1 上运行时，OpenClaw 无需任何 models.providers 配置即可发现它。安装 Ollama，使用 ollama pull llama3.3 拉取模型，然后设置为主模型：

json5
{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

对于需要更长上下文或特定量化方式的模型，Ollama 的模型库提供了数十种选择。OpenClaw 编码任务推荐的模型包括 qwen3-coder（代码生成）和 glm-4.7（通用推理），两者都需要最低 64K token 的上下文窗口才能有效运行代理。在选择模型大小时，请仔细考虑任务复杂度。8B 参数模型在普通硬件上即可高效处理快速补全和简单查询，而 70B 模型虽然接近云端推理质量但需要显著更多的显存。Q4_K_M 量化格式在大多数本地部署中提供了质量保留和内存节省之间的最佳平衡——与全精度权重相比，它将显存需求降低约 60%，同时在编码基准测试中保留了原始模型 95% 以上的能力。

vLLM 面向吞吐量至关重要的生产部署。它通过连续批处理和 PagedAttention 实现了比 Hugging Face Transformers 快 24 倍的速度，非常适合每分钟产生数百个请求的多代理部署。默认端点为 http://localhost:8000/v1，使用标 准 OpenAI 兼容格式：

json5
{
  models: {
    mode: "merge",
    providers: {
      vllm: {
        baseUrl: "http://localhost:8000/v1",
        apiKey: "not-needed",
        api: "openai-completions",
        models: [{
          id: "meta-llama/Llama-3.1-70B-Instruct",
          name: "Llama 3.1 70B",
          contextWindow: 131072,
          maxTokens: 16384,
        }],
      },
    },
  },
}

Docker 部署有一个关键细节：当 vLLM 和 OpenClaw 运行在不同容器中时，需要将 localhost 替换为 host.docker.internal（Docker Desktop）或主机的局域网 IP 地址。--network=host 标志是另一种方案但可移植性较差。对于生产环境的 vLLM 部署，建议通过 --enable-chunked-prefill 启用分块预填充，并考虑将 --max-model-len 设置为与你的 OpenClaw 上下文需求匹配的值——vLLM 根据此值分配 GPU 内存，因此设置为 65536 而非模型最大值 131072 可以将显存需求减半，同时仍然满足 OpenClaw 的典型上下文需要。

LM Studio 提供桌面图形界面，用于下载、转换和提供模型服务。其可视化界面使其成为用户在确定配置之前实验不同模型的最佳选择。OpenClaw 官方文档（docs.openclaw.ai，2026 年 2 月）提供了以下配置模板：

json5
{
  agents: {
    defaults: {
      model: { primary: "lmstudio/minimax-m2.1-gs32" },
      models: { "lmstudio/minimax-m2.1-gs32": { alias: "Minimax" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "LMSTUDIO_KEY",
        api: "openai-completions",
        models: [{
          id: "minimax-m2.1-gs32",
          name: "MiniMax M2.1",
          reasoning: false,
          input: ["text"],
          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
          contextWindow: 200000,
          maxTokens: 8192,
        }],
      },
    },
  },
}

LiteLLM 的定位与其他三个运行时不同。它不在本地运行推理，而是作为代理呈现统一的 OpenAI 兼容接口来对接多个上游提供商。这使其在多模型路由场景中非常强大，你可以通过单一端点 http://localhost:4000/v1 在云端和本地模型之间切换。使用相同的 openai-completions API 类型配置它，并定义你的 LiteLLM 实例所服务的每个模型。在 OpenClaw 设置中，LiteLLM 的独特优势在于跨多个提供商账户的负载均衡和速率限制管理。如果你同时拥有 OpenAI 和 Anthropic 的 API 密钥，LiteLLM 可以自动将请求路由到有可用容量的提供商，无需对 OpenClaw 配置做任何更改（只需指向 LiteLLM 代理端点），即可有效地将吞吐量上限翻倍。

下表总结了这四种本地模型运行时的关键差异，帮助你选择最适合自己工作流的方案：

硬件需求因模型大小而显著不同。8B 参数模型（如 Llama 3.1 8B 或 Mistral 7B）在 8GB 显存（RTX 3060）上即可流畅运行。34B 模型需要 20-24GB 显存（RTX 3090 或 RTX 4090）并配合量化。70B 模型需要 40-48GB 显存（A100 40GB 或双 GPU 配置）才能达到可接受的推理速度。对于 Mac 用户，M4 系列芯片的统一内存提供了一条性价比较高的路径——16GB 的 Mac Mini M4 可以以每秒 15-20 个 token 的速度运行 7-8B 模型（marc0.dev，2026 年 2 月）。

高级多模型路由与安全配置

自定义提供商的真正威力在于将它们与 OpenClaw 的路由和故障转移能力相结合。你可以设计一个同时优化成本、性能和可靠性的模型栈，而不是依赖单一模型。

一个实用的三层路由配置根据任务复杂度分配模型。将高端模型如 anthropic/claude-opus-4-6 用于复杂推理和架构设计——Claude Opus 4.5 的价格为每百万 token 输入/输出 $15/$75（haimaker.ai，2026 年 2 月），但在多文件编辑和复杂调试方面优于任何替代方案。将日常编码工作路由到中端模型如 moonshot/kimi-k2.5 或 anthropic/claude-sonnet-4-5，每百万 token 价格为 $3/$15，能覆盖绝大多数代码生成和审查任务。将心跳检查、文件查找和简单补全分配给经济型模型如 google/gemini-3-flash-lite（每百万 token $0.50）或 DeepSeek V3.2（每百万 token $0.53）——相比 Opus 的常规操作，成本降低了 60 倍（velvetshark.com，2026 年 2 月）。成本节省会快速累积：轻度用户报告约 65% 的月度节省（约每月省 $130），而实施完整三层路由的重度用户相比单模型配置每月节省超过 $600。故障转移链配置确保即使个别提供商出现故障也能持续运行：

json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: [
          "moonshot/kimi-k2.5",
          "openai/gpt-5.1-codex",
          "ollama/llama3.3"
        ]
      },
    },
  },
}

这个级联意味着如果 Anthropic 触及速率限制，请求会自动转到 Moonshot，然后是 OpenAI，再然后是你的本地 Ollama 实例——确保你的代理永不停止工作。对于管理 token 管理和成本优化策略 的团队来说，这种方法相比在单一高端模型上运行所有任务可节省 50-65% 的成本。

每代理模型覆盖进一步扩展了路由模型。agents.list[].model 配置允许为 OpenClaw 生态系统中的各个代理分配特定模型，因此代码审查代理可以使用 Opus 以获取更高的准确性，而文件搜索代理可以使用本地模型以获取更快的速度。这种按任务类型对模型分配的精细控制，正是基础配置与真正优化的多模型设置之间的区别所在。

在配置自定义提供商时，安全性值得特别关注。最重要的实践是将 API 密钥存储在环境变量中，而不是直接写在 openclaw.json 中。始终使用 ${VAR_NAME} 语法，确保凭据永远不会出现在可能被提交到版本控制的配置文件中。对于企业部署，模型白名单提供访问控制——设置 agents.defaults.models 以明确列出允许的模型，任何未列出的模型都会被拒绝。openclaw models status 命令显示所有已配置提供商的身份验证状态，帮助你验证凭据是否正确加载而不暴露实际密钥值。使用 laozhang.ai 或类似代理服务时，单个 API 密钥即可替代多个提供商凭据，减少凭据管理面的同时通过一个统一端点提供对数十个上游模型的访问。

对于共享 OpenClaw 配置的团队，建议将身份验证凭据与结构化配置完全分离。将 openclaw.json 存入版本控制，所有 API 密钥使用 ${VAR_NAME} 占位符，实际凭据通过密钥管理器或团队密码保险库分发。这种模式确保新团队成员可以克隆仓库并通过设置环境变量即可开始工作，而不会有凭据出现在 git 历史中的风险。agents.defaults.models 中的模型白名单增加了另一层治理，限制团队成员可以激活哪些模型，防止意外使用昂贵的高端模型来处理经济型模型同样能完成的任务。结合模型定义中准确的 cost 值启用的成本跟踪，你就能在整个团队范围内获得每个模型支出的可见性，而无需依赖外部监控工具。

自定义模型问题排查

自定义模型配置引入了与内置提供商不同的故障模式。以下内容涵盖了最常见的错误、根本原因以及确切的解决步骤。每次调试会话都应从 openclaw models status --probe 开始，该命令会对所有已配置的提供商执行实时连接测试，在一次输出中暴露身份验证、路由和连接问题。

"Model 'provider/model' is not allowed" 出现在模型白名单处于活动状态且你的自定义模型未包含在内时。这是添加新提供商时报告最多的问题。修复方法是将你的模型添加到 agents.defaults.models 白名单中：

json5
{
  agents: {
    defaults: {
      models: {
        "moonshot/kimi-k2.5": { alias: "Kimi" },
        // ... 在此添加你的自定义模型
      },
    },
  },
}

或者完全移除 agents.defaults.models 键以禁用白名单。这适用于个人设置，但不建议在需要控制模型访问的团队环境中使用。

"Connection refused" 或 "ECONNREFUSED" 出现在 OpenClaw 无法访问配置的 baseUrl 时。对于本地运行时，请验证服务器确实在运行——Ollama 用 curl http://localhost:11434/v1/models，LM Studio 用 curl http://localhost:1234/v1/models，vLLM 用 curl http://localhost:8000/v1/models。如 果 curl 命令也失败，说明推理服务器未运行或正在监听其他端口。对于 Docker 部署，请记住容器内的 localhost 指的是容器自身而非宿主机——请使用 host.docker.internal 或宿主机的 IP 地址。

"Invalid API key" 或 "401 Unauthorized" 意味着身份验证凭据缺失或不正确。首先使用 echo $YOUR_API_KEY_VAR 验证环境变量是否已设置——空响应意味着该变量未在当前 shell 会话中导出。确保 export 语句在 ~/.zshrc 或 ~/.bash_profile 中，且编辑后已经 source 过该文件。如果在 openclaw.json 中使用了 ${VAR_NAME} 语法，请确认变量名完全匹配——${MOONSHOT_API_KEY} 需要 export MOONSHOT_API_KEY='sk-...'，而不是 MOONSHOT_KEY 或 moonshot_api_key。如需更详细的 API 密钥调试，请参阅我们的 OpenClaw API 密钥认证错误指南。

"Unknown provider" 或 "Provider not found" 通常意味着模型引用中的提供商名称与任何内置或自定义提供商定义都不匹配。检查 models.providers 中的提供商键是否与你在模型引用中使用的完全一致——如果你定义了 providers: { "my-llm": { ... } }，模型引用必须是 my-llm/model-id，而不是 myllm/model-id 或 myLLM/model-id。

"Tool calling failed" 或 "Structured output not supported" 表示该模型不支持 OpenClaw 工具交互所使用的函数调用格式。并非所有模型都支持结构化工具调用——只有专门为函数调用训练的模型（如 Llama 3.1、支持函数调用的 Mistral、GPT 变体和 Claude 变体）才能与 OpenClaw 的工具系统可靠地配合工作。为不具备此功能的模型在定义中设置 reasoning: false，并考虑仅将它们用于简单的补全任务而非作为主代理模型。openclaw models status --probe 命令可以直接测试工具支持情况。

"Gateway timeout" 或响应缓慢 指向网络延迟或推理服务器过载。对于本地模型，请验证模型是否已完全加载到内存中——大型模型加载后的首次请求可能需要 30-60 秒。如有需要，可在配置中增加网关超时时间。对于持续遇到速率限制的云端提供商，配置回退以在多个提供商之间分配负载。我们的 速率限制故障排查指南 涵盖了针对不同提供商处理 429 错误的具体策略。

配置语法错误 尤其隐蔽，因为它们可能阻止整个网关启动。OpenClaw 的配置解析器非常严格——多余的逗号、字符串值缺少引号或嵌套层级不正确都会导致静默失败，网关启动但忽略了格式错误的提供商定义。openclaw doctor 命令提供全面的诊断，检查配置文件语法、提供商连接性、模型可用性和身份验证状态。每当配置更改产生意外行为时运行它——它能捕获手动检查常常遗漏的问题，包括 "Moltbot [OpenClaw] 的配置是严格校验的，不正确或多余的字段可能导致网关启动失败"（阿里云社区，2026 年 2 月）这类严格的 JSON 校验。一个实用的调试模式是从最小配置开始——baseUrl、apiKey、api 以及仅包含 id 和 name 的单个模型——用 openclaw models list --provider yourprovider 验证其正常工作，然后逐步添加 cost、contextWindow 和 reasoning 等可选字段，每次添加后都进行测试。

当其他方法都不奏效时，三步诊断流程可以解决大多数剩余问题。首先，运行 openclaw models status --probe 测试所有提供商的连接性和身份验证。其次，检查网关日志以获取 CLI 可能未展示的具体错误信息。第三，直接用 curl 测试提供商端点——curl -X POST http://your-endpoint/v1/chat/completions -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" -d '{"model":"model-id","messages":[{"role":"user","content":"test"}]}'——以隔离问题究竟出在 OpenClaw 的配置还是提供商本身。

常见问题

自定义微调模型能在 OpenClaw 中使用吗？ 可以，只要模型通过 OpenAI 兼容或 Anthropic 兼容的 API 端点提供服务即可。托管在 vLLM、Ollama（通过自定义 Modelfile）或任何暴露标准 chat completions 端点的推理服务器上的微调模型都可以使用 models.providers 配置。将 id 字段设置为你的服务器期望的确切模型标识符，并将 contextWindow 和 maxTokens 配置为与微调模型的实际能力匹配。

如何在聊天会话中切换自定义模型？ 使用 /model 命令加上完整的提供商/模型引用即可。例如，/model moonshot/kimi-k2.5 切换到 Kimi K2.5，/model ollama/llama3.3 切换到本地 Llama。/model list 命令显示所有可用模型，/model status 显示当前选择。无需重启——切换在下一条消息时立即生效。

如果自定义提供商在任务执行过程中宕机怎么办？ OpenClaw 的故障转移系统会自动激活。如果你配置了 agents.defaults.model.fallbacks，请求会自动路由到链中下一个可用的提供商。如果没有配置回退，当前请求会失败，你可以使用 /model 手动切换模型。为了生产环境的可靠性，始终配置至少两个来自不同提供商的回退模型。

自定义提供商的数量有限制吗？ models.providers 中的提供商数量没有硬性限制。实际考虑因素包括维护连接池的内存使用量以及管理多个 API 密钥的复杂度。大多数用户发现三到五个自定义提供商——涵盖云端 API、本地运行时和代理服务的组合——即可提供足够的灵活性而不会增加过多管理负担。

models.providers 配置是否适用于 OpenClaw Web UI 和移动应用？ 是的。openclaw.json 中的 models.providers 配置在所有 OpenClaw 界面中全局生效，包括 CLI、Web UI（通过 openclaw dashboard 访问）以及任何已连接的聊天平台（如 Discord 或 Telegram）。http://127.0.0.1:18789/ 上的仪表板提供了一种可视化方式来测试自定义提供商，然后再将其部署到生产频道。这意味着你只需在 JSON 文件中配置一次自定义提供商，即可立即在任何界面使用它，包括通过网关 API 的编程访问。配置更改在使用 openclaw gateway restart 重启网关后生效——添加新提供商到现有设置时无需重新安装或重新引导。