Remote Agent Guide Chinese

🌐 远程 Agent 配置教程

本教程详细介绍如何在 AionUi 中配置和使用远程 Agent —— 通过 WebSocket 连接远端 AI Agent 服务，无需在本地安装任何 CLI 工具。

English | 简体中文

🎯 远程 Agent 概览

远程 Agent 功能允许你将 AionUi 连接到运行在其他机器（服务器、云实例、办公室电脑等）上的 AI Agent 服务。与需要本地安装 CLI 工具的多 Agent 模式不同，远程 Agent 通过网络连接 —— 无需本地安装。

核心特性

• 零本地安装 — 直接连接远程 Agent 服务，无需安装 CLI 工具
• 安全连接 — Ed25519 设备身份 + Bearer Token 认证
• 设备配对 — OpenClaw Gateway 的配对审批机制，确保安全的设备注册
• 完整 Agent 能力 — 文本对话、思考展示、工具调用、权限管理
• 会话持久化 — 支持断线后恢复会话
• 多实例支持 — 同时连接多个不同服务器上的远程 Agent

远程 Agent vs 多 Agent 模式 vs 内置 Agent

特性	内置 Agent	多 Agent 模式 (ACP)	远程 Agent
安装要求	AionUi 内置	需要本地安装 CLI 工具	无需本地安装
连接方式	本地	本地进程 (stdin/stdout)	网络 WebSocket
适用场景	日常使用	专业用户使用 CLI 工具	访问远程服务器上的 Agent
通信协议	内部	ACP（Agent Client Protocol）	OpenClaw Gateway Protocol
配置难度	无	中等	简单

支持的协议

协议	状态	说明
OpenClaw Gateway	✅ 已支持	基于 WebSocket，完整 Agent 能力
ZeroClaw	🚧 规划中	后续版本支持
ACP over Network	🚧 规划中	后续版本支持

💡 提示：目前仅支持 OpenClaw Gateway 协议。你需要一台远程机器运行 OpenClaw Gateway 服务端才能连接。

---

🚀 前置条件

配置远程 Agent 之前，请确保：

1. AionUi 已安装并运行（v1.x 或更高版本，需支持远程 Agent 功能）
2. 远程 OpenClaw Gateway 已在另一台机器上运行，且可通过网络访问
3. 连接信息：
   • Gateway WebSocket 地址（如 wss://your-server.example.com:18789）
   • 认证 Token（如 Gateway 要求）

📖 部署 OpenClaw Gateway：请参考 OpenClaw 文档 了解如何部署 Gateway 服务端。

---

⚙️ 第一步：打开远程 Agent 设置

1. 打开 AionUi
2. 点击侧栏的 设置 图标（齿轮图标）
3. 导航到 Agents 标签页
4. 点击顶部的 远端 Agents 标签

你将看到远程 Agent 管理面板。如果尚未配置任何远程 Agent，会显示空状态并提示连接第一个 Agent。

---

➕ 第二步：添加远程 Agent

1. 点击 「添加」 按钮（或首次使用时点击 「连接第一个 Agent」）
2. 填写配置表单：

配置字段

字段	必填	说明
名称	是	自定义名称（如"办公室服务器 Agent"）
头像	否	点击 emoji 选择自定义头像（默认：🤖）
URL	是	远程 Gateway 的 WebSocket 地址（如 wss://server.example.com:18789）
认证方式	是	选择 无 或 Bearer Token
Token	认证=Bearer 时	Gateway 管理员提供的认证 Token
描述	否	可选的备注信息
允许不安全连接	否	启用后跳过 TLS 证书验证（用于自签名证书）

URL 格式

• 推荐格式：wss://hostname:port（安全 WebSocket）
• 也接受：ws://hostname:port（非安全 WebSocket）
• 如果输入的 URL 没有协议前缀，会自动补全 wss://

测试连接

保存之前，可以点击 「测试连接」 验证 WebSocket 地址是否可达：

• ✅ 连接成功 — URL 可达且 WebSocket 握手成功
• ❌ 连接失败 — 请检查 URL、网络连接和防火墙规则

⚠️ 注意：「测试连接」仅检查网络连通性，不会执行完整的认证或设备配对。完整握手在保存时进行。

---

🔐 第三步：设备配对（OpenClaw 握手）

点击 「保存」 后，AionUi 会执行完整的 OpenClaw Gateway 握手。这是一个安全流程，包括：

1. 生成设备身份 — AionUi 自动为此远程 Agent 生成唯一的 Ed25519 密钥对（安全存储在本地数据库中，与本地 OpenClaw 安装完全隔离）
2. 挑战-响应认证 — Gateway 发送挑战，AionUi 用设备私钥签名回应
3. Token 验证 — 如已配置，Bearer Token 也会一并发送进行认证

三种可能的结果

✅ 成功（自动批准）

如果 Gateway 自动批准设备：

• 状态变为 已连接（绿色标记）
• 设备令牌已签发并保存，供后续连接使用
• 弹窗自动关闭
• 可以开始对话了！

⏳ 等待审批

如果 Gateway 要求管理员手动批准新设备：

• 弹窗显示 「等待网关审批...」 加载动画
• 开始倒计时（最长 5 分钟）
• AionUi 每 5 秒轮询 Gateway

需要做的：

1. 前往远程服务器上的 OpenClaw Gateway 管理界面
2. 批准等待中的设备配对请求
3. 批准后，AionUi 自动检测并完成连接

如果 5 分钟超时：

• 弹窗显示 「审批请求已过期」
• 配置仍然保存，状态为 pending（待审批）
• 可以之后通过编辑 Agent 重新触发握手

❌ 错误

如果连接或认证失败：

• 显示错误详情
• 配置保存，状态为 error
• 请检查 URL、Token 和网络连接后重试

