使用 Docker 部署 OpenClaw 2026 完整指南

前言

OpenClaw 是一个支持 Docker 自托管部署的 AI Agent 平台，支持通过 Telegram 等渠道与 Agent 交互，并提供 Cron Job 定时任务功能。

2 月曾部署过 2.13 版本，时隔一个多月，在社交媒体上重新引发了讨论。笔者没有专用的新机器用于部署，当前是在已有的无头 Linux 服务器上运行 OpenClaw，使用 Docker 部署的目的是将 OpenClaw 与宿主机环境隔离，避免对宿主机目录造成影响。

环境要求

Docker 及 Docker Compose
一个可用的 Telegram Bot Token
（可选）Traefik 反向代理
（可选）tinyauth 认证服务

目录结构

openclaw/
├── compose.yaml
├── config/
│   ├── openclaw.json
│   └── workspace/

Docker Compose 配置

官方提供了 Docker 镜像，可以直接使用 Docker Compose 来部署 OpenClaw。以下是一个基本的 compose.yaml 配置示例：

services:
  openclaw-gateway:
    image: ghcr.io/openclaw/openclaw:2026.3.12
    container_name: openclaw-gateway
    environment:
      HOME: /home/node
      NODE_ENV: production
      TERM: xterm-256color
      TZ: Asia/Tokyo
      OPENCLAW_GATEWAY_TOKEN: "your-token-here"
      GOG_KEYRING_PASSWORD: "your-keyring-password"
      PATH: /home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ./config:/home/node/.openclaw
      - ./config/workspace:/home/node/.openclaw/workspace
    ports:
      - 18789:18789
      - 18790:18790
    init: true
    restart: unless-stopped
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "lan",
        "--port",
        "18789",
        "--allow-unconfigured",
      ]

启动以及初始化

启动 OpenClaw Gateway 并进入容器：

docker compose up -d

docker exec -it openclaw-gateway bash

初始化配置：

node@133872bbe17a:/app$ openclaw setup --wizard # 交互式配置向导
node@133872bbe17a:/app$ openclaw dashboard --no-open # 打开浏览器访问 http://localhost:18790

配置 Traefik + tinyauth 反向代理

使用 tinyauth 认证（trusted-proxy 模式）

如果使用 tinyauth 作为认证层，可以将 Gateway 配置为 trusted-proxy 模式，避免每次访问 Web UI 都需要输入 Gateway Token。

前提条件：tinyauth 的 Traefik middleware 配置中需要包含 authResponseHeaders：

# Traefik 动态配置
http:
  routers:
    openclaw:
      rule: "Host(`openclaw.example.com`)"
      service: "openclaw"
      middlewares:
        - "tinyauth"

  services:
    openclaw:
      loadBalancer:
        servers:
          - url: "http://192.168.1.100:18789"
        passHostHeader: true

  middlewares:
    tinyauth:
      forwardAuth:
        address: "http://tinyauth:3200/api/auth/traefik"
        authResponseHeaders:
          - "remote-user"
        trustForwardHeader: true

openclaw.json 对应配置：

{
  "gateway": {
    "auth": {
      "mode": "trusted-proxy",
      "trustedProxy": {
        "userHeader": "remote-user",
        "requiredHeaders": ["x-forwarded-proto", "x-forwarded-host"]
      }
    }
  }
}

注意：tinyauth 认证成功后传递用户身份的 header 名称为 remote-user，不是 x-forwarded-user。

trustedProxies 配置说明

trustedProxies 用于指定哪些 IP 来源的请求可以被信任。建议只填入实际的代理 IP 网段：

网段	用途
`127.0.0.1`	本机 loopback
`192.168.0.0/16`	内网局域网

Cron Job 配置

我日常使用 OpenClaw 的场景是工作日早上 7 点自动获取山手線的运行状态，并发送到 Telegram 频道。以下是一个 Cron Job 的配置示例：

配置结构

{
  "version": 1,
  "jobs": [
    {
      "id": "your-uuid",
      "agentId": "main",
      "name": "job-name",
      "enabled": true,
      "createdAtMs": 1234567890000,
      "updatedAtMs": 1234567890000,
      "schedule": {
        "kind": "cron",
        "expr": "0 7 * * 1-5",
        "tz": "Asia/Tokyo"
      },
      "sessionTarget": "isolated",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "systemEvent",
        "event": "cron",
        "prompt": "任务描述"
      },
      "delivery": {
        "mode": "announce",
        "channel": "telegram",
        "to": "-123456789",
        "bestEffort": false
      }
    }
  ]
}

关键字段说明

sessionTarget：isolated 表示每次独立执行，不携带历史上下文；main 表示注入到主 Session 时间线
wakeMode：next-heartbeat 等待下一个心跳周期触发；now 立即触发
delivery.mode：announce 将结果发送到指定频道；none 仅内部执行不发送

Prompt 编写建议

定时任务的 Prompt 建议遵循以下原则：

明确指定数据来源（URL）
规定输出格式，减少 Agent 自由发挥的空间
禁止添加额外的问候或情感信息
使用占位符让 Agent 自动填入动态内容（如日期时间）

示例：

请访问以下链接，获取山手線的实时运行状态：

山手線
https://traininfo.jreast.co.jp/train_info/line.aspx?gid=1&lineid=yamanoteline

查看完成后，严格按以下格式发送报告，不要添加任何额外的问候、评论或情感信息：

---
電車運行情報（{月日} {現在時刻}）

・山手線：[平常通り / 遅延]
---

常见问题

trusted_proxy_user_missing

Gateway 未收到用户身份 header，检查 Traefik middleware 的 authResponseHeaders 是否包含 remote-user。此外还需确认 Traefik 静态配置的 forwardedHeaders.trustedIPs 包含了上游代理的 IP 网段，否则 Traefik 会丢弃来自不受信任来源的 forwarded header。

总结

OpenClaw 支持接入日常社交媒体和工作流程，但当前版本在 Web UI 交互体验和配置复杂度上仍有一些不完善之处，我自己也花了不少时间在调试和适应上。

目前我主要用它来处理一些明确、简单的定时任务，省去了手动编写查询脚本的麻烦。后续我可能会继续探索更多的集成方式。

作为开发者，我认为更值得投入的方向是 MCP 以及 Skills 的开发与集成，通过 OpenClaw 提供的接口来实现更复杂的自动化任务。

前言