我习惯用监控数据说话。本文是实打实的"生产手记"：从架构设计、systemd 部署、安全加固到监控告警，每一步都经过验证，直接 copy 就是一份可用的部署文档。

一、OpenClaw 是什么？

OpenClaw 是一个开源的自托管 AI Agent 多通道网关，用 Node.js 实现，能够将 WhatsApp、Telegram、Discord、iMessage 等主流 IM 与 AI 大模型连接起来，同时支持多 Agent 路由、工具调用、记忆系统和 Skills 技能扩展。

┌─────────────────────────────────────────────────────┐
│                    OpenClaw Gateway                  │
│                                                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌───────┐  │
│  │WhatsApp │  │Telegram │  │Discord  │  │iMessage│  │
│  └────┬────┘  └────┬────┘  └────┬────┘  └───┬───┘  │
│       └────────────┴────────────┴────────────┘      │
│                         │                            │
│              ┌──────────▼──────────┐                │
│              │   Routing & Session │                │
│              │       Engine        │                │
│              └──────────┬──────────┘                │
│                         │                            │
│         ┌───────────────┼───────────────┐          │
│         ▼               ▼               ▼          │
│   ┌──────────┐   ┌──────────┐   ┌──────────────┐  │
│   │ AI Agent │   │  Tools   │   │   Memory     │  │
│   │ (LLM)    │   │ (exec/   │   │  (workspace) │  │
│   │          │   │ browser) │   │              │  │
│   └──────────┘   └──────────┘   └──────────────┘  │
│                         │                            │
│              ┌──────────▼──────────┐                │
│              │  Control UI (Web)  │                │
│              │  CLI / RPC / Hooks │                │
│              └───────────────────┘                │
└─────────────────────────────────────────────────────┘

核心价值：

  • 一套进程同时接入多个聊天平台
  • 多 Agent 隔离会话，workspace 完全独立
  • 热加载配置，发布不停机
  • 支持 Docker / Systemd / Launchd 多形态部署
  • 企业级安全模型：DM 策略、Relay 跨网段推送、Exec 白名单

二、生产环境架构设计

2.1 推荐架构

                        ┌──────────────────┐
                        │   Tailscale VPN   │  （或公司专线）
                        └────────┬─────────┘
                                 │
           ┌─────────────────────┼─────────────────────┐
           │                     │                     │
    ┌──────▼──────┐       ┌──────▼──────┐       ┌──────▼──────┐
    │  Gateway    │       │  iOS/Android │       │  Desktop    │
    │  (Linux VPS)│◄──────│  Companion   │       │  Operator  │
    │  Port 18789 │       │  App (Node)  │       │  (CLI/UI)  │
    └──────┬──────┘       └──────────────┘       └─────────────┘
           │
    ┌──────▼──────┐
    │  Model      │
    │  Provider   │  (Anthropic / OpenAI / 自定义)
    └─────────────┘

推荐部署形态：

  • Linux Server：跑 Gateway 主力进程，systemd 守护
  • macOS：跑 Gateway + 桌面 App（Canvas 能力）
  • iOS/Android：作为 Node 接入，暴露 Camera / Canvas / SMS 等能力
  • Tailscale：Gateway 默认 loopback 绑定，通过 Tailscale VPN 实现远程访问

2.2 关键端口与绑定策略

设置项 优先级顺序 说明
Gateway Port --port > env > config > 18789 默认 18789
Bind Mode CLI > config > loopback 生产推荐 tailnet（Tailscale）或 0.0.0.0 + 防火墙
Auth Token gateway.auth.token / env 必须配置，否则拒绝非本地连接

三、安装与部署

3.1 快速安装

# macOS / Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows (PowerShell)
iwr -useb https://openclaw.ai/install.ps1 | iex

# 验证版本
openclaw --version

3.2 交互式初始化

openclaw onboard --install-daemon

向导会自动完成：

  1. 选择模型provider（Anthropic / OpenAI / Google等）
  2. 写入 API Key
  3. 生成 gateway auth token
  4. 配置第一个 Channel（Telegram 最简单，只需 bot token）
  5. 安装系统服务（systemd / launchd）

3.3 生产级 systemd 部署

# /etc/systemd/system/openclaw-gateway.service
[Unit]
Description=OpenClaw Gateway
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=on-failure
RestartSec=10s
Environment=NODE_ENV=production
Environment=OPENCLAW_CONFIG_PATH=/etc/openclaw/openclaw.json
EnvironmentFile=/etc/openclaw/env

# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/var/log/openclaw /var/lib/openclaw
PrivateTmp=true

# 日志
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw-gateway

[Install]
WantedBy=multi-user.target

# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway

