my-project/doc/COORDINATION_DEPLOYMENT.md

OpenClaw 协同部署指南

概述

协同部署涉及以下层面：

1. 多 Gateway 部署 - 同一主机运行多个 Gateway 实例
2. 多 Agent 部署 - 单 Gateway 管理多个隔离 Agent
3. 节点（Nodes）管理 - 远程设备作为节点接入
4. 远程访问 - SSH 隧道、Tailscale 等

---

一、多 Gateway 部署

何时需要多 Gateway

• 需要更强的隔离（如救援 Bot）
• 需要冗余备份
• 不同实例需要不同配置

隔离要求

配置项	说明	必需
OPENCLAW_CONFIG_PATH	独立配置文件	✅
OPENCLAW_STATE_DIR	独立状态目录	✅
agents.defaults.workspace	独立工作目录	✅
gateway.port	独立端口	✅

使用 Profile（推荐）

# 主 Gateway
openclaw --profile main setup
openclaw --profile main gateway --port 18789
openclaw --profile main gateway install

# 救援 Gateway
openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19789
openclaw --profile rescue gateway install

手动配置示例

# 主实例
OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \
OPENCLAW_STATE_DIR=~/.openclaw-main \
openclaw gateway --port 18789

# 救援实例
OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \
OPENCLAW_STATE_DIR=~/.openclaw-rescue \
openclaw gateway --port 19789

端口映射（衍生端口）

基础端口 = gateway.port

服务	端口偏移
browser control	+2
canvas host	+4
CDP 端口范围	+9 ~ +108

多 Gateway 状态检查

openclaw --profile main status
openclaw --profile rescue status
openclaw --profile rescue browser status

---

二、多 Agent 部署

架构

┌─────────────────────────────────────────────────────────┐
│                    Gateway                              │
│  - 消息路由                                             │
│  - Agent 调度                                          │
└────────────────────────┬────────────────────────────────┘
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
   ┌─────────┐     ┌─────────┐     ┌─────────┐
   │ Agent 1 │     │ Agent 2 │     │ Agent 3 │
   │ 主助手   │     │ 家庭 Bot│     │ 工作 Bot│
   └─────────┘     └─────────┘     └─────────┘

配置示例

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "主助手",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "家庭 Bot",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit"]
        }
      },
      {
        "id": "work",
        "name": "工作 Bot",
        "workspace": "~/.openclaw/workspace-work"
      }
    ],
    "bindings": [
      { "agentId": "main", "match": { "channel": "telegram" } },
      { "agentId": "family", "match": { "channel": "whatsapp" } },
      { "agentId": "work", "match": { "channel": "discord" } }
    ]
  }
}

Agent 路由规则

匹配顺序：

1. match.peer（具体对话）
2. match.guildId / match.teamId
3. match.accountId（具体账号）
4. match.accountId: "*"（整个通道）
5. 默认 Agent

Agent 工具限制

{
  "agents": {
    "list": [
      {
        "id": "public",
        "tools": {
          "profile": "read-only",
          "allow": ["read", "message"],
          "deny": ["exec", "write", "browser"]
        }
      }
    ]
  }
}

工具组速查

组名	包含工具
group:runtime	exec, bash, process
group:fs	read, write, edit, apply_patch
group:sessions	sessions_list, sessions_history, sessions_send
group:memory	memory_search, memory_get
group:ui	browser, canvas
group:messaging	message

---

三、节点（Nodes）管理

节点概念

节点是连接到 Gateway 的辅助设备（macOS/iOS/Android/无头主机），提供：

• 屏幕截图（Canvas）
• 摄像头拍照/录像
• 位置信息
• 系统命令执行
• 通知推送

节点架构

┌─────────────────────────────────────────────────────────┐
│                      Gateway                            │
│  - 接收消息                                             │
│  - 运行 Agent                                           │
│  - 路由工具调用                                         │
└────────────────────────┬────────────────────────────────┘
                         │ WebSocket
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
   ┌─────────┐     ┌─────────┐     ┌─────────┐
   │  Mac    │     │  iPhone │     │ Android │
   │  节点   │     │  节点   │     │  节点   │
   └─────────┘     └─────────┘     └─────────┘

