拒绝黑盒：手写 JSON 配置 Ollama 与 OpenClaw

对于习惯掌控一切的开发者来说，图形界面里的“一键启动”往往意味着黑盒。你不知道它到底调用了哪个后端，上下文窗口被截断到了多少，更不知道当报错发生时该改哪里。在本地部署 AI 工作流时，真正的控制权来自于配置文件。今天我们就抛开 LM Studio 的滑块和按钮，直接通过编辑 JSON 文件，将 Ollama（或兼容 OpenAI 协议的本地服务）与 OpenClaw 深度绑定，打造一条完全透明、可调试的自动化链路。

这种“手写配置”的方式不仅能让你的 Agent 运行得更稳定，还能让你清晰理解 baseUrl、apiKey 以及最关键的 contextWindow 是如何在两个系统间握手的。

核心配置解析：打通模型服务的任督二脉

OpenClaw 的核心优势在于其灵活的代理编排能力，但它需要一个可靠的模型后端。虽然 Ollama 原生使用自己的协议，但通过开启兼容模式或使用中间件，我们可以让它以标准 OpenAI 格式对外服务。假设你已经在本地启动了服务（无论是原生的 Ollama 还是通过其他工具暴露的接口），监听地址通常为 http://127.0.0.1:11434 或映射后的 1234 端口。

我们需要找到 OpenClaw 的配置文件，通常位于用户目录下的 ~/.openclaw/openclaw.json。打开它，我们将手动构建 models 部分。这不是简单的复制粘贴，每一行都有其存在的逻辑。

{
  "models": {
    "providers": {
      "local-ollama": {
        "baseUrl": "http://127.0.0.1:11434/v1",
        "apiKey": "ollama-is-all-you-need",
        "api": "openai-responses",
        "models": [
          {
            "id": "qwen2.5-coder:7b",
            "contextWindow": 32768,
            "maxTokens": 4096
          }
        ]
      }
    },
    "agents": {
      "defaults": {
        "model": {
          "primary": "local-ollama/qwen2.5-coder:7b"
        }
      }
    }
  }
}

这段配置中有三个关键点值得逐行拆解：

首先是 baseUrl。很多初学者在这里栽跟头，直接填了 http://127.0.0.1:11434 而忽略了末尾的 /v1。OpenClaw 默认遵循 OpenAI 的 API 规范，请求路径通常是 /v1/chat/completions。如果基础 URL 缺少版本后缀，框架拼接出的完整地址就会变成 404，导致连接被拒绝。务必确认你的本地服务是否开启了 HTTP API 兼容层，并在地址后显式加上 /v1。

其次是 apiKey。对于本地私有化部署，安全性不是首要考虑，连通性才是。Ollama 默认不需要密钥，但 OpenClaw 的客户端实现通常会强制检查 Header 中的 Authorization 字段。随便填一个非空字符串（如上面的 ollama-is-all-you-need）即可骗过校验机制，让请求顺利发出。不要留空，否则可能直接抛出认证错误。

最后也是最容易出错的是 contextWindow。这个数值必须与你本地运行的模型实际支持的上下文长度严格一致，甚至要略保守一点。如果你在 Ollama 启动参数或 Modelfile 中限制了上下文为 32k，这里却写了 128k，当任务涉及长文档检索时，OpenClaw 会尝试发送超出模型处理能力的 prompt，导致服务端直接切断连接或返回 context_length_exceeded 错误。反之，如果这里写小了，Agent 就无法利用模型的全部记忆能力，造成信息丢失。

实战演练：创建自定义代理与连通性测试

配置保存后，不要急着跑复杂任务。先验证链路是否通畅。在终端执行以下命令重启网关，确保新配置生效：

openclaw gateway restart

接着，我们创建一个最简单的测试代理指令，用于验证“手”和“脚”是否听使唤。新建一个任务描述文件 test-task.md：

# Task: Local Connectivity Check
请读取当前目录下的 README.md 文件，提取前三行内容，并以 JSON 格式输出。
不需要联网搜索，仅使用本地知识库。

运行代理：

openclaw run test-task.md

如果配置正确，你应该能在终端看到实时的日志流，显示 OpenClaw 正在向 127.0.0.1 发起请求，并迅速收到模型的响应。如果卡住不动，大概率是网络层面的问题。

常见的报错是 Connection Refused。这时候别慌，按以下步骤排查：

1. 检查端口占用：使用 netstat -ano | findstr 11434 (Windows) 或 lsof -i :11434 (Mac/Linux) 确认 Ollama 是否真的在监听该端口。
2. 验证 API 路径：直接在浏览器或 curl 中访问 http://127.0.0.1:11434/v1/models。如果这里都打不开，说明服务没起对，或者防火墙拦截了本地回环请求。
3. 核对 JSON 语法：有时候仅仅是配置文件里多了一个逗号或少了一个大括号，导致整个配置加载失败，程序回退到了默认的空配置。可以用在线 JSON 校验工具过一遍。

深度调优：解决上下文不匹配的隐形坑

在实际的高负载场景中，最隐蔽的问题往往来自 contextWindow 的不一致。我曾遇到过一个案例：本地模型明明支持 128k 上下文，但在处理一份大型代码库时，Agent 总是读到一半就“失忆”了，或者干脆报错退出。

检查发现，OpenClaw 配置文件中该值被默认设为了 8192。这意味着无论模型多强大，框架在组装 Prompt 时，只会截取最近的 8k token 发送给后端。对于需要跨文件引用变量的编程任务，这显然是不够的。

解决方法很简单：打开 openclaw.json，将对应模型的 contextWindow 调整为与实际模型能力匹配的值，例如 131072。同时，也要留意 maxTokens 的设置。如果你希望生成的报告非常详尽，需要将 maxTokens 调大（如 8192 或更高），否则模型会在输出中途因为达到 token 上限而强行截断，导致生成的代码缺少结尾的大括号或函数未闭合。

修改完成后，再次重启服务。此时再观察日志，你会发现发送的 payload 体积明显增大，而模型的回复也更加完整连贯。这种通过手动微调参数带来的性能提升，是任何“智能自动优化”都无法替代的。

通过这种纯文本配置的方式，我们不仅避开了图形界面的不确定性，更建立了一套可版本控制、可复现的本地 AI 工作流。每一次修改都有迹可循，每一个参数都心中有数。当你看着终端里滚动的日志，确认每一个字节都在自己的机器内安全流转时，这种对数据的绝对掌控感，才是本地部署最大的魅力所在。

200小时GPU算力已就位，快来领取：https://marketing.csdn.net/questions/Q2604140858304426315?utm_source=AIpaper