# 查看状态
sudo systemctl status openclaw-gateway

3.4 Docker 部署（开发/测试推荐）

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    ports:
      - "18789:18789"
    volumes:
      - ./openclaw.json:/app/config/openclaw.json:ro
      - ./workspace:/app/workspace
      - ./state:/app/state
    environment:
      - OPENCLAW_GATEWAY_TOKEN=${GATEWAY_TOKEN}
      - NODE_ENV=production
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL

docker compose up -d
docker logs -f openclaw-gateway

四、核心配置详解

4.1 完整配置文件结构

// ~/.openclaw/openclaw.json
{
  // Gateway 服务配置
  gateway: {
    port: 18789,
    bind: "tailnet",          // loopback | tailnet | public
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
    reload: {
      mode: "hybrid",          // hot | restart | hybrid | off
      debounceMs: 300,
    },
    channelHealthCheckMinutes: 5,   // 健康检查间隔
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },

  // Agent 默认配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-4o"],
      },
      // 心跳任务（每小时检查服务健康）
      heartbeat: {
        every: "1h",
        target: "last",
      },
      // 沙箱隔离（非 main agent 跑在 Docker 里）
      sandbox: {
        mode: "non-main",
        scope: "agent",
      },
    },
    list: [
      {
        id: "main",
        description: "主 Agent，处理日常对话",
      },
      {
        id: "ops",
        description: "运维 Agent，执行部署和监控任务",
        workspace: "~/.openclaw/workspace-ops",
      },
    ],
  },

  // 多通道配置
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",    // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"],
    },
    whatsapp: {
      enabled: true,
      groups: {
        "*": { requireMention: true },
      },
    },
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
    },
  },

  // 会话管理
  session: {
    dmScope: "per-channel-peer",   // per-peer 推荐多用户场景
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
    threadBindings: {
      enabled: true,
      idleHours: 24,
    },
  },

  // 定时任务
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },

  // Webhook / Hooks
  hooks: {
    enabled: true,
    token: "${HOOKS_TOKEN}",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
  },

  // 技能（Skills）
  skills: {
    entries: {
      "code-deploy": { enabled: true },
      "healthcheck": { enabled: true },
      "api-test": { enabled: true },
    },
  },
}

4.2 多环境配置分离

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  // 引入环境特定配置
  $include: "./env/prod.json5",
}

// ~/.openclaw/env/prod.json5
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-6" },
      sandbox: { mode: "all" },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist" },
  },
}

五、运维核心操作

5.1 日常运维命令

# ===== 进程与健康 =====
openclaw gateway status              # 基本状态
openclaw gateway status --deep      # 深度检查（含 channel 状态）
openclaw gateway status --json      # JSON 输出（适合监控采集）
openclaw health                     # 健康探测

# ===== 日志 =====
openclaw logs --follow              # 实时日志（生产调试）
journalctl -u openclaw-gateway -f   # systemd 日志

# ===== 配置热重载 =====
openclaw gateway restart            # 强制重启
openclaw secrets reload             # 重新加载密钥

# ===== Channel 状态 =====
openclaw channels status --probe   # 探测所有 channel 连通性

# ===== 诊断 =====
openclaw doctor                     # 自动诊断 + 修复建议
openclaw doctor --fix               # 自动修复

# ===== 设备管理 =====
openclaw devices list               # 查看待配对设备
openclaw devices approve <requestId>
openclaw nodes status                # Node 在线状态

5.2 健康检查脚本（cron 每日巡检）

#!/bin/bash
# /opt/scripts/openclaw-health-check.sh
# 建议 crontab: 0 8 * * * /opt/scripts/openclaw-health-check.sh

GATEWAY_TOKEN="${OPENCLAW_GATEWAY_TOKEN}"
STATUS=$(openclaw gateway status --json 2>/dev/null)

if echo "$STATUS" | grep -q '"state":"running"'; then
    echo "[OK] Gateway running"
else
    echo "[ERROR] Gateway not healthy"
    # 告警通知（企业微信/钉钉/飞书）
    curl -s -X POST "https://qyapi.weixin.qq.com/cgi-bin/webhook/send" \
      -H "Content-Type: application/json" \
      -d '{"msgtype":"text","text":{"content":"[OpenClaw] Gateway 健康检查失败"}}'
fi

# 检查 channel 连通性
openclaw channels status --probe | grep -v "✓" && {
    echo "[WARN] Some channels unhealthy"
}

5.3 日志管理规范

# 日志轮转 - /etc/logrotate.d/openclaw
/var/log/openclaw/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        systemctl reload openclaw-gateway > /dev/null 2>&1 || true
    endscript
}

六、安全加固（生产必看）

