自定义提供程序和本地运行时

通过 models.providers 提供者 （custom/base URL）

使用 models.providers（或 models.json）添加 custom 提供程序或 OpenAI/Anthropic-compatible 代理。

下面许多内置的提供商插件已经发布了默认目录。只有在你想覆盖默认基础 URL、请求头或模型列表时，才使用显式的 models.providers.<id> 条目。

捆绑和目录已知的路由从拥有的提供商插件中获取其 compat 功能。配置 compat 块用于自定义 provider/model 或您已验证其端点合同的不同 api/baseUrl 路由；请参阅 定制提供商能力指南。 Doctor 删除了仅重复目录的遗留值，并留下不同的值供操作员查看。

自定义端点不会继承原始目录路由的首选代码模式层。通过自动代码模式并且无需自定义 compat.codeMode 声明，嵌入式运行时保持其正常的工具表面。仅在验证该端点上的代码模式后才设置 compat.codeMode: "preferred"。

提供商标准化别名（例如 Anthropic 端点的 /v1 后缀）保留其标准目录功能。

Gateway 的模型能力检查也会读取显式的 models.providers.<id>.models[] 元数据。如果自定义或代理模型接受图像，请在该模型上设置 input: ["text", "image"]，这样 WebChat 和 node-origin 附件路径就会将图像作为原生模型输入传递，而不是仅文本的媒体引用。

agents.defaults.models["provider/model"] 用于控制 agents 的别名和每个模型的元数据。它既不会限制覆盖，也不会单独注册新的运行时模型。对于自定义提供商模型，还要添加 models.providers.<provider>.models[]，并至少包含匹配的 id；当你想要覆盖限制时，请另外使用 agents.defaults.modelPolicy.allow。

Moonshot AI (Kimi)

在引导流程之前安装 @openclaw/moonshot-provider。只有在你需要覆盖基础 URL 或模型元数据时，才添加显式的 models.providers.moonshot 条目：

• 提供方：moonshot
• 认证：MOONSHOT_API_KEY
• 示例模型：moonshot/kimi-k3
• CLI：openclaw onboard --auth-choice moonshot-api-key 或 openclaw onboard --auth-choice moonshot-api-key-cn

Kimi 模型 ID：

