把本地开源模型接进 OpenClaw：llama.cpp 自托管完整教程（零成本跑 Agent）

原创。本文教你用 llama.cpp 在本地起一个 OpenAI 兼容的模型服务器，然后把它接进 OpenClaw 当主力或备用模型——全程零 API 费用，配置参数全部来自官方文档。

OpenClaw 是 2026 年最火的开源个人 AI Agent 框架之一（GitHub 上 25 万+ star），默认接的是 Anthropic、OpenAI 这些云端模型。但很多人的使用场景是：不想把数据送出去、不想每个月付订阅费、或者就想试试开源模型。好消息是 OpenClaw 原生支持 OpenAI 兼容的本地端点，而 llama.cpp 恰好就自带一个这样的服务器。

这篇教程带你走完整条路：装 llama.cpp → 启动本地模型服务器 → 配置 OpenClaw 接入 → 设置云端/本地混合 fallback → 排掉最常见的坑。

为什么选 llama.cpp

在 OpenClaw 官方文档的本地模型页面里，llama.cpp 和 LM Studio、Ollama、vLLM 并列，是官方支持的几条路线之一。相比其他方案，llama.cpp 有几个实在的优势：

• 哪里都能跑：CPU、CUDA、Metal（Mac）、ROCm（AMD）、Vulkan 全支持，没有 GPU 也能用 CPU 硬扛
• 自带 OpenAI 兼容服务器：llama-server 一条命令就起一个 /v1/chat/completions 端点，OpenClaw 直接当 OpenAI 用
• 激进量化：支持 Q4_K_M 甚至更低的量化，让更大的模型跑在更小的内存里——这是它在官方文档里被点名"比 Ollama 更适合跑大模型"的原因
• 零依赖：单个可执行文件，不需要 Docker 也不需要 Python 环境

如果你的机器是 Mac 且想要图形界面，LM Studio 是更省事的选择；如果你习惯命令行和脚本化，llama.cpp 这条路线更干净。

第一步：安装 llama.cpp

先安装编译工具链，然后从源码构建（官方推荐方式，能拿到最新的模型格式支持）：

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j --clean-first --target llama-cli llama-mtmd-cli llama-server llama-gguf-split
cp llama.cpp/build/bin/llama-* llama.cpp

注意两点：

• 没有 NVIDIA GPU 就把 -DGGML_CUDA=ON 改成 -DGGML_CUDA=OFF，走纯 CPU 推理
• Apple Mac / Metal：同样设 -DGGML_CUDA=OFF，Metal 支持默认开启，不用额外配置

第二步：下载模型（GGUF 格式）

llama.cpp 跑的是 GGUF 格式的量化模型。用 hf 命令直接从 Hugging Face 拉：

hf download unsloth/Qwen3.5-9B-GGUF \
    --local-dir ~/models/qwen3.5-9b \
    --include "Qwen3.5-9B-Q4_K_M.gguf"

选量化档位的原则：你的内存能装下的最大档位。Q4_K_M 是性价比最高的起点（约 5-6GB 文件），内存富余可以上 Q6_K 或 Q8_0，追求速度可以试 Q3_K。别选太激进的量化——OpenClaw 官方文档特别警告过，小模型或重度量化的 checkpoint 会提高 prompt injection 风险，Agent 场景下模型质量直接关系到安全。

第三步：启动 llama-server

./llama.cpp/llama-server \
  -m ~/models/qwen3.5-9b/Qwen3.5-9B-Q4_K_M.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  --ctx-size 32768 \
  --n-gpu-layers 999

参数说明：

• -m：模型文件路径
• --host 0.0.0.0：允许局域网访问（如果 OpenClaw 跑在别的机器上；本机用 127.0.0.1 更安全）
• --ctx-size：上下文长度，32K 是个稳妥的起点
• --n-gpu-layers 999：尽可能多地把层放到 GPU（CPU 机器会忽略）

起好后验证一下端点：

curl http://127.0.0.1:8080/v1/models

能看到模型列表就说明服务器正常。

第四步：把 OpenClaw 指向本地模型

llama.cpp 的服务器说 OpenAI 的协议，所以 OpenClaw 里把它配成一个自定义 OpenAI 兼容提供商。编辑 OpenClaw 的配置文件（openclaw config edit 或直接改 ~/.openclaw/config.json5），加入：