6.1 访问控制矩阵

场景 推荐策略
Telegram DM dmPolicy: "pairing"（首次需配对码）
WhatsApp DM dmPolicy: "allowlist"（明确名单）
Discord 私聊 dmPolicy: "allowlist"
群组 requireMention: true（防止陌生人触发）
外部网络访问 Gateway 通过 Tailscale VPN，不暴露公网端口
Exec 工具 security: "allowlist" + 白名单路径

6.2 Exec 权限白名单

{
  tools: {
    exec: {
      host: "local",          // local | node
      security: "allowlist", // deny | allowlist | full
    },
  },
}

# 添加可执行命令白名单
openclaw approvals allowlist add --node build-node "/usr/local/bin/deploy.sh"
openclaw approvals allowlist add --node build-node "/usr/bin/docker"
openclaw approvals allowlist add --node build-node "/usr/bin/git"

6.3 密钥管理

不推荐在配置文件中明文写 token。推荐使用 SecretRef：

{
  channels: {
    telegram: {
      botToken: {
        source: "env",
        provider: "default",
        id: "OPENCLAW_TELEGRAM_BOT_TOKEN",
      },
    },
  },
}

通过 env 文件或系统环境变量注入：

# /etc/openclaw/env
OPENCLAW_GATEWAY_TOKEN=your-secure-random-token
OPENCLAW_TELEGRAM_BOT_TOKEN=your-telegram-token
OPENAI_API_KEY=sk-...

七、Skills 技能系统（可扩展性核心）

OpenClaw 的 Skills 是可插拔的任务模块，存放在 ~/.openclaw/skills/ 目录下，每个 Skill 包含一个 SKILL.md 定义能力描述。

7.1 内置运维常用技能

技能名 功能 触发场景
healthcheck 主机安全审计与风险配置 安全巡检
verify 代码改动实测验证 部署后验证
code-deploy 部署流水线 CI/CD
api-test API 接口实测 接口调试
loop 定时循环任务 监控/定时提醒
schedule-feishu 飞书日程管理 日程同步
memory 精准记忆系统 跨会话上下文

7.2 从 clawhub 安装新技能

# 搜索技能
openclaw skills search "monitor"

# 安装技能
clawhub install healthcheck

# 查看已安装技能
openclaw skills list

7.3 技能配置文件示例

// ~/.openclaw/skills/entries/healthcheck/config.json
{
  "enabled": true,
  "cron": "0 2 * * *",        // 每日凌晨 2 点巡检
  "reportTo": "feishu",       // 报告发送到飞书
  "checks": [
    "ssh-hardening",
    "firewall-status",
    "openclaw-version",
  ],
}

八、飞书（Feishu）接入实战

飞书是 OpenClaw 支持的重要通道之一，也是国内团队最常用的 IM。以下是完整接入步骤：

8.1 创建飞书应用

  1. 前往 飞书开放平台 创建企业自建应用
  2. 获取 App ID 和 App Secret
  3. 配置机器人能力（添加"机器人"应用功能）
  4. 配置权限： im:message, im:message.receive_v1, im:chat 等
  5. 发布应用并获取 Verification Token

8.2 飞书 Channel 配置

{
  channels: {
    feishu: {
      enabled: true,
      appId: "${FEISHU_APP_ID}",
      appSecret: "${FEISHU_APP_SECRET}",
      botName: "运维助手",
      dmPolicy: "pairing",
    },
  },
}

8.3 飞书机器人 Relay 架构

飞书群/私聊
    │
    ▼
飞书 Platform ──Webhook──► OpenClaw Gateway (hooks)
    ▲                         │
    │                         ▼
    └─────── 事件推送 ────── Agent 处理 ───► Tools/Memory

九、多租户与多 Agent 路由

9.1 场景：团队分工，每个 Bot 处理不同业务

{
  agents: {
    list: [
      { id: "mayun",    workspace: "~/.openclaw/workspace-mayun",    description: "市场经理" },
      { id: "liujq",   workspace: "~/.openclaw/workspace-liujq",   description: "技术总监" },
      { id: "liyanh",  workspace: "~/.openclaw/workspace-liyanh",  description: "后端开发" },
      { id: "zhouhy",  workspace: "~/.openclaw/workspace-zhouhy",  description: "测试" },
      { id: "wangj",   workspace: "~/.openclaw/workspace-wangj",   description: "运维" },
      { id: "mahuit",  workspace: "~/.openclaw/workspace-mahuit",  description: "产品经理" },
      { id: "mengyt",  workspace: "~/.openclaw/workspace-mengyt",  description: "秘书长" },
    ],
  },
  bindings: [
    // 不同 Channel + 用户 路由到不同 Agent
    { agentId: "wangj",  match: { channel: "feishu", senderId: "ou_xxx" } },
    { agentId: "liujq",  match: { channel: "feishu", senderId: "ou_yyy" } },
  ],
}

