每日备份 2026-06-10 12:57:13
This commit is contained in:
root-backup committed
1 parent
fda2ccb8c2
commit
3d2e638c6a
244 files changed
+58890
-3
No files matched your search
@@ -0,0 +1,434 @@
|
||||
# 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*
|
||||
Reference in new issue
Block a user