435 lines
10 KiB
Markdown
435 lines
10 KiB
Markdown
# 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*
|