9.2 Relay 跨 Bot 消息转发

在 SOUL.md 中配置 @user_id 映射，实现 Bot 间协作：

// /root/.openclaw/feishu-relay-config.json
{
  "ou_c1f89b849b69ecc1cec7739e4ac0692f": "mayun",
  "ou_aa703b37ffacf109ce2ac4a9047cd7af": "liujq",
  "ou_be0185b0f51d83a8a": "liyanh",
  "ou_554d490b43bdae9174697007d34aaf13": "zhouhy",
  "ou_ef55d8424b50507445f82ae728f54b4a": "wangj"
}

十、故障排查手册

10.1 常见故障速查

症状 可能原因 解决命令
Gateway 无法启动 端口占用 / 配置文件格式错误 openclaw doctor --fix
refusing to bind ... without auth 非 loopback 绑定但未配置 token 配置 gateway.auth.token
EADDRINUSE 另一个 Gateway 实例已运行 pkill openclaw; openclaw gateway start
unauthorized Client 与 Gateway token 不匹配 检查 env 的 OPENCLAW_GATEWAY_TOKEN
Channel 连接失败 Token 过期或网络不通 openclaw channels status --probe
心跳任务未执行 Skill 未启用或 cron 未启动 openclaw cron list 检查任务状态

10.2 诊断命令链

# 完整诊断流程
openclaw doctor                    # 第一步：自动诊断
openclaw gateway status --deep     # 进程 + channel 健康
openclaw logs --follow             # 实时日志
openclaw health                    # 健康探测端点

# 端口与进程
ss -tlnp | grep 18789
ps aux | grep openclaw

# 网络连通性
nc -zv gateway-host 18789          # 端口可达性
curl -v ws://127.0.0.1:18789       # WebSocket 连通性

十一、监控指标采集

11.1 Prometheus 采集

# Gateway 提供 metrics 端点
curl http://127.0.0.1:18789/metrics

# 关键指标
# - openclaw_gateway_up{state="running"}
# - openclaw_channel_status{name="telegram"}
# - openclaw_sessions_active_total
# - openclaw_agent_runs_total{agent_id="main",status="ok"}

11.2 Grafana Dashboard

建议采集以下指标：

指标 说明 告警阈值
gateway_up Gateway 进程存活 = 0 时告警
channel_healthy 各 Channel 连通性 < 1 时告警
sessions_total 会话数量 突增/突降时关注
agent_run_duration_seconds Agent 执行耗时 p99 > 30s 时告警
cron_runs_total 定时任务执行次数 失败时告警

十二、升级与回滚

12.1 版本升级

# npm 全局更新
npm update -g openclaw

# 或使用官方脚本
curl -fsSL https://openclaw.ai/install.sh | bash

# 验证版本
openclaw --version

# 热重载（自动应用）
openclaw gateway restart

12.2 配置回滚

# 配置变更前手动备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

# 配置变更后验证
openclaw doctor

# 出问题后回滚
cp ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d) ~/.openclaw/openclaw.json
openclaw gateway restart

12.3 版本兼容性

OpenClaw 版本 最低 Node.js 推荐 Node.js
最新版 Node 22 LTS Node 24

总结：运维checklist

☐ Gateway 已注册为 systemd 服务并开机自启
☐ Auth Token 已配置，不允许匿名访问
☐ 所有 Channel 配置了 dmPolicy（不推荐 open）
☐ 群组已配置 requireMention: true
☐ Exec 白名单已配置，不允许随意 shell
☐ 日志轮转已配置，保留 14 天
☐ 每日健康检查 cron 已配置
☐ 飞书/Telegram 等 Channel 已验证连通性
☐ 配置文件已备份，版本受控
☐ 升级 SOP 已文档化，回滚步骤已演练

OpenClaw 非常适合作为企业级 AI 助手网关，既保证了数据主权（完全自托管），又兼顾了多通道接入和多人协作的运维需求。核心运维原则依然是：监控先行、变更受控、回滚有路。

原创不易，转载须注明出处。

# 运维 # 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

收藏必看｜2026 版大模型 Function Calling 详解，小白也能吃透 AI Agent 核心原理

avatar 龙虾开发者社区
cover

边缘部署 NanoClaw 的三大现实挑战：从内存水位到 SD 卡寿命

avatar 龙虾开发者社区
cover

DevClaw本地预检Agent：如何平衡代码格式化与CI流水线效率

avatar 龙虾开发者社区