# 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（推荐）

```bash
# 主 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
```

### 手动配置示例

```bash
# 主实例
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 状态检查

```bash
openclaw --profile main status
openclaw --profile rescue status
openclaw --profile rescue browser status
```

---

## 二、多 Agent 部署

### 架构

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

### 配置示例

```json5
{
  "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 工具限制

```json5
{
  "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 │
   │  节点   │     │  节点   │     │  节点   │
   └─────────┘     └─────────┘     └─────────┘
```

### 节点配对

```bash
# 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
```

### 节点命令

#### 屏幕截图

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

#### 摄像头拍照

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

#### 屏幕录制

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

#### 位置信息

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

#### 系统命令（节点主机）

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

### 节点绑定 Exec

```bash
# 全局默认
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 隧道

#### 创建隧道

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

#### 隧道建立后的操作

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

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

### 远程 Gateway 配置

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

### Tailscale 访问

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

# 查看状态
openclaw gateway status
```

### 远程访问模式

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

---

## 五、协同部署清单

### 部署前检查

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

### 配置模板

#### 主 Gateway（主 Agent）

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

#### 救援 Gateway（隔离 Agent）

```json5
{
  "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 无法连接

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

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

#### 节点不响应

```bash
# 检查节点状态
openclaw nodes status

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

#### Agent 路由错误

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

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

#### 工具调用被拒绝

```bash
# 检查工具限制
openclaw sandbox explain

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

---

## 七、相关文档

- [CLI 命令参考](./CLI_COMMAND_REFERENCE.md)
- [Gateway 配置详解](./GATEWAY_CONFIGURATION.md)
- [故障排查指南](./TROUBLESHOOTING_GUIDE.md)
- [日志配置指南](./LOGGING_GUIDE.md)
- [系统架构](./SYSTEM.md)
- [多机部署](./MULTI-MACHINE.md)

---

*最后更新: 2026-02-04*