[//]： # "moonshot-kimi-k2-model-refs：start"

• moonshot/kimi-k2.6
• moonshot/kimi-k3
• moonshot/kimi-k2.7-code
• moonshot/kimi-k2.7-code-highspeed
• moonshot/kimi-k2.5

[//]： # "moonshot-kimi-k2-model-refs：end"

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

参见 Moonshot AI（Kimi + Kimi Coding） 获取完整设置指南。

Kimi 编程

Kimi 编码使用 Moonshot AI 的 Anthropic- 兼容端点：

• 提供商：kimi
• 认证：KIMI_API_KEY
• Kimi K3：kimi/k3（最高 1M，按层级开放）或 kimi/k3-256k（256K，较低配额使用）
• Kimi 代码：kimi/kimi-for-coding
• Kimi 代码 HighSpeed： kimi/kimi-for-coding-highspeed

{  env: { vars: { KIMI_API_KEY: "sk-..." } },  agents: {    defaults: { model: { primary: "kimi/kimi-for-coding" } },  },}

Kimi K3 使用自适应思考。--thinking minimal|low 选择低强度， --thinking medium|high|adaptive 选择高强度，而 --thinking xhigh|max 选择最高强度。目录定价为输入 $3/MTok、输出 $15/MTok，以及缓存读取 $0.30/MTok。旧版 kimi/kimi-code 和 kimi/k2p5 仍然被接受为兼容模型 id，并会规范化为 Kimi 稳定 API 的模型 id；此前发布的 kimi/k3[1m] 引用会规范化为 kimi/k3，以兼容现有配置。

火山发动机（Doubao）

火山引擎（Volcano Engine）提供在中国访问 Doubao 等模型的服务。

• 提供商：volcengine（编码：volcengine-plan）
• 认证：VOLCANO_ENGINE_API_KEY
• 示例模型：volcengine-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice volcengine-api-key

{  agents: {    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },  },}

注册时默认使用编码界面，但通用的 volcengine/* 目录会同时注册。

在 onboarding/configure 模型选择器中，Volcengine 身份验证选择更喜欢 volcengine/* 和 volcengine-plan/* 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供者范围选择器。

BytePlus（国际版）

BytePlus ARK 为国际用户提供与火山引擎相同的模型访问能力。

• 插件：@openclaw/byteplus-provider
• 提供商：byteplus（编程：byteplus-plan）
• 认证：BYTEPLUS_API_KEY
• 示例模型：byteplus-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice byteplus-api-key

安装官方插件并重启网关：

openclaw plugins install @openclaw/byteplus-provideropenclaw gateway restart

{  agents: {    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },  },}

注册时默认使用编程界面，但通用的 byteplus/* 目录会同时注册。

在 onboarding/configure 模型选择器中，BytePlus 身份验证选择更喜欢 byteplus/* 和 byteplus-plan/* 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供者范围选取器。

Synthetic

Synthetic 在 synthetic 提供程序背后提供 Anthropic- 兼容模型：

• 提供商：synthetic
• 认证：SYNTHETIC_API_KEY
• 示例模型：synthetic/hf:MiniMaxAI/MiniMax-M3
• CLI: openclaw onboard --auth-choice synthetic-api-key

{  agents: {    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M3" } },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [{ id: "hf:MiniMaxAI/MiniMax-M3", name: "MiniMax M3" }],      },    },  },}

MiniMax

MiniMax 通过 models.providers 配置，因为它使用自定义端点：

• MiniMax OAuth（全球）：--auth-choice minimax-global-oauth
• MiniMax OAuth (CN): --auth-choice minimax-cn-oauth
• MiniMax API 密钥（全球）：--auth-choice minimax-global-api
• MiniMax API 密钥 （CN）： --auth-choice minimax-cn-api
• Auth：MINIMAX_API_KEY 为 minimax； MINIMAX_OAUTH_TOKEN 或 MINIMAX_API_KEY 适用于 minimax-portal

请参见 /providers/minimax 获取设置详情、模型选项和配置片段。

插件拥有的能力划分：

• Text/chat 默认保留在 minimax/MiniMax-M3
• 图像生成使用 minimax/image-01 或 minimax-portal/image-01
• 图像理解在两种 MiniMax 认证路径上都由插件拥有的 MiniMax-VL-01 提供
• Web 搜索停留在提供商 ID minimax 上

llama.cpp

捆绑的 llama-cpp 插件为一个本地文本提供程序提供了两种设置选择：

• 托管本地服务器安装并监督经过验证的llama服务器和本地GGUF文件。
• E现有的 llama-server 连接到您操作的服务器并发现其模型。

为任一路径安装一次插件：

openclaw plugins install @openclaw/llama-cpp-provider

两者都使用 llama-cpp/<model> 参考。有关设置、发现、身份验证和托管本地嵌入的信息，请参阅 llama.cpp。

llmman

llmman 通过 models.providers 配置为 OpenAI- 兼容的本地服务器。它将模型作为 OCI 工件拉取，并通过上游 llama-server、vllm 或 mlx-lm 为它们提供服务，并且可以在单个模型 ID 下将本地模型与托管模型配对：

• Provider：llmman（自定义；api: "openai-completions"）
• Auth：不强制执行；设置 LLMMAN_API_KEY=llmman-local 并使用 apiKey: "${LLMMAN_API_KEY}"
• 默认底座URL：http://127.0.0.1:17434/v1
• 示例模型：llmman/qwen3.8
• H混合示例：llmman/llmman.hybrid/qwen3.8,openai/gpt-5.6-luna

llmman pull qwen3.8llmman serve

{  agents: {    defaults: { model: { primary: "llmman/qwen3.8" } },  },  models: {    providers: {      llmman: {        baseUrl: "http://127.0.0.1:17434/v1",        apiKey: "${LLMMAN_API_KEY}",        api: "openai-completions",        models: [          { id: "qwen3.8", name: "Qwen3.8 (llmman)", reasoning: true, input: ["text", "image"] },        ],      },    },  },}

请参阅 /providers/llmman 了解设置、混合本地 + 托管路由、愿景和故障排除。

LM Studio

LM Studio 作为一个内置提供商插件发布，使用原生 API：

• 提供商：lmstudio
• 认证：LM_API_TOKEN
• 默认推理基础 URL：http://localhost:1234/v1

然后设置一个模型（替换为 http://localhost:1234/api/v1/models 返回的 ID 之一）：

{  agents: {    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },  },}

OpenClaw 使用 LM Studio 的原生 /api/v1/models 和 /api/v1/models/load 进行发现 + 自动加载，并默认使用 /v1/chat/completions 进行推理。如果你希望由 LM Studio 自己管理模型生命周期（JIT 加载、TTL 和自动逐出），请将 models.providers.lmstudio.params.preload: false。有关设置和故障排除，请参见 /providers/lmstudio。

Ollama

Ollama 作为一个内置提供商插件发布，并使用 Ollama 的原生 API：

• 提供商：ollama
• 认证：不需要（本地服务器）
• 示例模型：ollama/llama3.3
• 安装：https://ollama.com/download

# Install Ollama, then pull a model:ollama pull llama3.3

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

当您选择使用 OLLAMA_API_KEY 时，会在 http://127.0.0.1:11434 本地检测到 Ollama，并且捆绑的提供程序插件将 Ollama 直接添加到 openclaw onboard 和模型选择器中。请参阅 /providers/ollama 了解入门、cloud/local 模式和自定义配置。

vLLM

vLLM 作为 local/self-hosted OpenAI- 兼容服务器的捆绑提供商插件提供：

• 提供商：vllm
• 认证：可选（取决于你的服务器）
• 默认基础 URL：http://127.0.0.1:8000/v1

要在本地启用自动发现（如果你的服务器不强制认证，任何值都可以）：

export VLLM_API_KEY="vllm-local"

然后设置一个模型（替换为 /v1/models 返回的 ID 之一）：

{  agents: {    defaults: { model: { primary: "vllm/your-model-id" } },  },}

详情请参见 /providers/vllm。

SG郎

SGLang 作为快速自托管 OpenAI- 兼容服务器的捆绑提供程序插件提供：

• 提供商：sglang
• 认证：可选（取决于你的服务器）
• 默认基础 URL：http://127.0.0.1:30000/v1

要在本地启用自动发现（如果你的服务器不强制认证，任何值都可以）：

export SGLANG_API_KEY="sglang-local"

然后设置一个模型（替换为 /v1/models 返回的 ID 之一）：

{  agents: {    defaults: { model: { primary: "sglang/your-model-id" } },  },}

详情请参见 /providers/sglang。

本地代理（LM Studio、vLLM、LiteLLM 等）

示例（OpenAI- 兼容）：

{  agents: {    defaults: {      model: { primary: "lmstudio/my-local-model" },      models: { "lmstudio/my-local-model": { alias: "Local" } },    },  },  models: {    providers: {      lmstudio: {        baseUrl: "http://localhost:1234/v1",        apiKey: "${LM_API_TOKEN}",        api: "openai-completions",        timeoutSeconds: 300,        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 200000,            maxTokens: 8192,          },        ],      },    },  },}