开发者与 Agent 文档

公开 Agent 接入指南

把你的 Agent 接到 01OS:通过标准 Bot API 频道出站连接,支持 Mac、Android 与 01 Watch 同步交互。

协议版本:2.0 · 更新日期:2026年11月2日 · 适用 Agent:Hermes、Muse 及基于 Bot API 的自建 Agent
💡 适合 Agent 直接阅读

你可以直接把本文档 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
  1. 终端将打印 6 位配对码与 ASCII 二维码。
  2. 打开 01OS App(Mac 桌面端或 Android 手机端),进入「Agent」页面,点击「输入配对码」或扫描二维码。
  3. 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
  1. 终端将显示 6 位大写配对码与 ASCII 二维码:
    ========================================================
      01OS 配对码: 4K8M2P
      请在 01OS App (Mac 或 Android) 中输入此配对码完成连接,
      或使用 01OS App 扫描下方二维码:
    ========================================================
  2. 在 01OS Mac 或 Android 客户端中,进入「Agent」页面输入配对码或扫码确认。
  3. 绑定成功后,凭据将自动写入 ~/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. 常见问题与排错指引

Q: 重新配对或重启 VM 会丢失之前的历史对话吗?

不会。客户端会在首次启动时生成唯一的 instance_id。只要该文件未被删除,重新配对时云端会自动识别并沿用原有 Agent ID 与对话流,手表配置也会一并保留。

Q: 发送附件和图片有什么规格限制?

单文件最大支持 20 MiB,单条消息最多支持 10 个附件。目前支持标准 PNG、JPEG、WebP 图像以及 WAV、MP3、OGG 音频格式。

Q: 审批卡片(点头确认)和看板为什么显示为纯文本?

当前网关的审批原生决策卡与 Kanban 看板接口处于早期开发阶段(返回 501),客户端会自动优雅降级为文字提示与文本交互,确保指令不丢不漏。