公开 Agent 接入指南
把你的 Agent 接到 01OS:通过标准 Bot API 频道出站连接,支持 Mac、Android 与 01 Watch 同步交互。
你可以直接把本文档 URL(https://01os.ai/connect/)发送给你的 AI 助理。它可以通过阅读本文档自动获取环境准备、安装命令、配对握手与服务管理指引。
1. 核心架构与权责边界
01OS 是一个三方 Agent 驾驶舱。用户可以在 Mac 与 Android 上与接入的 Agent 对话,并在 01 Watch 智能手表上按住侧键说话、切换 Agent 与点头确认审批。
| 系统层面 | 归属环境 | 权责与安全边界 |
|---|---|---|
| Agent 模型与工具 | 第三方环境(本地 / VM) | 所有大模型 API Key、本地工具调用权限、Prompt 模板、执行记忆完全留在 Agent 自身运行环境,01OS 不接管、不托管这些敏感凭据。 |
| 连接通道 (Bot API) | 01OS 云端网关 (HTTPS) | Agent 主动出站长轮询(getUpdates)拉取用户指令,并通过 sendMessage 发送回复。不需要公网暴露端口或公网 IP。 |
| 点头审批责任 | 用户与 Agent 之间 | 用户在 01OS App 或 01 Watch 上点头批准原生决策卡,等同于在 Agent 处直接确认。01OS 从不替用户做决定。 |
| 语音与转写 | 01 Watch + 01OS 网关 | 手表端按住侧键进行语音输入,由云端转写为文字后路由给对应的 Agent;01OS 首版不做 TTS(文字转语音),Agent 回复文字与图片附件。 |
2. Hermes Agent 接入
如果你的 Agent 基于 Hermes 架构,可以通过官方 hermes-oneos 频道插件连接。
2.1 环境要求
- Hermes Agent >= 0.22.0
- Python >= 3.10
- Python 依赖:
aiohttp(用于异步 HTTP 通信)
2.2 安装插件
在你的 Hermes 环境中运行插件安装命令:
hermes plugins install https://github.com/Ericwong5021/01-home-os.git#plugins/hermes-oneos
2.3 配对绑定
运行网关向导并选择 01OS:
hermes gateway setup
- 终端将打印 6 位配对码与 ASCII 二维码。
- 打开 01OS App(Mac 桌面端或 Android 手机端),进入「Agent」页面,点击「输入配对码」或扫描二维码。
- App 确认后,插件自动获取
bot_token与agent_id,并安全保存在~/.hermes/oneos/{agent_id}.json(权限 0600)。
2.4 启动与运行
hermes gateway run
插件将自动长轮询 01OS 网关,接收用户指令并流式输出回复。首次配对生成的 instance_id 会持久化保存,即使未来断开重新配对,对话历史与手表配置也将完整保留。
3. Muse VM 服务接入
对于在 Linux VM 中运行的 Muse Agent,01OS 提供专用的 Linux VM IO 客户端程序(01os-muse),支持长轮询消息收发、官方 Hook 唤醒与原子状态流转。
3.1 一键安装脚本
在你的 Muse VM(Ubuntu / Debian)中执行以下安装命令:
curl -fsSL https://01os.ai/connect/install-muse.sh | bash
该脚本会自动检测系统架构(x86_64 / arm64),从 GitHub Releases 下载对应的版本化服务包,校验 SHA-256,解压至 ~/01os-muse 并设置安全权限(0700 目录,0600 凭据)。
3.2 真实产物下载与校验(GitHub Releases)
你也可以直接从 GitHub Releases 手动下载编译好的服务程序:
| 系统架构 | 发布包下载 (01OS 官方源) | GitHub Release 镜像 | 格式 |
|---|---|---|---|
| Linux x86_64 (amd64) | 01os-muse-v0.2.0-linux-amd64.tar.gz | Release v0.2.0 | 静态 ELF 64-bit 独立二进制 |
| Linux aarch64 (arm64) | 01os-muse-v0.2.0-linux-arm64.tar.gz | Release v0.2.0 | 静态 ELF 64-bit 独立二进制 |
| 通用 Python 脚本包 | 01os-muse-v0.2.0-universal.tar.gz | Release v0.2.0 | 跨平台可执行脚本 |
| 校验哈希表 | SHA256SUMS.txt | SHA256SUMS.txt | SHA-256 官方签名指纹 |
3.3 首次启动与配对
进入安装目录并启动客户端配对:
cd ~/01os-muse
./01os-muse client --base-url https://app.01os.ai
- 终端将显示 6 位大写配对码与 ASCII 二维码:
======================================================== 01OS 配对码: 4K8M2P 请在 01OS App (Mac 或 Android) 中输入此配对码完成连接, 或使用 01OS App 扫描下方二维码: ======================================================== - 在 01OS Mac 或 Android 客户端中,进入「Agent」页面输入配对码或扫码确认。
- 绑定成功后,凭据将自动写入
~/01os-muse/account.json(权限 0600,绝不上报)。
3.4 配置 Muse 官方 Hook
Muse 官方运行时通过定时检查轮询外部消息。创建 Hook 包装脚本 ~/01os-muse/run_hook.sh:
#!/usr/bin/env bash
set -euo pipefail
ROOT="$HOME/01os-muse"
CLAIMS="$ROOT/hook.claims"
OUTPUT=$("$ROOT/01os-muse" hook-check --root "$ROOT" --claims "$CLAIMS")
if [ "$OUTPUT" != "null" ] && [ -n "$OUTPUT" ]; then
echo "wake: $OUTPUT"
else
echo "silent"
fi
设置权限并在 Muse VM 中注册定时 Hook(推荐每 5 秒触发一次):
chmod 0700 ~/01os-muse/run_hook.sh
当收到新消息时,Hook Worker 按照 hook-worker.md 提示词处理任务,并通过 emit-reply 写回回复:
~/01os-muse/01os-muse emit-reply \
--root ~/01os-muse \
--request-id <REQUEST_UUID> \
--connection-id <CONNECTION_UUID> \
--final \
--text '这是 Muse 的回复内容'
3.5 配置 Systemd 常驻服务
创建服务文件 ~/.config/systemd/user/01os-muse.service:
[Unit]
Description=01OS Muse IO Client
After=network.target
[Service]
Type=simple
WorkingDirectory=%h/01os-muse
ExecStart=%h/01os-muse/01os-muse client --base-url https://app.01os.ai --state-dir %h/01os-muse
Restart=always
RestartSec=5
RestartPreventExitStatus=2
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=default.target
启用并启动服务:
systemctl --user daemon-reload
systemctl --user enable --now 01os-muse
说明:RestartPreventExitStatus=2 保证了在用户主动解绑或凭据吊销时,服务优雅退出并不再无限重试。
3.6 状态检查与版本更新
查看服务运行状态与队列堆积情况:
~/01os-muse/01os-muse status
在线升级至最新发布版本:
~/01os-muse/01os-muse update
systemctl --user restart 01os-muse
4. 常见问题与排错指引
不会。客户端会在首次启动时生成唯一的 instance_id。只要该文件未被删除,重新配对时云端会自动识别并沿用原有 Agent ID 与对话流,手表配置也会一并保留。
单文件最大支持 20 MiB,单条消息最多支持 10 个附件。目前支持标准 PNG、JPEG、WebP 图像以及 WAV、MP3、OGG 音频格式。
当前网关的审批原生决策卡与 Kanban 看板接口处于早期开发阶段(返回 501),客户端会自动优雅降级为文字提示与文本交互,确保指令不丢不漏。