{
  agents: {
    defaults: {
      model: { primary: "local/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8080/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: 32768,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

几个关键点：

• api: "openai-completions"：llama.cpp 不支持 OpenAI 的 Responses API，必须用 completions。官方文档明确说，除非后端明确支持 /v1/responses，否则一律用 openai-completions（省略 api 字段时 OpenClaw 默认也是它）
• apiKey 随便填：llama.cpp 默认不校验 key，填个非空字符串就行（除非你启动服务器时加了 --api-key）
• cost 全 0：本地模型不花钱，这样 OpenClaw 不会把 token 费用计入统计
• contextWindow 要和 llama-server 的 --ctx-size 对上：配置里写 32768，服务器也得是 32768，否则上下文窗口检测会出偏差
• models.mode: "merge"：必须保留，这样你原来配置的云端模型不会丢，还能当 fallback

第五步：混合配置——云端主力 + 本地备用

官方文档给了一个很实用的模式：hosted primary, local fallback。云端模型干重活，本地模型当保险——API 挂了、额度用完了，Agent 自动切到本地，不至于完全停摆：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["local/my-local-model", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "local/my-local-model": { alias: "Local" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      local: { /* 同上一步 */ },
    },
  },
}

想反过来做"本地优先、云端兜底"，把 primary 和 fallbacks 的顺序对调即可。

常见坑与排查

接本地模型最容易踩的坑，OpenClaw 官方文档基本都列了：

1. 工具调用变成了原始文本（最常见） Agent 该调工具时，输出却是一堆 JSON/XML 或 [tool_name] 之类的原始文本。官方文档说得直白：不要加一个"盲目把文本转成工具调用"的代理层，先修服务器的 chat template 或解析器——这是模型/服务器不兼容，不是 OpenClaw 的 bug。

如果确定模型的解析器只有强制工具调用时才工作，可以按模型单独覆盖：

{
  agents: {
    defaults: {
      models: {
        "local/my-local-model": {
          params: {
            extra_body: { tool_choice: "required" },
          },
        },
      },
    },
  },
}

注意这会让每个正常回合都强制调用工具，只适用于"每轮都该调工具"的会话。

2. 上下文窗口报错 OpenClaw 会根据模型配置的窗口做预检：低于 20% 警告（下限 8k），低于 10% 硬阻断（下限 4k）。报错就检查两处——配置里的 contextWindow 和 llama-server 的 --ctx-size，把小的那个调大。

3. messages[].content ... expected a string 某些本地服务器只接受字符串格式的 content，不接受结构化的 content 数组。在模型配置里加：

compat: { requiresStringContent: true }

4. 报 "message entries only allow role and content" 服务器拒绝含多余字段的消息，加：

compat: { strictMessageKeys: true }

5. 服务器频繁中断（terminated / ECONNRESET） 多半是内存压力——量化档位选大了。用 qwen3.5-9b 这类 9B 模型配 Q4_K_M，16GB 内存的机器跑 32K 上下文基本没问题；24GB 以上可以放心上更大的模型。

6. 最后手段 模型加载正常但整个 Agent 回合就是不对劲，按官方文档从上到下排查：先确认本地模型裸响应正常（不带工具、不带 Agent 上下文），再逐步缩小范围。实在不行，把该模型的工具支持关掉：compat.supportsTools: false——Agent 就不调工具了。如果这样还不行，问题基本出在模型或服务器本身（上下文窗口、显存、kv-cache 逐出），跟 OpenClaw 无关。

安全提醒

官方文档在本地模型页面开头就强调了：本地模型绕过了提供商的过滤层。云端模型有厂商的安全过滤器兜底，本地模型没有。所以：

• 尽量跑你能跑的最大模型，别用重度量化的版本
• Agent 权限收窄，别给它无限制的 shell 访问
• 保持 compaction（上下文压缩）开启，限制 prompt injection 的影响范围

小结

整套流程下来，你的 OpenClaw 就有了一个完全免费、数据不出机器的模型通道：llama.cpp 起服务器 → 配置文件加一个 local provider → primary 或 fallbacks 指向它。云端模型该用还用，本地模型该省就省，两者还能自动切换。对于在意隐私、预算或者纯粹想折腾开源模型的开发者，这是官方文档支持的、最干净的一条路。