---

💬 第四步：开始对话

远程 Agent 连接成功后：

1. 进入 首页 / 欢迎页
2. 在可用 Agent 列表中可以看到远程 Agent（显示自定义名称和头像）
3. 选择远程 Agent
4. 输入消息，开始对话！

对话功能

功能	支持状态
文本消息	✅
流式响应	✅
思考 / 推理展示	✅
工具调用	✅
权限审批请求	✅
文件附件（消息中）	✅
断线后恢复会话	✅

💡 提示：远程 Agent 对话的使用体验与本地 Agent 对话完全一致。你可以同时与同一个远程 Agent 进行多个对话 —— 每个对话拥有独立的会话。

---

✏️ 管理远程 Agent

编辑远程 Agent

1. 进入 设置 > Agents > 远端 Agents
2. 点击 Agent 卡片上的 编辑（铅笔）图标
3. 修改配置后点击 保存
4. 如果修改了 URL 或 Token，会重新执行握手

删除远程 Agent

1. 进入 设置 > Agents > 远端 Agents
2. 点击 Agent 卡片上的 删除（减号）图标
3. 确认删除

⚠️ 注意：删除远程 Agent 不会删除已有的对话。这些对话将变为不可用状态（无法发送新消息）。

状态标记

每个远程 Agent 卡片显示状态标记：

状态	标记颜色	含义
已连接	🟢 绿色	配对成功，可以使用
待审批	🟠 橙色	等待 Gateway 管理员审批
错误	🔴 红色	连接或认证失败
未知	⚪ 灰色	尚未测试

---

🔧 高级配置

允许不安全连接（自签名证书）

如果远程 Gateway 使用自签名 TLS 证书：

1. 编辑远程 Agent 配置
2. 启用 「允许不安全连接」
3. 保存配置

⚠️ 安全警告：这会跳过 TLS 证书验证。仅用于使用自签名证书的内部可信服务器。不要在公网连接中启用此选项。

设备身份

每个远程 Agent 配置拥有独立的 Ed25519 设备身份：

• 自动生成 — 创建远程 Agent 时自动生成
• 存储在本地数据库 — 加密存储
• 完全独立 — 与本地 OpenClaw CLI 安装（~/.openclaw/identity/）无关
• 不共享 — 不同远程 Agent 配置之间不共享

这意味着：

• 添加远程 Agent 不会影响你的本地 OpenClaw 配置
• 每个远程 Agent 在 Gateway 上有唯一的设备指纹
• 删除远程 Agent 会从本地数据库中移除其设备身份

---

❓ 常见问题

Q: 什么是 OpenClaw Gateway？

A: OpenClaw Gateway 是一个基于 WebSocket 的服务，将 AI Agent 能力暴露到网络上。它处理认证、会话管理和消息路由。可以理解为 AI Agent 的"远程访问服务器"。

Q: 我需要在本地安装 OpenClaw 吗？

A: 不需要。 远程 Agent 直接连接到远程 Gateway 服务器。你不需要任何本地 CLI 安装。设备身份完全由 AionUi 生成和管理。

Q: 可以连接多个远程 Agent 吗？

A: 可以。 你可以添加任意数量的远程 Agent 配置，每个指向不同的 Gateway 服务器（甚至同一服务器使用不同凭据）。

Q: 远程服务器掉线怎么办？

A: 对话会显示断线状态。当服务器恢复后，你可以继续对话 —— AionUi 保存了会话密钥，会尝试恢复之前的会话。

Q: 认证 Token 存储安全吗？

A: 安全。 所有认证 Token 和设备私钥在存储到本地 SQLite 数据库之前都经过加密处理。

Q: 「测试连接」和保存时的握手有什么区别？

A:

• 测试连接：轻量级检查，仅验证 WebSocket 地址是否可达（打开并关闭连接），不执行认证。
• 保存（握手）：执行完整的 OpenClaw 认证协议，包括设备身份验证、Token 认证和设备配对。

---

🔧 故障排除

连接失败

1. 检查 URL 格式 — 确保是有效的 WebSocket 地址（如 wss://hostname:port）
2. 检查网络连通性 — 能否从你的机器访问该服务器？试试 ping hostname
3. 检查防火墙规则 — 确保 Gateway 端口已开放且可访问
4. 检查 Gateway 是否运行 — 验证远程服务器上的 OpenClaw Gateway 进程是否活跃

认证失败

1. 检查 Bearer Token — 确保 Token 与 Gateway 的配置一致
2. 检查 Token 过期 — 某些 Token 可能会过期，请向 Gateway 管理员获取新的
3. 尝试无认证 — 如果 Gateway 允许无认证访问，将认证类型设为「无」

配对审批一直未完成

1. 检查 Gateway 管理界面 — 查看是否有待审批的设备配对请求
2. 确认 Gateway 的审批模式 — 某些 Gateway 自动批准，其他需要手动批准
3. 注意 5 分钟时间窗口 — 审批请求 5 分钟后过期。如已过期，重新编辑并保存 Agent 可触发新的握手

TLS 证书错误

1. 自签名证书 — 在 Agent 设置中启用「允许不安全连接」
2. 证书过期 — 请 Gateway 管理员续签 TLS 证书
3. 主机名不匹配 — 确保 URL 中的主机名与证书的 CN/SAN 匹配

---

📚 相关文档

• 快速入门: 快速入门
• 多 Agent 模式: 多 Agent 模式配置
• WebUI 远程访问: WebUI 配置
• 常见问题: 常见问题

---

需要帮助？

• 🐛 报告问题
• 💬 社区讨论
• 📖 完整文档

远程 Agent 让你随时随地访问强大的 AI Agent 能力 —— 无需本地安装！