本文将从运维视角出发，系统讲解 OpenClaw 的架构设计、生产部署、监控告警、安全加固与多通道接入，适合企业级落地参考。
一、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 / Linuxcurl-fsSLhttps://openclaw.ai/install.sh|bash# Windows (PowerShell)iwr-usebhttps://openclaw.ai/install.ps1|iex# 验证版本openclaw--version3.2 交互式初始化
openclaw onboard --install-daemon向导会自动完成：
- 选择模型provider（Anthropic / OpenAI / Google等）
- 写入 API Key
- 生成 gateway auth token
- 配置第一个 Channel（Telegram 最简单，只需 bot token）
- 安装系统服务（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# 启用并启动sudosystemctl daemon-reloadsudosystemctlenable--nowopenclaw-gateway# 查看状态sudosystemctl status openclaw-gateway3.4 Docker 部署（开发/测试推荐）
# docker-compose.ymlversion:'3.8'services:openclaw:image:ghcr.io/openclaw/openclaw:latestcontainer_name:openclaw-gatewayports:-"18789:18789"volumes:-./openclaw.json:/app/config/openclaw.json:ro-./workspace:/app/workspace-./state:/app/stateenvironment:-OPENCLAW_GATEWAY_TOKEN=${GATEWAY_TOKEN}-NODE_ENV=productionrestart:unless-stoppedsecurity_opt:-no-new-privileges:truecap_drop:-ALLdockercompose up-ddockerlogs-fopenclaw-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-uopenclaw-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.shGATEWAY_TOKEN="${OPENCLAW_GATEWAY_TOKEN}"STATUS=$(openclaw gateway status--json2>/dev/null)ifecho"$STATUS"|grep-q'"state":"running"';thenecho"[OK] Gateway running"elseecho"[ERROR] Gateway not healthy"# 告警通知（企业微信/钉钉/飞书）curl-s-XPOST"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 rotate14compress delaycompress missingok notifempty postrotate systemctl reload openclaw-gateway>/dev/null2>&1||trueendscript}六、安全加固（生产必看）
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 allowlistadd--nodebuild-node"/usr/local/bin/deploy.sh"openclaw approvals allowlistadd--nodebuild-node"/usr/bin/docker"openclaw approvals allowlistadd--nodebuild-node"/usr/bin/git"6.3 密钥管理
不推荐在配置文件中明文写 token。推荐使用 SecretRef：
{ channels: { telegram: { botToken: { source: "env", provider: "default", id: "OPENCLAW_TELEGRAM_BOT_TOKEN", }, }, }, }通过 env 文件或系统环境变量注入：
# /etc/openclaw/envOPENCLAW_GATEWAY_TOKEN=your-secure-random-tokenOPENCLAW_TELEGRAM_BOT_TOKEN=your-telegram-tokenOPENAI_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"# 安装技能clawhubinstallhealthcheck# 查看已安装技能openclaw skills list7.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 创建飞书应用
- 前往 飞书开放平台 创建企业自建应用
- 获取
App ID和App Secret - 配置机器人能力（添加"机器人"应用功能）
- 配置权限：
im:message,im:message.receive_v1,im:chat等 - 发布应用并获取
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|grep18789psaux|grepopenclaw# 网络连通性nc-zvgateway-host18789# 端口可达性curl-vws://127.0.0.1:18789# WebSocket 连通性十一、监控指标采集
11.1 Prometheus 采集
# Gateway 提供 metrics 端点curlhttp://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 全局更新npmupdate-gopenclaw# 或使用官方脚本curl-fsSLhttps://openclaw.ai/install.sh|bash# 验证版本openclaw--version# 热重载（自动应用）openclaw gateway restart12.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 restart12.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 助手网关，既保证了数据主权（完全自托管），又兼顾了多通道接入和多人协作的运维需求。核心运维原则依然是：监控先行、变更受控、回滚有路。
原创不易，转载须注明出处。
