本地模型
OpenClaw 可以安装并管理本地模型,也可以连接到你已经运行的服务器。如需基于硬件的推荐,请安装 llama.cpp 插件,运行 openclaw onboard,并选择 托管本地服务器。设置过程会在下载前显示 Gateway 主机、模型、下载大小和执行后端,然后在更改默认模型前验证一次真实工具调用。当你希望单独管理模型时,LM Studio 和 Ollama 仍然是可选方案。
本页还涵盖更大的本地技术栈和自定义 OpenAI 兼容服务器。本地模型不提供托管提供商的安全过滤。请根据模型和任务保持适当的工具权限和提示注入防御。
对于仅在选择模型需要时才启动的本地服务器,请参见 本地模型服务。
硬件最低要求¶
内存需求取决于模型权重、上下文大小、运行时以及主机上的其他工作负载。托管 llama.cpp 设置会检查可用 RAM、受支持的 GPU 内存和磁盘空间,而不是假定特定机器。其精选配方使用 64K 上下文。最小配方的主机内存下限为 8 GiB,更大的配方需要更多内存。这些下限不保证可运行性或速度。当前模型目录请参见 模型推荐。
对于自定义服务器,请为完整的 OpenClaw 提示、工具、历史和模型输出预留空间。能够加载或回答短提示的模型仍可能无法完成智能体回合。在将其设为默认之前,请测试实际任务,并查看 本地模型安全。
选择后端¶
| 后端 | 适用场景 |
|---|---|
| ds4 | 在 macOS Metal 上本地运行 DeepSeek V4 Flash,并支持 OpenAI 兼容工具调用 |
| LiteLLM / OAI-proxy / 自定义 OpenAI 兼容代理 | 当你在另一个模型 API 前做代理,并需要 OpenClaw 将其视为 OpenAI 时 |
| llama.cpp | 硬件感知的模型选择、经过验证的下载,以及由 OpenClaw 管理的服务器 |
| llmman | OCI 注册表模型拉取、上游 llama.cpp/vLLM/MLX 引擎、本地 + 托管混合路由 |
| LM Studio | 首次本地设置、GUI 加载器、原生 Responses API |
| MLX / vLLM / SGLang | 高吞吐自托管服务,并提供 OpenAI 兼容 HTTP 端点 |
| Ollama | CLI 工作流、模型库、免维护的 systemd 服务 |
当后端支持时,请使用 api: "openai-responses"(LM Studio 支持)。否则使用 api: "openai-completions"。如果带有 baseUrl 的自定义提供商省略了 api,OpenClaw 默认使用 openai-completions。
Warning
WSL2 + Ollama + NVIDIA/CUDA: 官方 Ollama Linux 安装程序会启用带有 Restart=always 的 systemd 服务。在 WSL2 GPU 环境中,自动启动可能在开机时重新加载上一个模型并占用主机内存,导致虚拟机反复重启。参见 WSL2 崩溃循环。
LM Studio + 大型本地模型(Responses API)¶
对于单独管理的本地服务器,请在 LM Studio 中加载适合你硬件的模型。启用本地服务器(默认 http://127.0.0.1:1234)。使用 Responses API 将推理与最终文本分开。
{
agents: {
defaults: {
model: { primary: "lmstudio/my-local-model" },
models: {
"anthropic/claude-opus-4-6": { alias: "Opus" },
"lmstudio/my-local-model": { alias: "Local" },
},
},
},
models: {
mode: "merge",
providers: {
lmstudio: {
baseUrl: "http://127.0.0.1:1234/v1",
apiKey: "lmstudio",
api: "openai-responses",
models: [
{
id: "my-local-model",
name: "Local Model",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 196608,
maxTokens: 8192,
},
],
},
},
},
}
设置清单:
- 安装 LM Studio:https://lmstudio.ai
- 下载可用的最大模型构建(避免 "small"/高度量化变体),启动服务器,并检查
http://127.0.0.1:1234/v1/models是否列出该模型。 - 将
my-local-model替换为 LM Studio 中显示的实际模型 ID。 - 保持模型已加载。冷加载会增加启动延迟。
- 如果你的 LM Studio 构建不同,请调整
contextWindow/maxTokens。 - 对于 WhatsApp,请坚持使用 Responses API,以便只发送最终文本。
- 保持
models.mode: "merge",以便托管模型仍可作为回退方案。
混合配置:托管主模型,本地回退¶
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-6",
fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],
},
models: {
"anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
"lmstudio/my-local-model": { alias: "Local" },
"anthropic/claude-opus-4-6": { alias: "Opus" },
},
},
},
models: {
mode: "merge",
providers: {
lmstudio: {
baseUrl: "http://127.0.0.1:1234/v1",
apiKey: "lmstudio",
api: "openai-responses",
models: [
{
id: "my-local-model",
name: "Local Model",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 196608,
maxTokens: 8192,
},
],
},
},
},
}
对于本地优先并带有托管安全网,交换 primary/fallbacks 顺序,并保留相同的 providers 块和 models.mode: "merge"。
OpenClaw 回退会在提供商错误时按轮次切换模型。对于按请求路由,使小提示保留在本地模型,仅将超大提示发送到托管模型,请参阅使用 llmman 的 混合推理。
区域托管 / 数据路由¶
OpenRouter 上还存在托管的 MiniMax/Kimi/GLM 变体,带有区域固定端点(例如,美国托管)。选择区域变体可将流量保留在你选择的司法管辖区,同时为 Anthropic/OpenAI 回退保留 models.mode: "merge"。仅本地仍然是最强的隐私路径。托管区域路由是中间方案,当你需要提供商功能但希望控制数据流时使用。
其他 OpenAI 兼容的本地代理¶
MLX(mlx_lm.server)、vLLM、SGLang、LiteLLM、OAI-proxy 或任何自定义网关都可以工作,只要它暴露 OpenAI 风格的 /v1/chat/completions 端点。除非后端明确记录支持 /v1/responses,否则使用 openai-completions。
{
agents: {
defaults: {
model: { primary: "local/my-local-model" },
},
},
models: {
mode: "merge",
providers: {
local: {
baseUrl: "http://127.0.0.1:8000/v1",
apiKey: "sk-local",
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: 120000,
maxTokens: 8192,
},
],
},
},
},
}
自定义/本地提供商条目会信任其精确配置的 baseUrl 源,用于受保护的模型请求,包括环回、LAN、tailnet 和私有 DNS 主机。元数据、链路本地和本地用途 NAT64(64:ff9b:1::/48)源在没有明确选择加入的情况下仍会被阻止。请求其他私有源仍需要 models.providers.<id>.request.allowPrivateNetwork: true。将信任标志设置为 false 可退出精确源信任。
models.providers.<id>.models[].id 是提供商本地的——不要包含提供商前缀。对于使用 mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit 启动的 MLX 服务器:
models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"
在本地或代理的视觉模型上设置 input: ["text", "image"],以便图像附件被注入到代理轮次中。交互式自定义提供商引导会推断常见的视觉模型 ID,并只询问未知名称。非交互式引导使用相同的推断,并可用 --custom-image-input / --custom-text-input 覆盖它。
对于缓慢的本地/远程模型服务器,请先使用 models.providers.<id>.timeoutSeconds,再提高 agents.defaults.timeoutSeconds。提供商超时仅覆盖模型 HTTP 请求的连接、头部、正文流式传输以及受保护获取的总中止。如果代理或运行超时更低,也请提高它。提供商超时无法延长整个运行。
Note
对于自定义 OpenAI 兼容提供商,当 baseUrl 解析为环回、私有 LAN、.local 或裸主机名时,会接受非机密本地标记,例如 apiKey: "ollama-local"。OpenClaw 会将其视为有效的本地凭据,而不是报告缺少密钥。对于接受公共主机名的任何提供商,请使用真实值。
本地/代理 /v1 后端的行为说明:
- OpenClaw 将这些视为代理风格的 OpenAI 兼容路由,而不是原生 OpenAI 端点。
- 仅适用于原生 OpenAI 的请求整形不适用:没有
service_tier,没有 Responsesstore,没有 OpenAI 推理兼容负载整形,没有提示缓存提示。 - 隐藏的 OpenClaw 归属头(
originator、version、User-Agent)不会注入到自定义代理 URL 上。
兼容声明仅适用于此提供商行描述的自定义端点。目录已知路由则使用提供商拥有的功能。请参阅 自定义提供商功能指南。
针对更严格的 OpenAI 兼容后端的兼容覆盖:
- 仅字符串内容:一些服务器只接受字符串
messages[].content,而不是结构化内容部分数组。设置models.providers.<provider>.models[].compat.requiresStringContent: true。 - 严格消息键:如果服务器拒绝包含除
role/content以外更多键的消息条目,设置compat.strictMessageKeys: true。 - 括号工具文本:一些本地模型会以文本形式发出独立的括号工具请求,例如
[tool_name]后跟 JSON 和[END_TOOL_REQUEST]。OpenClaw 仅当名称与当前轮次中已注册的工具完全匹配时,才将这些提升为真正的工具调用。否则,它会保持为隐藏的、不支持的文本。 - 非结构化工具调用样文本:模型可以发出看起来像工具调用但并非结构化调用的 JSON、XML 或 ReAct 风格文本。OpenClaw 会将其保留为文本并记录警告。警告包含运行 ID、提供商和模型、检测到的模式,以及可用时的工具名称。这是提供商/模型不兼容,而不是已完成的工具运行。
- 强制使用工具:工具可能以助手文本、原始 JSON、XML 或 ReAct 形式出现,或者以空
tool_calls数组出现。首先检查服务器的聊天模板和解析器是否支持工具调用。如果解析器仅在强制使用工具时才能工作,则按模型覆盖默认代理值tool_choice: "auto":
{
agents: {
defaults: {
models: {
"local/my-local-model": {
params: {
extra_body: {
tool_choice: "required",
},
},
},
},
},
},
}
仅在每个正常轮次都应调用工具的地方使用此设置。将 local/my-local-model 替换为 openclaw models list 中的精确引用,或通过 CLI 设置:
openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
```
- **额外推理强度**:如果自定义的 OpenAI 兼容模型接受内置配置之外的 OpenAI 推理强度,请在该模型的 compat 块中声明它们。添加 `"xhigh"` 后,该模型引用会在 `/think xhigh`、会话选择器、Gateway 验证和 `llm-task` 验证中暴露:
```json5
{
models: {
providers: {
local: {
baseUrl: "http://127.0.0.1:8000/v1",
apiKey: "sk-local",
api: "openai-responses",
models: [
{
id: "gpt-5.4",
name: "GPT 5.4 via local proxy",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 196608,
maxTokens: 8192,
compat: {
supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],
reasoningEffortMap: { xhigh: "xhigh" },
},
},
],
},
},
},
}
```
## 更小或更严格的后端 {#smaller-or-stricter-backends}
如果模型能正常加载,但完整的 agent 轮次出现异常,请先检查传输层,然后检查工具使用情况和上下文预算。
1. **检查本地模型是否有响应** - 不使用工具,不使用 agent 上下文:
```bash
openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
```
2. **检查 Gateway 路由** - 仅发送 Prompt。它会跳过转录、AGENTS 引导、context-engine 组装、工具以及捆绑的 MCP 服务器。它仍会验证 Gateway 路由、认证和 provider 选择:
```bash
openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: pong" --json
```
3. **检查 Tool Search** 如果两项检查都通过,但真实 agent 轮次因格式错误的工具调用或过大的 Prompt 而失败。本地 Ollama 模型、LM Studio 和托管本地服务在 `tools.toolSearch` 未设置时会自动使用结构化 [Tool Search](../tools/tool-search.md)。其他后端可以通过 `tools.toolSearch: { mode: "tools" }` 启用它。这会延迟加载 schema,同时保留策略允许的能力。保持 `localModelLean` 未设置或将其设置为 `false`,以便可选工具仍然可用。同时检查服务器的实际上下文分配和内存使用情况。
4. **作为最后手段完全禁用工具** 通过为该模型设置 `models.providers.<provider>.models[].compat.supportsTools: false` - 然后 agent 将在没有工具调用的情况下运行。
5. **检查失败的请求和服务器日志。** 检查 chat 模板、上下文窗口、内存压力和服务器错误。仅文本检查成功并不能证明模型能够可靠地完成多步骤 agent 任务。
## 故障排除 {#troubleshooting}
- **Gateway 无法访问代理?** `curl http://127.0.0.1:1234/v1/models`。
- **LM Studio 模型未加载?** 重新加载它。冷启动是常见的“挂起”原因。
- **本地服务器提示 `terminated`、`ECONNRESET`,或在轮次中途关闭流?** OpenClaw 会在诊断中记录低基数的 `model.call.error.failureKind`,以及 OpenClaw 进程的 RSS/堆快照。对于 LM Studio/Ollama 内存压力,请将该时间戳与服务器日志或 macOS 崩溃/jetsam 日志进行比对,以检查模型服务器是否被终止。
- **上下文错误?** OpenClaw 会根据检测到的模型窗口或每个模型的 `models.providers.<provider>.models[].contextTokens` 上限推导上下文窗口预检阈值。低于 20% 时发出警告,下限为 **8k**。低于 10% 时硬性阻止,下限为 **4k**。降低该模型条目的 `contextTokens`,或提高服务器/模型上下文限制。
- **接近上下文限制时出现单 token 回复?** 当输入估算会将请求的输出上限降低到 16 个 token 以下时,OpenAI 兼容代理请求会进入上下文溢出恢复,即使 thinking 关闭也是如此。刻意设置的短上限在能够容纳时仍然有效。该估算较为保守:如果 Prompt 适合服务器但 OpenClaw 报告溢出,请减少 Prompt 或提高已配置的上下文限制,以匹配服务器的实际分配。
- **`messages[].content ... expected a string`?** 在该模型条目上添加 `compat.requiresStringContent: true`。
- **`validation.keys`,或“message 条目仅允许 `role` 和 `content`”?** 在该模型条目上添加 `compat.strictMessageKeys: true`。
- **直接调用 `/v1/chat/completions` 可以工作,但 `openclaw infer model run --local` 在 Gemma 或其他本地模型上失败?** 首先检查 provider URL、模型引用、认证标记和服务器日志。`model run` 会完全跳过 agent 工具。如果 `model run` 成功但更大的 agent 轮次失败,请检查 Tool Search 和已分配的上下文。仅对无法可靠调用工具的模型使用 `compat.supportsTools: false`。
- **工具调用显示为原始 JSON/XML/ReAct 文本,或 provider 返回空的 `tool_calls` 数组?** 不要添加一个盲目地将 assistant 文本转换为工具执行的代理。首先修复服务器的 chat 模板和解析器。如果模型仅在强制使用工具时才能工作,请添加上述 `params.extra_body.tool_choice: "required"` 覆盖。仅将该模型条目用于每轮都预期有工具调用的会话。
- **安全**:本地模型会跳过 provider 端过滤器。保持 agent 范围狭窄并开启压缩,以限制 Prompt 注入的影响范围。
### 本地模型精简模式 {#local-model-lean-mode}
在 **设置 → Agent 默认值 → 代理** 中配置精简模式,并显示高级设置,或使用下面的配置示例。保留的 `experimental.localModelLean` 键仍然受支持。
精简模式是一种高级故障排除覆盖,会明确限制能力。本地推理通常使用 [Tool Search](../tools/tool-search.md) 来延迟加载 schema,同时保留能力,因此除非你确实希望使用更小的工具集,否则请保持精简模式关闭。
`agents.defaults.experimental.localModelLean: true` 会在目录构建之前移除可选工具:`browser`、`automations`、`message`、`image_generate`、`music_generate`、`video_generate`、`tts` 和 `pdf`。这些被移除的工具无法通过 Tool Search 找到。明确允许或交付必需的工具仍然可用,尽管 Tool Search 可能会将它们编入目录,而不是直接暴露。当 `tools.toolSearch` 尚未设置时,精简模式还会将目录默认设置为结构化 Tool Search(`tool_search`、`tool_describe`、`tool_call`)。使用 `agents.entries.*.experimental.localModelLean` 将此范围限定到一个 agent。
安装程序不再写入此标志。对于旧安装,`openclaw doctor --fix` 会在其所有权标记仍匹配默认模型时,移除由 onboarding 拥有的 `true`。显式设置以及带有过期所有权标记的设置会被保留。将保留的标志设置为 `false` 可恢复可选功能;自动 Tool Search 仍适用于本地路由。
如果你已经全局调整了 Tool Search,OpenClaw 会保持该配置不变。设置 `tools.toolSearch: false` 可退出精简模式的 Tool Search 默认行为。
在结构化 `tools` 模式下,精简运行会在 Tool Search 控件旁直接显示 `exec`,以便经过编码调优的本地模型仍可选择其熟悉的 shell 路径。这仅改变 schema 可见性:常规工具策略、沙箱和 exec 审批仍然适用。显式 `code` 和 `directory` 模式保持其常规压缩行为。
#### 为什么是这些工具 {#why-these-tools}
这些工具的描述最大、参数形状最宽泛,或者最有可能让小型模型偏离正常的编码和对话路径。在小上下文或更严格的 OpenAI 兼容后端上,这正是以下区别:
- 工具 schema 能放入提示词,而不是挤占对话历史。
- 模型选择正确的工具,而不是因过多相似 schema 而发出格式错误的工具调用。
- Chat Completions 适配器保持在结构化输出限制内,而不是因工具调用负载大小返回 400。
模型仍具有 `read`、`write`、`edit`、`exec`、`apply_patch`、图像理解、网络搜索/抓取(如果已配置)、记忆以及会话/代理工具。除非你设置 `tools.toolSearch: false`,否则剩余目录工具仍可通过 Tool Search 访问;显式工具允许列表可以恢复被精简模式移除的功能。
#### 何时开启 {#when-to-turn-it-on}
一旦你已证明模型可以与 Gateway 通信,但完整代理轮次表现异常,就启用精简模式:
1. `openclaw infer model run --gateway --model <ref> --prompt "Reply with exactly: pong"` 成功。
2. 常规代理轮次因格式错误的工具调用、提示词过大或模型忽略其工具而失败。
3. 切换 `localModelLean: true` 可清除该故障。
#### 何时保持关闭 {#when-to-leave-it-off}
保持精简模式未设置,或设置 `agents.defaults.experimental.localModelLean: false`,以保留完整的策略批准工具集。安装程序会保留显式选择,并且永远不会自动启用精简模式。
精简模式不会替代 `tools.profile`、`tools.allow`/`tools.deny`,或模型 `compat.supportsTools: false` 逃生通道。对于特定代理永久更窄的工具集,请优先使用这些稳定配置项。
#### 启用 {#enable}
```json5
{
agents: {
defaults: {
experimental: {
localModelLean: true,
},
},
},
}
仅针对一个代理:
{
agents: {
entries: {
local: {
model: "lmstudio/gemma-4-e4b-it",
experimental: {
localModelLean: true,
},
},
},
},
}
在配置文件中更改标志后,重启 Gateway。精简过滤会移除 browser、automations、message、image_generate、music_generate、video_generate、tts 和 pdf,除非你使用 tools.allow 或 tools.alsoAllow 显式保留它们;Tool Search 可能仍会将保留的工具编入目录,而不是直接暴露它们。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw