openclaw

OpenClaw - 可自托管的 AI 网关

将 OpenClaw（coollabsio/openclaw）部署并管理为容器化的 AI 网关。 在消息平台与多个 LLM 提供商之间路由对话，支持完整的工具使用、会话隔离和浏览器自动化。

已通过生产环境测试：KASM 1.17.0（Ubuntu 22.04）上的 OpenClaw v2026.1.x 源代码：https://github.com/coollabsio/openclaw

---

步骤 0：查阅正确的参考文档

任务	参考文档
全新 Docker 部署	references/installation.md
KASM 工作区设置	references/kasm-workspace.md
环境变量和配置	references/configuration.md
消息渠道（Telegram、Discord 等）	references/channels.md
安全加固	references/security.md
错误排查	references/troubleshooting.md
浏览器 sidecar 和自动化	references/browser-automation.md

---

关键规则

1. 务必设置 OPENCLAW_GATEWAY_BIND=loopback - 默认绑定会将网关暴露在公网上的 18789 端口。这是已知的严重安全问题（2026 年 2 月）。
2. 绝不要省略 AUTH_PASSWORD - nginx 基本身份验证是第一道防御层。
3. 挂载卷之前，将目录所有权设为 uid 1000 - 容器以非 root 用户 node 运行。
4. API 密钥只能通过环境变量配置 - 绝不要将提供商密钥放入 JSON 配置文件。
5. WhatsApp 使用完全覆盖模式 - 设置 WHATSAPP_ENABLED=true 时，整个 WhatsApp 配置块会被替换（而不是合并）。
6. 环境变量优先级最高 - 三层合并：JSON < 持久化状态 < 环境变量。
7. 在 KASM 上：每个 OpenClaw 工作区至少分配 4GB RAM，并为 /data 卷配置持久化配置文件。

---

快速参考

架构

[Messaging Channels] → [OpenClaw Gateway :18789] → [LLM Providers]
       ↑                        ↑                         ↑
  WhatsApp, Telegram    nginx reverse proxy :8080    Anthropic, OpenAI
  Discord, Slack        HTTP Basic Auth              Gemini, Groq, etc.
  Google Chat, Signal   Webhook routing

默认端口

端口	服务	绑定
8080	nginx 反向代理（外部）	可通过 PORT 配置
18789	OpenClaw 网关（内部）	必须绑定到 loopback
9223	Chrome CDP（浏览器 sidecar）	仅限内部

支持的 AI 提供商

Anthropic、OpenAI、Google Gemini、xAI Grok、Groq、Mistral、Cerebras、 Venice、Moonshot、Kimi、MiniMax、AWS Bedrock、Ollama（本地）、GitHub Copilot

支持的渠道

WhatsApp（Baileys）、Telegram（grammY）、Discord（discord.js）、Slack（Bolt）、 Google Chat、Signal、iMessage/BlueBubbles、Microsoft Teams、Matrix、Zalo

---

系统要求

独立 Docker 部署

资源	最低要求	推荐配置
RAM	2 GB	4 GB+
磁盘	10 GB	20 GB+
Docker	Engine + Compose v2	最新稳定版
架构	amd64 或 arm64	均可

KASM 工作区

资源	值
核心数	2
内存	4096 MB
Docker 镜像	coollabsio/openclaw:latest
持久化配置文件	/data 必需
GPU	不需要

必需配置

OpenClaw 至少需要：

1. 一个 AI 提供商 API 密钥（例如 ANTHROPIC_API_KEY）
2. 用于 nginx 基本身份验证的 AUTH_PASSWORD
3. 出于安全考虑设置 OPENCLAW_GATEWAY_BIND=loopback

---

最简部署

docker run -d --name openclaw \
  -p 8080:8080 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e AUTH_PASSWORD=changeme \
  -e OPENCLAW_GATEWAY_BIND=loopback \
  -e OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32) \
  -v openclaw-data:/data \
  coollabsio/openclaw:latest

访问控制面板：http://localhost:8080/

---

健康检查

# Container health
docker inspect --format='{{.State.Health.Status}}' openclaw

# Gateway health
docker exec openclaw node dist/index.js health \
  --token "$OPENCLAW_GATEWAY_TOKEN"

# Diagnostic scan
docker exec openclaw openclaw doctor --fix

# Full status
docker exec openclaw openclaw status --all

# Logs
docker logs -f openclaw

---

Docker Compose（含浏览器的完整配置）

services:
  openclaw-gateway:
    image: coollabsio/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - AUTH_USERNAME=admin
      - AUTH_PASSWORD=${AUTH_PASSWORD}
      - OPENCLAW_GATEWAY_BIND=loopback
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - BROWSER_CDP_URL=http://browser:9223
    volumes:
      - openclaw-data:/data
    depends_on:
      - browser

  browser:
    image: coollabsio/openclaw-browser:latest
    container_name: openclaw-browser
    restart: unless-stopped
    shm_size: 2gb
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - browser-data:/config

volumes:
  openclaw-data:
  browser-data:

---

此技能可避免的错误

#	错误	根本原因	预防措施
1	网关暴露在互联网中	默认绑定到 0.0.0.0	始终设置 OPENCLAW_GATEWAY_BIND=loopback
2	“1008 token mismatch”	过时的环境变量覆盖配置	使用 --no-cache 重新构建，并验证环境变量
3	EACCES 权限被拒绝	非 root 容器（uid 1000）	对挂载目录运行 chown -R 1000:1000
4	“context_length_exceeded” 误报	Token 计数不正确	清除会话，减少历史记录限制
5	忽略 WhatsApp 配置	完全覆盖模式	启用 WhatsApp 时设置所有 WhatsApp 变量
6	配置文件中包含 API 密钥	密钥泄露到日志或备份中	仅使用环境变量
7	无法在运行时安装软件包	非 root 容器	在构建时使用 OPENCLAW_DOCKER_APT_PACKAGES
8	浏览器自动化失败	未捆绑 Chromium	使用浏览器 sidecar 容器