节点配对

# 1. 在节点设备上启动
openclaw node run --host <gateway-host> --port 18789 --display-name "Mac Node"

# 2. 在 Gateway 主机上审批
openclaw nodes pending
openclaw nodes approve <requestId>

# 3. 查看节点状态
openclaw nodes status
openclaw nodes list

节点命令

屏幕截图

openclaw nodes canvas snapshot --node <id> --format png
openclaw nodes canvas snapshot --node <id> --format jpg --max-width 1200

摄像头拍照

openclaw nodes camera list --node <id>
openclaw nodes camera snap --node <id>
openclaw nodes camera snap --node <id> --facing front

屏幕录制

openclaw nodes screen record --node <id> --duration 10s --fps 10

位置信息

openclaw nodes location get --node <id>
openclaw nodes location get --node <id> --accuracy precise

系统命令（节点主机）

openclaw nodes run --node <id> -- echo "Hello"
openclaw nodes notify --node <id> --title "Title" --body "Message"

节点绑定 Exec

# 全局默认
openclaw config set tools.exec.host node
openclaw config set tools.exec.node "<node-id>"

# Agent 级别
openclaw config set agents.list[0].tools.exec.node "<node-id>"

---

四、远程访问

SSH 隧道

创建隧道

# 本地 18789 -> 远程 127.0.0.1:18789
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

隧道建立后的操作

# 查看远程 Gateway 状态
openclaw health
openclaw status --deep

# 发送消息
openclaw message send --target +15555550123 --message "Hi"

远程 Gateway 配置

{
  "gateway": {
    "mode": "remote",
    "remote": {
      "url": "ws://127.0.0.1:18789",
      "token": "your-token"
    }
  }
}

Tailscale 访问

# 推荐：保持 loopback 绑定 + Tailscale Serve
openclaw gateway --tailscale serve

# 查看状态
openclaw gateway status

远程访问模式

模式	说明	适用场景
SSH 隧道	通用方案	临时访问
Tailscale	内网穿透	长期使用
VPN	专用网络	企业环境

---

五、协同部署清单

部署前检查

• 确定 Gateway 数量和角色
• 确定 Agent 数量和用途
• 规划端口分配（间隔至少 20 端口）
• 配置网络访问（SSH/Tailscale）
• 准备各实例的认证信息

配置模板

主 Gateway（主 Agent）

{
  "gateway": { "port": 18789, "mode": "local", "bind": "loopback" },
  "agents": {
    "list": [{ "id": "main", "default": true, "workspace": "~/.openclaw/workspace" }],
    "bindings": [{ "agentId": "main", "match": { "channel": "telegram" } }]
  }
}

救援 Gateway（隔离 Agent）

{
  "gateway": { "port": 19789, "mode": "local", "bind": "loopback" },
  "agents": {
    "list": [{ "id": "rescue", "workspace": "~/.openclaw/workspace-rescue" }],
    "bindings": [{ "agentId": "rescue", "match": { "channel": "telegram" } }]
  }
}

运维命令速查

任务	命令
查看所有 Gateway	openclaw --profile <name> status
查看节点	openclaw nodes status
查看 Agent	openclaw agents list --bindings
重启 Gateway	openclaw gateway restart
SSH 隧道	ssh -N -L 18789:127.0.0.1:18789 user@host

---

六、故障排查

常见问题

Gateway 无法连接

# 检查本地隧道
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 检查远程 Gateway
ssh user@host "openclaw gateway status"

节点不响应

# 检查节点状态
openclaw nodes status

# 检查节点连接日志
openclaw logs | grep -i node

Agent 路由错误

# 查看绑定配置
openclaw agents list --bindings

# 检查消息路由
openclaw logs | grep -i routing

工具调用被拒绝

# 检查工具限制
openclaw sandbox explain

# 检查 Agent 工具配置
openclaw config get agents.list

---

七、相关文档

• CLI 命令参考
• Gateway 配置详解
• 故障排查指南
• 日志配置指南
• 系统架构
• 多机部署

---

最后更新: 2026-02-04