《OpenClaw (Docker手工部署版) 终极避坑与实战指南》

🦞 OpenClaw (Docker纯手工部署版) 终极避坑与实战指南

背景说明： OpenClaw（又名 ClawdBot）是一个极其强大的私人 AI 助手，具有持久记忆并能无缝接入 Telegram 等聊天软件。 官方推荐使用“源码编译 + CLI交互向导”进行部署，但这会污染宿主机环境。因此，我们选择了更硬核、更干净的 Docker 容器化 + 纯手工配置 路线。但由于跳过了向导，我们直面了其底层极其苛刻的校验机制和潜藏的代码 Bug。

本文记录了在 VPS（如 RackNerd）上使用 Docker 部署 OpenClaw 并接入 DeepSeek 模型时，遇到的所有“致命暗坑”及终极解法。

---

💡 TL;DR：先上终极完美配置代码

如果你不想看排错过程，只想一次性点火成功，请直接清空你现有的配置，使用以下这套经过无数次试错得出的“终极防御版配置”。

1. docker-compose.yml (纯净版)

核心原则：千万不要在这里写任何关于 OPENAI_BASE_URL 或 MODEL 的环境变量！全部交给 JSON 处理，避免双重注入冲突。

YAML

services:
  openclaw-core:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw_kernel
    restart: unless-stopped
    volumes:
      # 必须挂载当前目录到容器内，不要随意新建 data 文件夹
      - ./:/home/node/.openclaw
    environment:
      # --- 只保留 Telegram 机器人的 Token 和你的 ID ---
      - TELEGRAM_BOT_TOKEN=8688xxxx:xxxx你的真实Tokenxxxx
      - ALLOWED_USER_IDS=8408082812
      - LOG_LEVEL=info
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

2. openclaw.json (主脑自立门户版)

核心原则：绕过系统自带的 openai 驱动 Bug，强行自创一个名为 deepseek 的提供商，并指定基础通信协议。

JSON

{
  "models": {
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com",
        "apiKey": "sk-这里填入你真实有效的DeepSeek密钥",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "deepseek-chat"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": "deepseek/deepseek-chat"
    }
  },
  "gateway": {
    "auth": {
      "mode": "token"
    }
  }
}

3. 终极启动命令

在执行启动前，必须清理掉旧的记忆文件，否则它会固执地读取旧配置！

Bash

# 彻底停机并清除旧特工记忆
docker compose down
rm -rf agents/

# 重新点火并查看日志
docker compose up -d
docker compose logs -f openclaw-core

只要日志出现 [gateway] listening on ws://...，去 Telegram 发一句“你好”，你的私人管家就彻底活了！

---

🕵️‍♂️ 万字排坑记录：我们到底踩了哪些雷？

坑一：幽灵般的“顽固记忆” (Config overwrite)

• 现象：修改了 docker-compose.yml 里的环境变量，甚至改了 openclaw.json，但每次重启，日志里读取的模型名字依然是旧的（比如退回默认的 Claude）。

• 原理：OpenClaw 内部有一个强悍的状态保护机制。只要 agents/ 文件夹或旧的 openclaw.json 存在，它启动时就会优先读取“历史记忆”，直接覆盖并无视你新写的配置。

• 解法：每次做重大配置修改时，必须执行 rm -rf agents/ 和 rm -f openclaw.json，逼迫它重新认主。

坑二：极其变态的 JSON 质检员 (Config invalid)

• 现象：在 openclaw.json 里添加自定义模型白名单时，疯狂报错：Invalid input: expected string, received undefined 或 expected object, received string。

• 原理：如果你跳过向导手工写 JSON，它的底层校验器一板一眼到了发指的地步。模型列表不能只是一个字符串 ["deepseek-chat"]，必须是一个完整的对象，并且强制要求同时包含 id、name 以及 baseUrl，缺一不可。

• 解法：严格按照终极配置中的 models 数组格式，老老实实把 id 和 name 补齐。

坑三：URL 疯狂拼接导致的 404 (No Body)

• 现象：模型识别成功了，API Key 也没错，但发消息测试时，总是秒回 error=404 status code (no body)。

• 原理：这曾是我们卡得最久的地方。业界标准的 OpenAI 兼容地址通常是 https://api.deepseek.com/v1。但 OpenClaw 底层发请求时，是个“大聪明”，它会自动在你写的网址后面再补上一个 /v1/chat/completions。如果你在配置里写了带 /v1 的网址，它拼出来就会变成 .../v1/v1/chat...，DeepSeek 服务器一看这个畸形网址，直接拒收并返回 404。

• 解法：在自定义配置中，baseUrl 只能写到 https://api.deepseek.com，剩下的让它自己去补。

坑四：“假钥匙”与“被墙”的罗生门 (curl 核酸检测法)

• 现象：即使配置全对，依然 404。开始怀疑是不是 VPS（如 RackNerd）的 IP 被 DeepSeek 的 Cloudflare 防火墙给拦截了。

• 原理：在层层软件包裹下，你很难分清是“网络不通”、“代码写错”还是“密钥失效”。

• 解法：直接用原生 curl 绕过 OpenClaw 进行单行通信测试：

  Bash

  curl -X POST https://api.deepseek.com/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer sk-你的真实密钥" -d '{"model": "deepseek-chat", "messages": [{"role": "user", "content": "hi"}]}'
  

  通过这个测试，我们成功发现网络根本没被墙，而是原有的 API Key 本身已经失效（返回了 invalid_api_key）。换了新 Key，瞬间打通。

坑五 (终极大 Boss)：openai 驱动的底层私货 Bug

• 现象：网络通了，钥匙换了，网址也没双重 /v1 了，居然还是 404！

• 原理：这是 OpenClaw 当前版本最恶性的一个 Bug。当你在 JSON 的 providers 里命名提供商为 "openai" 时，系统会强行启用一套特殊的内部驱动。这个驱动会在请求里强行塞入一些特殊参数（如 store: false），甚至在某些情况下会引发二次 URL 乱拼接，导致国内大模型（如 DeepSeek）的网关无法解析。

• 终极降维解法（自立门户）： 不使用 "openai" 这个名字！在 JSON 中自定义一个名为 "deepseek" 的提供商，并且加上一行魔法指令："api": "openai-completions"。 这行代码的作用是告诉系统：“请用最基础、最干净的通信协议来对接这个叫 deepseek 的通道，不要给我加任何私货！” 正是这最后一次“降维打击”，彻底斩断了所有底层 Bug，迎来了最终的胜利。

---

致谢： 感谢在终端前无数次敲下 docker compose down 和 up -d 的不屈精神。手工驯服这只“龙虾”虽然痛苦，但也让我们彻底摸清了它的大脑构造。希望这篇指南能帮到每一位渴望拥有真正本地化私人 AI 助手的极客朋友们！