diff --git a/docs/shared/a2a-setup.md b/docs/shared/a2a-setup.md index e62c64f..274b4bf 100644 --- a/docs/shared/a2a-setup.md +++ b/docs/shared/a2a-setup.md @@ -1,6 +1,6 @@ # 🔗 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 │ -│ │ │ │ -│ ┌────────────┐ │ Agent Card Discovery │ ┌────────────┐ │ -│ │ A2A Gateway│──┼──────────────────────────────┼──│ A2A Gateway│ │ -│ │ :18800 │ │ │ │ :18800 │ │ -│ └────────────┘ │ Bearer Token Auth │ └────────────┘ │ -│ │ │ │ -│ 小墨 / 绿豆 ... │ │ Agent们 ... │ -└─────────────────┘ └─────────────────┘ -``` + +每个 Gateway 独立运行，各自管理自己的 agents，通过 A2A 协议通信。这样任何一方重启/故障都不影响其他方。 + +### 分工 + +| 节点 | 角色 | 特点 | +|------|------|------| +| NEKO (neko-vm) | 7×24 值班、飞书/Telegram 响应 | 轻量任务 | +| KUMA (kuma-vm) | 7×24 值班、LiteLLM Proxy | 统一 LLM 入口 | +| Home PC | 重活：全栈开发、本地 AI 模型推理 | 高配硬件 | ## 插件安装 diff --git a/docs/shared/gateway-safety.md b/docs/shared/gateway-safety.md new file mode 100644 index 0000000..f3c8c78 --- /dev/null +++ b/docs/shared/gateway-safety.md @@ -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
neko-vm] <-->|A2A| K[KUMA Gateway
kuma-vm] + N <-->|A2A| H[Home Gateway
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@ + +# 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 的血泪教训 diff --git a/docs/shared/gateway-setup.md b/docs/shared/gateway-setup.md new file mode 100644 index 0000000..3da5d29 --- /dev/null +++ b/docs/shared/gateway-setup.md @@ -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://:4000/v1", + "apiKey": "your-litellm-key" + } + }, + "agents": { + "defaults": { + "model": "litellm/" + } + } +} +``` + +!!! 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": "", + "appSecret": "" + } + } +} +``` + +### Telegram + +```json +{ + "messages": { + "telegram": { + "enabled": true, + "botToken": "" + } + } +} +``` + +--- + +## 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 # 修改配置 + +# 日志 +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) 避免踩坑 diff --git a/mkdocs.yml b/mkdocs.yml index 06a21da..08a80b1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -85,9 +85,11 @@ nav: - 概览: kuma/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 - SiliconFlow 图片生成: shared/siliconflow-image-gen.md - - A2A 跨队通信: shared/a2a-setup.md - Memex 知识管理: shared/memex-knowledge-base.md - TTS 语音功能: shared/tts-guide.md