Agents
添加自定义 Agent
用自定义命令、参数和环境变量接入兼容的 Agent 运行时。
当 SoniBot 没有自动识别某个兼容 CLI，或你需要为同一运行时维护一套独立启动配置时，可以添加自定义 Agent。
前置条件
- 目标 CLI 已安装，并能在系统终端中正常启动；
- 目标运行时与 SoniBot 当前支持的 ACP 接入方式兼容；
- 你知道它的启动命令、必要参数与认证方式；
- 需要使用的账号或 API Key 已准备好。
创建方式
进入“设置 → Agents → 添加自定义 Agent”，可以选择：
- 通过对话添加：让 SoniBot 管家协助检查本机命令并生成配置；
- 手动添加：直接填写配置，适合已知完整启动参数的用户。
字段说明
| 字段 | 说明 | 建议 |
|---|---|---|
| 名称 | 在 Agent 和助手选择器中显示的名称 | 写清服务商或用途 |
| 命令 | 实际启动的可执行文件 | 优先使用绝对路径 |
| 参数 | 启动时传给命令的参数列表 | 每项独立填写，避免拼成 Shell 字符串 |
| 环境变量 | 只传给该运行时的键值 | 密钥不要写入普通参数 |
| 图标 | 列表中的识别标记 | 使用稳定、可访问的资源 |
| 高级配置 | 运行时提供的附加选项 | 不确定时保留默认值 |
保存后回到 Agent 列表，点击“测试连接”。只有测试成功，才建议将它设为助手的主 Agent。
维护自定义 Agent
- 停用：保留配置，但不再作为新的可用运行时；
- 编辑：修改命令、参数、环境变量或展示信息；
- 删除：移除 Agent 配置。删除前检查是否仍被助手引用；
- 重新启用：修复命令或认证后，重新开启并测试连接。
安全建议
自定义命令会在运行 SoniBot 的机器上启动。不要粘贴来源不明的命令，不要使用包含
sudo、远程脚本下载或不受控 Shell 展开的启动方式。
- API Key 仅放在专用环境变量中；
- 为 Agent 选择尽可能窄的项目目录；
- 首次运行保留逐次授权，不要直接开启自动允许；
- 升级 CLI 后重新测试连接；
- 团队使用前，先用普通会话验证文件、模型与权限行为。
如果测试失败，先参阅检测、配置与测试 Agent中的诊断清单。