Agents
读完你能：分清助手与 Agent 各管什么，会检测本机 CLI、测试连接，并用修复页自己解决启动问题。
1. 助手负责包装，Agent 负责干活
Section titled “1. 助手负责包装，Agent 负责干活”一句话定位：助手是面向任务的配置，Agent 是真正跑对话的引擎。
- 助手把名称、头像、规则、默认配置包装成一个「岗位」，让你一键切换场景
- Agent 决定对话背后用哪个 AI 引擎，以及它支持哪些模型和权限档位
- 一个 Agent 可以同时被多个助手复用；助手换了 Agent，能力范围跟着换
入口：设置 → 「AI 核心」→ Agents
页面开头写明了规则：管理本机可用的 AI 编程 Agent。Aion CLI 为内置，App 自带、无需安装；其它 Agent 需先在本地安装对应 CLI 才能被识别。旁边有「查看安装指南」链接。
2. 认识 Agent 列表
Section titled “2. 认识 Agent 列表”列表第一行固定是内置的 Aion CLI，开箱即用、无需安装。往下是本机检测到的其它 CLI Agent，常见的包括：
| Agent | 说明 |
|---|---|
| Claude Code | Anthropic 的编程 Agent，需先安装其 CLI |
| Codex | OpenAI 的编程 Agent，需先安装其 CLI |
| Gemini CLI | Google 的命令行 Agent，需先安装其 CLI |
| Qwen Code | 通义千问的命令行 Agent，需先安装其 CLI |
| Kimi CLI | Kimi 的命令行 Agent，需先安装其 CLI |
| Goose | 开源命令行 Agent，需先安装其 CLI |
| …… | 其它支持 ACP 协议的 CLI 装好即可能被识别，以应用内实际检测为准 |
每行右侧有两个按钮：测试连接 和 编辑。名字旁边的彩色标签是当前状态：
| 状态标签 | 含义 | 下一步 |
|---|---|---|
| 可用 | 命令能找到、连接正常 | 直接给助手选用 |
| 需登录 | 能连上，但还没登录或缺密钥 | 在 CLI 里登录，或在修复页补环境变量 |
| 不可用 | 命令能找到，但连接失败 | 打开修复页看错误原因 |
| 未安装 | 默认路径找不到这个命令 | 先安装该 CLI，或进修复页指定启动路径 |
| 未检测 | 还没测过 | 点一次「测试连接」 |
顶部可按 全部 / 可用 / 不可用 筛选，搜索框可按名称过滤（「搜索 Agent…」）。
3. 测试连接与修复页
Section titled “3. 测试连接与修复页”点「测试连接」后稍等片刻，结果用提示气泡告知：连接成功的提示为：“XX”连接成功。；未安装、需登录、连接失败也各有对应提示。
点 Agent 行（或「编辑」）进入该 Agent 的修复页：
| 区块 | 怎么用 |
|---|---|
| 状态卡 | 按当前状态给建议：已连接（提示”在线”只代表可连接，不代表已登录）、连接失败（照错误信息调整下方配置）、未检测到（若已安装，在下方指定完整启动路径）、尚未检测（点右上角「测试连接」） |
| 启动路径 | 默认路径找不到命令时，手动填完整路径；填错可点「恢复默认」 |
| 环境变量 | 每行一个变量。页面列出了它擅长解决的三类问题：缺 API 密钥（如 ANTHROPIC_API_KEY）、自定义 API 地址（如 ANTHROPIC_BASE_URL）、网络代理（如 HTTPS_PROXY） |
| 保存并测试 | 改完路径或环境变量后点它，立即重测 |
修复页底部还有「绑定此 Agent 的助手」列表，点任一助手可跳去它的详情页调整绑定。
常见失败原因与提示语对照：
| 现象 | 先检查 |
|---|---|
| 命令找不到 | CLI 装了吗？按提示安装后重新测试连接 |
| 启动但初始化失败 | 先在终端打开一次该 CLI，完成登录或首次设置 |
| 可连接但需登录 | 在 CLI 里登录，或在「环境变量」中补 API 密钥 |
| 尚未配置模型供应商 | 到 设置 → 模型 添加并启用一个供应商 |
| 运行组件缺失 | 按提示修复或重新安装对应组件（见下） |
4. 运行环境自动托管
Section titled “4. 运行环境自动托管”部分 Agent 依赖的运行组件（如「托管 Node 运行环境」）由应用自动准备：首次使用时后台自动下载并校验，你只需等待。若准备失败或组件损坏，Agent 状态会给出修复提示，按提示重新打开应用或重装即可；提示组件缺失时，按「请修复或重新安装对应组件，然后重新测试连接」处理。
5. 添加自定义 Agent
Section titled “5. 添加自定义 Agent”右上角「添加自定义 Agent」按钮支持「通过对话添加」（让管家引导）或「手动添加」。手动添加是一个表单：
| 字段 | 填什么 |
|---|---|
| 显示名称 | Agent 选择器里显示的名字 |
| 头像 | 可「上传图片」 |
| 命令 | 运行该 Agent CLI 的可执行命令，例如 my-agent 或完整路径 |
| 参数 | 传给命令的参数，例如 --acp --verbose |
| 环境变量 | 按变量名 / 值逐行添加，点「添加变量」增行 |
填完先点「测试连接」，出现「连接成功！CLI 存在且 ACP 协议正常工作。」再保存。需要微调高级选项时，展开「高级 (JSON)」区块直接编辑 JSON。
6. 当前版本的两个说明
Section titled “6. 当前版本的两个说明”- 旧版本的「远程 Agent」连接入口（如 OpenClaw Gateway）在本版本设置页中已不再提供；若确有远程使用需求，可用 WebUI 远程访问本机
- Agent 市场（安装、更新、卸载更多 Agent）即将上线，当前版本暂未开放
- 能说出助手与 Agent 的分工，并从 设置 → 「AI 核心」→ Agents 打开列表
- 列表里有内置的 Aion CLI，且你安装过的 CLI 出现在列表中并完成了一次「测试连接」
- 能按状态标签（可用 / 需登录 / 不可用 / 未安装 / 未检测）判断下一步动作
- 用修复页补一次启动路径或环境变量后，「保存并测试」得到连接成功