docs: Gateway 搭建指南 + 配置红线 + A2A 三方通信架构
- 新增 Gateway 本地搭建指南（Windows/macOS/Linux） - 新增 Gateway 配置安全红线（血泪教训） - 更新 A2A 文档：三方互通架构（NEKO/KUMA/Home PC） - 推荐方案：本地 Gateway + A2A，不改现有 Gateway 配置
This commit is contained in:
NEKO 小队
parent
c4fee2fbf1
commit
0583245977
@ -1,6 +1,6 @@
|
|||||||
# 🔗 A2A 跨队通信配置指南
|
# 🔗 A2A 跨队通信配置指南
|
||||||
|
|
||||||
> 使用 A2A (Agent-to-Agent) 协议实现 KUMA ↔ NEKO 小队的 Agent 互联互通
|
> 使用 A2A (Agent-to-Agent) 协议实现多小队 Agent 互联互通（NEKO / KUMA / Home PC）
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -26,18 +26,36 @@ A2A (Agent-to-Agent) 是 Google 提出的开放协议，用于不同 AI Agent
|
|||||||
|
|
||||||
## 架构概览
|
## 架构概览
|
||||||
|
|
||||||
|
### 三方互通（当前架构）
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
subgraph "NEKO (neko-vm, 7×24)"
|
||||||
|
N_A2A[A2A :18800]
|
||||||
|
N_XJ[小橘 🍊]
|
||||||
|
end
|
||||||
|
subgraph "KUMA (kuma-vm, 7×24)"
|
||||||
|
K_A2A[A2A :18800]
|
||||||
|
K_XM[小墨 🖊️]
|
||||||
|
end
|
||||||
|
subgraph "Home PC (本地, 重活)"
|
||||||
|
H_A2A[A2A :18800]
|
||||||
|
H_AG[Agent]
|
||||||
|
end
|
||||||
|
N_A2A <-->|Bearer Token| K_A2A
|
||||||
|
N_A2A <-->|Bearer Token| H_A2A
|
||||||
|
K_A2A <-->|Bearer Token| H_A2A
|
||||||
```
|
```
|
||||||
┌─────────────────┐ A2A Protocol ┌─────────────────┐
|
|
||||||
│ KUMA 小队 VM │ ◄──── JSON-RPC/REST ────► │ NEKO 小队 VM │
|
每个 Gateway 独立运行，各自管理自己的 agents，通过 A2A 协议通信。这样任何一方重启/故障都不影响其他方。
|
||||||
│ │ │ │
|
|
||||||
│ ┌────────────┐ │ Agent Card Discovery │ ┌────────────┐ │
|
### 分工
|
||||||
│ │ A2A Gateway│──┼──────────────────────────────┼──│ A2A Gateway│ │
|
|
||||||
│ │ :18800 │ │ │ │ :18800 │ │
|
| 节点 | 角色 | 特点 |
|
||||||
│ └────────────┘ │ Bearer Token Auth │ └────────────┘ │
|
|------|------|------|
|
||||||
│ │ │ │
|
| NEKO (neko-vm) | 7×24 值班、飞书/Telegram 响应 | 轻量任务 |
|
||||||
│ 小墨 / 绿豆 ... │ │ Agent们 ... │
|
| KUMA (kuma-vm) | 7×24 值班、LiteLLM Proxy | 统一 LLM 入口 |
|
||||||
└─────────────────┘ └─────────────────┘
|
| Home PC | 重活：全栈开发、本地 AI 模型推理 | 高配硬件 |
|
||||||
```
|
|
||||||
|
|
||||||
## 插件安装
|
## 插件安装
|
||||||
|
|
||||||
|
|||||||
134
docs/shared/gateway-safety.md
Normal file
134
docs/shared/gateway-safety.md
Normal file
@ -0,0 +1,134 @@
|
|||||||
|
# 🚨 Gateway 配置安全红线
|
||||||
|
|
||||||
|
> 用血泪教训换来的经验，请务必遵守
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 背景
|
||||||
|
|
||||||
|
2026-03-26，NEKO 小队在尝试配置 Remote Node（Home PC 通过公网连接 neko-vm Gateway）时，**三次搞挂 Gateway**，每次都需要 KUMA 小队的小墨 🖊️ SSH 过来手动修复。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⛔ 绝对不能碰的配置
|
||||||
|
|
||||||
|
| 配置项 | 说明 | 为什么危险 |
|
||||||
|
|--------|------|------------|
|
||||||
|
| `gateway.bind` | 监听地址 | 改成 `lan` 后如果 TLS 没配好，Gateway 可能暴露在公网上不安全；改错直接断连 |
|
||||||
|
| `gateway.tls` | TLS 证书配置 | 字段名、路径、权限任何一个不对，Gateway 就启动失败 |
|
||||||
|
| `gateway.port` | 端口号 | systemd service 里硬编码端口会覆盖 config，两边不一致就挂 |
|
||||||
|
| systemd service 参数 | `--port` 等 | 和 config 打架，导致不可预测的行为 |
|
||||||
|
|
||||||
|
!!! danger "三次教训"
|
||||||
|
1. **第一次**：端口改 8443 + TLS 字段名写错 → Gateway 挂
|
||||||
|
2. **第二次**：修复 TLS 后 approval 配置连锁问题 → 被锁在门外
|
||||||
|
3. **第三次**：再次尝试 TLS → Gateway 挂，exec 权限也被重置
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 为什么 Remote Node 方案有风险
|
||||||
|
|
||||||
|
### 问题链
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph TD
|
||||||
|
A[想让 Home PC 连 Gateway] --> B[需要 bind: lan]
|
||||||
|
B --> C[公网暴露需要 TLS]
|
||||||
|
C --> D[配 TLS 容易搞挂 Gateway]
|
||||||
|
D --> E[Gateway 挂了 = 所有连接断开]
|
||||||
|
E --> F[包括自己的 agent session]
|
||||||
|
F --> G[无法自救，需要外部救援]
|
||||||
|
```
|
||||||
|
|
||||||
|
### 核心矛盾
|
||||||
|
|
||||||
|
- Gateway 配置变更需要重启
|
||||||
|
- 重启会断开**所有**连接（包括 agent 自己）
|
||||||
|
- 如果配置有误，Gateway 起不来 → 彻底失联
|
||||||
|
- 飞书通道不支持 exec approval → 被锁死
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ✅ 推荐方案：本地 Gateway + A2A
|
||||||
|
|
||||||
|
不改现有 Gateway 配置，在 Home PC 上跑独立的本地 Gateway，通过 A2A 通信：
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
subgraph "各自独立，互不影响"
|
||||||
|
N[NEKO Gateway<br/>neko-vm] <-->|A2A| K[KUMA Gateway<br/>kuma-vm]
|
||||||
|
N <-->|A2A| H[Home Gateway<br/>Home PC]
|
||||||
|
K <-->|A2A| H
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
### 优势
|
||||||
|
|
||||||
|
| 对比项 | Remote Node | 本地 Gateway + A2A |
|
||||||
|
|--------|-------------|-------------------|
|
||||||
|
| 需要改 Gateway 配置 | ✅ 需要 | ❌ 不需要 |
|
||||||
|
| 公网暴露 | ✅ 需要 TLS | ❌ 本地运行 |
|
||||||
|
| 挂了影响范围 | 全部断连 | 只影响自己 |
|
||||||
|
| 自救能力 | 无（被锁门外） | 有（本地操作） |
|
||||||
|
| 配置复杂度 | 高（bind+TLS+port+approval） | 低（标准安装） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 安全检查清单
|
||||||
|
|
||||||
|
如果你**确实需要**修改 Gateway 配置（比如换 provider），请：
|
||||||
|
|
||||||
|
- [ ] 备份 `openclaw.json`：`cp openclaw.json openclaw.json.bak`
|
||||||
|
- [ ] 确保有另一种方式访问服务器（SSH）
|
||||||
|
- [ ] 确保有人能帮你手动恢复（不要单独操作）
|
||||||
|
- [ ] 修改后先 `openclaw gateway status` 检查
|
||||||
|
- [ ] **绝对不要碰** bind / tls / port
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 急救手册
|
||||||
|
|
||||||
|
如果 Gateway 挂了：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. SSH 到服务器
|
||||||
|
ssh azureuser@<ip>
|
||||||
|
|
||||||
|
# 2. 查看状态
|
||||||
|
systemctl --user status openclaw-gateway
|
||||||
|
|
||||||
|
# 3. 恢复备份配置
|
||||||
|
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
|
||||||
|
|
||||||
|
# 4. 重启
|
||||||
|
systemctl --user restart openclaw-gateway
|
||||||
|
|
||||||
|
# 5. 验证
|
||||||
|
systemctl --user status openclaw-gateway
|
||||||
|
openclaw status
|
||||||
|
```
|
||||||
|
|
||||||
|
如果没有备份，最小可用配置：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"gateway": {
|
||||||
|
"port": 18789,
|
||||||
|
"bind": "loopback"
|
||||||
|
},
|
||||||
|
"tools": {
|
||||||
|
"exec": {
|
||||||
|
"host": "gateway",
|
||||||
|
"security": "full"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 致谢
|
||||||
|
|
||||||
|
感谢小墨 🖊️ 三次紧急救援 🙏
|
||||||
|
|
||||||
|
> "不要试图通过修改 Gateway 配置来解决远程连接问题" — 2026-03-26 的血泪教训
|
||||||
299
docs/shared/gateway-setup.md
Normal file
299
docs/shared/gateway-setup.md
Normal file
@ -0,0 +1,299 @@
|
|||||||
|
# 🦞 OpenClaw Gateway 本地搭建指南
|
||||||
|
|
||||||
|
> 在 Windows/macOS/Linux 上搭建本地 OpenClaw Gateway，组建本地小队
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
OpenClaw Gateway 是小队的核心运行环境。每个 Gateway 独立运行，管理自己的 agents，通过 A2A 协议与其他小队互通。
|
||||||
|
|
||||||
|
### 架构
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
subgraph "Home PC (本地)"
|
||||||
|
GW_HOME[Gateway :18789]
|
||||||
|
A1[Agent 1]
|
||||||
|
A2[Agent 2]
|
||||||
|
GW_HOME --- A1
|
||||||
|
GW_HOME --- A2
|
||||||
|
end
|
||||||
|
subgraph "NEKO (neko-vm)"
|
||||||
|
GW_NEKO[Gateway :18789]
|
||||||
|
XJ[小橘 🍊]
|
||||||
|
GW_NEKO --- XJ
|
||||||
|
end
|
||||||
|
subgraph "KUMA (kuma-vm)"
|
||||||
|
GW_KUMA[Gateway :18789]
|
||||||
|
XM[小墨 🖊️]
|
||||||
|
GW_KUMA --- XM
|
||||||
|
end
|
||||||
|
GW_HOME <-->|A2A| GW_NEKO
|
||||||
|
GW_HOME <-->|A2A| GW_KUMA
|
||||||
|
GW_NEKO <-->|A2A| GW_KUMA
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 安装 OpenClaw
|
||||||
|
|
||||||
|
### 前提条件
|
||||||
|
|
||||||
|
- **Node.js** v20+ （推荐通过 [nvm-windows](https://github.com/coreybutler/nvm-windows) 或 [nvm](https://github.com/nvm-sh/nvm) 安装）
|
||||||
|
- **Git**（用于版本管理）
|
||||||
|
|
||||||
|
### 安装
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install -g openclaw
|
||||||
|
```
|
||||||
|
|
||||||
|
验证安装：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openclaw --version
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 初始化 Gateway
|
||||||
|
|
||||||
|
首次运行会自动创建配置文件 `~/.openclaw/openclaw.json`：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openclaw gateway start
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! tip "Windows 路径"
|
||||||
|
Windows 上配置文件位于 `C:\Users\<用户名>\.openclaw\openclaw.json`
|
||||||
|
|
||||||
|
### 默认配置
|
||||||
|
|
||||||
|
| 配置项 | 默认值 | 说明 |
|
||||||
|
|--------|--------|------|
|
||||||
|
| `gateway.port` | 18789 | Gateway 端口 |
|
||||||
|
| `gateway.bind` | loopback | 监听地址（127.0.0.1） |
|
||||||
|
| `gateway.tls` | 无 | TLS 配置 |
|
||||||
|
| `tools.exec.security` | allowlist | 命令执行安全策略 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 配置 LLM Provider
|
||||||
|
|
||||||
|
Gateway 需要至少一个 LLM provider 才能运行 agent。
|
||||||
|
|
||||||
|
### 方式 A：直接配置 API Key
|
||||||
|
|
||||||
|
编辑 `~/.openclaw/openclaw.json`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"providers": {
|
||||||
|
"copilot-api": {
|
||||||
|
"type": "copilot",
|
||||||
|
"apiKey": "your-api-key"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 方式 B：通过 LiteLLM Proxy（推荐团队方案）
|
||||||
|
|
||||||
|
如果团队有统一的 LiteLLM Gateway，可以指向它：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"providers": {
|
||||||
|
"litellm": {
|
||||||
|
"type": "openai",
|
||||||
|
"baseUrl": "http://<litellm-host>:4000/v1",
|
||||||
|
"apiKey": "your-litellm-key"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"agents": {
|
||||||
|
"defaults": {
|
||||||
|
"model": "litellm/<model-name>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! info "LiteLLM 的好处"
|
||||||
|
- 统一管理多个 LLM provider 的 API Key
|
||||||
|
- 支持 load balancing 和 fallback
|
||||||
|
- 团队共享一套配置，单点管理
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 创建 Agent
|
||||||
|
|
||||||
|
### 配置 agent
|
||||||
|
|
||||||
|
在 `openclaw.json` 中添加 agents：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agents": {
|
||||||
|
"defaults": {
|
||||||
|
"model": "copilot-api/claude-sonnet-4"
|
||||||
|
},
|
||||||
|
"list": [
|
||||||
|
{
|
||||||
|
"id": "main",
|
||||||
|
"name": "主 Agent",
|
||||||
|
"description": "协调者"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "coder",
|
||||||
|
"name": "代码工程",
|
||||||
|
"description": "代码工程师"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Agent 工作目录
|
||||||
|
|
||||||
|
每个 agent 有独立的工作目录：
|
||||||
|
|
||||||
|
```
|
||||||
|
~/.openclaw/
|
||||||
|
├── workspace/ # 共享工作区
|
||||||
|
│ ├── AGENTS.md # 行为规范
|
||||||
|
│ ├── SOUL.md # 身份人格
|
||||||
|
│ ├── USER.md # 用户信息
|
||||||
|
│ ├── TOOLS.md # 工具备忘
|
||||||
|
│ └── memory/ # 记忆目录
|
||||||
|
├── agents/
|
||||||
|
│ ├── main/ # 主 agent 目录
|
||||||
|
│ └── coder/ # 代码 agent 目录
|
||||||
|
└── openclaw.json # Gateway 配置
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 配置 Exec 安全策略
|
||||||
|
|
||||||
|
### 安全级别
|
||||||
|
|
||||||
|
| 级别 | 说明 | 推荐场景 |
|
||||||
|
|------|------|----------|
|
||||||
|
| `deny` | 禁止所有命令执行 | 不需要执行命令 |
|
||||||
|
| `allowlist` | 只允许白名单命令 | 生产环境 |
|
||||||
|
| `full` | 允许所有命令 | 开发环境/受信本地 |
|
||||||
|
|
||||||
|
### 设置
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openclaw config set tools.exec.security full
|
||||||
|
```
|
||||||
|
|
||||||
|
### Exec Approvals 文件
|
||||||
|
|
||||||
|
`~/.openclaw/exec-approvals.json`：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": 1,
|
||||||
|
"defaults": {
|
||||||
|
"security": "full"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! warning "安全提示"
|
||||||
|
`security: full` 仅建议在受信的本地开发环境使用。
|
||||||
|
远程/公网 Gateway 请使用 `allowlist` 模式。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. 配置消息通道（可选）
|
||||||
|
|
||||||
|
### 飞书
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"messages": {
|
||||||
|
"feishu": {
|
||||||
|
"enabled": true,
|
||||||
|
"appId": "<App ID>",
|
||||||
|
"appSecret": "<App Secret>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Telegram
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"messages": {
|
||||||
|
"telegram": {
|
||||||
|
"enabled": true,
|
||||||
|
"botToken": "<Bot Token>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. 常用命令
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Gateway 管理
|
||||||
|
openclaw gateway start # 启动
|
||||||
|
openclaw gateway stop # 停止
|
||||||
|
openclaw gateway restart # 重启
|
||||||
|
openclaw gateway status # 状态
|
||||||
|
|
||||||
|
# Agent 管理
|
||||||
|
openclaw status # 总览
|
||||||
|
openclaw agents list # 列出 agents
|
||||||
|
openclaw config set <key> <val> # 修改配置
|
||||||
|
|
||||||
|
# 日志
|
||||||
|
openclaw logs --follow # 实时日志
|
||||||
|
|
||||||
|
# 服务安装（开机自启）
|
||||||
|
openclaw gateway install # 安装为系统服务
|
||||||
|
openclaw gateway uninstall # 卸载服务
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Windows 特别注意
|
||||||
|
|
||||||
|
### PowerShell 环境变量
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# 设置环境变量（当前 session）
|
||||||
|
$env:VARIABLE_NAME = "value"
|
||||||
|
|
||||||
|
# 永久设置
|
||||||
|
[System.Environment]::SetEnvironmentVariable("VARIABLE_NAME", "value", "User")
|
||||||
|
```
|
||||||
|
|
||||||
|
### 路径问题
|
||||||
|
|
||||||
|
- Windows 配置路径：`C:\Users\<用户名>\.openclaw\`
|
||||||
|
- PowerShell 中用 `$env:USERPROFILE` 代替 `~`
|
||||||
|
- JSON 中路径用正斜杠 `/` 或双反斜杠 `\\`
|
||||||
|
|
||||||
|
### 服务安装
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# 以管理员权限运行
|
||||||
|
openclaw gateway install
|
||||||
|
```
|
||||||
|
|
||||||
|
这会创建 Windows 计划任务（Task Scheduler），开机自动启动 Gateway。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 下一步
|
||||||
|
|
||||||
|
- 配置 [A2A 跨队通信](a2a-setup.md) 连接其他小队
|
||||||
|
- 参考 [Gateway 配置红线](gateway-safety.md) 避免踩坑
|
||||||
@ -85,9 +85,11 @@ nav:
|
|||||||
- 概览: kuma/index.md
|
- 概览: kuma/index.md
|
||||||
- 共享知识:
|
- 共享知识:
|
||||||
- 概览: shared/index.md
|
- 概览: shared/index.md
|
||||||
|
- Gateway 本地搭建: shared/gateway-setup.md
|
||||||
|
- Gateway 配置红线: shared/gateway-safety.md
|
||||||
|
- A2A 跨队通信: shared/a2a-setup.md
|
||||||
- 语音转文字配置: shared/speech-to-text.md
|
- 语音转文字配置: shared/speech-to-text.md
|
||||||
- SiliconFlow 图片生成: shared/siliconflow-image-gen.md
|
- SiliconFlow 图片生成: shared/siliconflow-image-gen.md
|
||||||
- A2A 跨队通信: shared/a2a-setup.md
|
|
||||||
- Memex 知识管理: shared/memex-knowledge-base.md
|
- Memex 知识管理: shared/memex-knowledge-base.md
|
||||||
- TTS 语音功能: shared/tts-guide.md
|
- TTS 语音功能: shared/tts-guide.md
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user