OpenClaw 纯 Docker 版终极部署防坑指南（甲骨文 ARM VPS）

适用：Oracle ARM VPS / Docker 环境
目标：OpenClaw 可用 + 外网 HTTP 可访问 + 自定义模型生效

---

一、核心避坑原则（先看这三条）

1. 绝不用 root 目录直接挂载
   容器内跑 node:1000，root 创建目录直接 EACCES。

2. 自定义模型必须写 openclaw.json
   环境变量不生效，别浪费时间。

3. HTTP 环境必须放行设备验证
   否则永远卡 1008 报错。

---

二、目录准备（权限是生死线）

sudo mkdir -p /opt/openclaw
cd /opt/openclaw

sudo mkdir -p ./config ./workspace
sudo chown -R 1000:1000 ./config ./workspace

✅ 验证要点：目录 owner 必须是 1000:1000

---

三、编写核心配置 openclaw.json

sudo nano ./config/openclaw.json

模板（替换 token / baseUrl / apiKey）：

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "你的自定义网页登录密码"
    },
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true,
      "allowInsecureAuth": true
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "custom_api": {
        "baseUrl": "http://你的中转API地址/v1",
        "apiKey": "sk-请填入你完整的真实API_Key",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-5.2-codex",
            "name": "GPT 5.2 Codex",
            "reasoning": false,
            "input": ["text"]
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "custom_api/gpt-5.2-codex"
      },
      "models": {
        "custom_api/gpt-5.2-codex": {
          "alias": "GPT 5.2 Codex"
        }
      },
      "workspace": "/home/node/.openclaw/workspace"
    }
  },
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": {
          "enabled": true
        }
      }
    }
  }
}

✅ 要点

• mode 必须是 local
• allowInsecureAuth 必须开
• baseUrl 要带 /v1

---

四、编写 Docker Compose

sudo nano /opt/openclaw/docker-compose.yml

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./config:/home/node/.openclaw
      - ./workspace:/home/node/.openclaw/workspace
    environment:
      - TZ=Asia/Shanghai
    command:
      ["node","dist/index.js","gateway","--bind","lan"]

  openclaw-cli:
    image: ghcr.io/openclaw/openclaw:latest
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/home/node/.openclaw
      - ./workspace:/home/node/.openclaw/workspace
    entrypoint: ["node", "dist/index.js"]

✅ 要点

• --bind lan 必须写，别写 0.0.0.0

---

五、启动 & 访问

sudo docker compose up -d

浏览器访问：

http://你的服务器IP:18789

输入 openclaw.json 里的 token → 登录成功。

---

六、常见问题与修复

1）改了 openclaw.json 不生效

sudo docker compose restart openclaw-gateway

2）改了 docker-compose.yml

sudo docker compose up -d --force-recreate openclaw-gateway

3）1008 设备验证报错

sudo docker compose exec openclaw-gateway node dist/index.js devices list
sudo docker compose exec openclaw-gateway node dist/index.js devices approve <requestId>

---

✅ 最终效果验证

• Web 控制台可进
• 自定义模型生效
• 外网 HTTP 能正常用，不会被设备验证卡死

---

需要的话我再补一节：反向代理 + HTTPS。