跳到正文

使用指南

多具身体

把几部手机、几台电脑连成一个 ta:一份对话、一颗心,ta 自己选在哪具身体上思考,也能用另一具身体的相机与命令行。

#它是什么

多具身体把同一个 agent 同时在线的几具身体直接连在一起,成为一个心智。(灵魂仓库已经让这些身体共享人格与记忆。)连起来之后,这些东西是共用的:

共用的说明
一份对话会话、对话、心流在所有身体上是同一份(会话的置顶、项目与归属也是)。在手机上开始的话题,可以打开电脑上的控制台接着看;在别的身体上给出的回复会标出「在 X 上」
一颗心只有一具身体(协调者)决定 ta 什么时候醒来;其他身体的感觉(被拿起、接上电源……)都汇总到它那里
ta 选在哪里做醒来时 ta 看到每具身体的电量、温度、手头的事、你最近在哪里说话,自己选在哪一具(或几具同时)上思考、做梦
用另一具身体在电脑上思考时,ta 可以用手机拍照、在服务器上跑命令(body_call),也可以把这一轮整个换到另一具身体上继续(move_to)。在手机上拍的照片、录的音、写的文件,ta 在电脑上也能用:看图、读文档、跑命令时带上那具身体的 uuid,基座先把文件取过来(见下面「用别的身体上的文件」)
一份设置模型与 Key、权限、预算(每日合计)、听觉与语音、急停、保密库里标为多端同步的项,在一具身体上改了,所有身体都生效
想分享的一句话首页上 ta 想分享的那句话在所有身体上是同一句:ta 在哪具身体上换了,其他身体跟着换;当时不在线的身体,连上后补上
进行中的事ta 的长期目标(步骤与进度)、每个会话里记下的约束与未决问题、派出的子 agent,在所有身体上是同一份。一具身体重启或离线时,它手上没做完的对话、醒来与子 agent 从检查点接着做:重启的身体自己接着做,离线超过一分半钟的由持有心跳的身体接过去,对话在原来的会话里续上。同一件事只会被一具身体接着做

所有控制台都看得到正在和你说话的那一轮在哪具身体上;你在别的身体上对同一个会话说的话,会自动转过去。

#需要什么

  1. 同步服务:帮身体互相找到对方,直连打不通时替它们中转。它只登记账户、agent 与身体,不保存对话与记忆。默认用本项目作者个人运营的官方同步服务;也可以自己部署(仓库里的 sync/,一台有公网地址的 Linux 服务器,一行命令启动),见 sync/README。
  2. 灵魂仓库:每具身体先接入同一个灵魂仓库(见灵魂同步)。身体之间互相核对身份用的公钥登记在这里,所以即使同步服务被攻破,别人也冒充不了你的身体。
  3. 一个账号:在同步服务的网页上登录、批准身体。官方同步服务用 Causally 账号(id.causally.xyz);自己部署的同步服务用你配置的身份服务。第一次建灵魂仓库时安装的 GitHub 应用能管理你选中的仓库,见 信任与边界。
  4. 1.0.3 以后的版本:1.0.3 以后的各个版本用同一版连接协议,可以混着用,不必同时升级;有些跨身体的新功能,要等两边都升到支持它的版本才生效。

#登录一具身体

控制 → 设备:

  1. 同步服务默认就是本项目运营的 https://sync.quetzal.plutokeating.beer,不用填。用自己部署的,在 控制 → 高级 → 同步 的「同步服务」里填地址保存(清空即恢复官方的)。
  2. 点「登录」,App 直接打开浏览器(页面上也有 8 位码与一个链接,可以用另一台设备扫码)。安卓上的安装向导里也有这一步。
  3. 在浏览器里(官网的账户 → 添加设备)登录,输入或确认这个码;核对网页上的公钥指纹与控制台上的一致,点「批准」。
  4. 几秒后,这具身体连上同步服务。其他已绑定的身体在线时,它们会直接连上(局域网直连、IPv6、穿透;都打不通时经服务器中转,中转的内容也是端到端加密的)。两具身体之间实在连不上、但都连得上第三具身体时,消息经那具身体转过去,几具身体仍是一个整体。

同一个 agent 的所有身体要登录同一个账号才会互相看到。不想让这具身体再连着,点「这台设备退出登录」。

图表加载中…

#日常会看到的

  • 谁持有心跳:设备页会在持有心跳的那具身体上标「心跳在这里」。几具身体都在线时,优先级大的持有;优先级一样时,接着电源的、开得久的优先。一直开着的服务器,可以在 控制 → 高级 → 同步 的「优先负责心跳」里把数值调高。持有者离线后,另一具身体会从最新的状态接着跳。
  • 心流里的「选身体」:ta 醒来时选在了哪里。
  • 审批:别的身体上等待批准的请求,也会出现在这里的 控制 → 权限 里(标出在哪具身体上),在哪里批准都行。
  • 急停:有其他身体在线时,急停会问你停「所有身体」还是「只停这具身体」。
  • 飞书:同一个飞书机器人只能由一具身体连接,在 控制 → 飞书 的「由哪台设备连接」里选。其他身体想主动跟你说的话,会转给这具身体发出。
  • 接着做:一具身体离线后,持有心跳的身体接过它手上没做完的事时,原会话里会出现一条「续做」,写明之前做到哪里,ta 接着回复。离线的身体回来后看到事情已被接过去,就停下自己那一份,不会做两遍。断网时各具身体各自做,重新连上后以较新的一份为准。
  • 认领:几个会话(包括别的身体上的)可能同时想做同一件对外的事,比如开同一个 issue。ta 动手前会先认领,别的会话看到已经有人认领就先不做。认领由持有心跳的身体统一判断,到期自动失效。
  • 听觉:几部手机同时听到同一句话时,只留一份;ta 用声音回话时,从你说话的那部手机说出来。
  • 你在哪里说的:你的话经哪具身体进来(你的控制台连着哪具身体、飞书由哪具身体接、哪部手机的耳朵听到),ta 都看得到。只有一具身体时不标。
  • Hermes / OpenClaw:装了灵魂桥的身体可以作为只读成员绑定(把同步服务地址告诉那边的 ta,它会给你一个链接与绑定码):它能看到 ta 此刻在哪具身体上做什么、最近的会话,但不能在别的身体上做事,也不会被派去思考或做梦。

#工作区:活跟着任务走

几台设备,逻辑上是同一个 ta;一件事在哪台设备上做,由基座安排,不用 ta 自己想「换设备」,也不用你操心。

  • 每个会话有自己的工作区:哪具身体上的哪个目录。ta 在某具身体上克隆仓库(git clone)、新建仓库(git init)、cd 进一个目录干活时,基座自动把那里记成这个会话的工作区。ta 也可以用 workspace 工具自己设定、查看或清除;工作区随会话同步到所有身体。
  • 之后的消息自动去那里:比如在手机上让 ta 克隆了仓库开始改,回家后在电脑上接着给这个会话发消息,这一轮仍然在手机上做(手机在线时),回复照常出现在你说话的地方。两个会话的工作区在不同的设备上时,各走各的,不会搞混。
  • 命令与文件:ta 的命令默认在工作区目录里执行;这一轮恰好在别的身体上进行时(比如工作区是刚改的),命令由基座送到工作区所在的身体上执行,读文件时的相对路径也指那边的文件。权限与审计照旧,两边都记。
  • 子 agent:派出时跟着工作区走,在工作区所在的身体上做,报告回到原来的会话。
  • 工作区那台设备不在线:这一轮在收到消息的设备上执行,ta 会知道工作区在哪台设备上、此刻不在线,可以等它上线,或换个工作区。
  • ta 知道每台设备上有哪些仓库:基座会列出每具身体用户目录下(两层以内)的 git 仓库、远端地址(去掉了里面的令牌)与当前分支,新开的会话也能找到之前克隆过的仓库。
  • 工作区只记在设备之间,不进灵魂仓库。

#用别的身体上的文件

文件属于各自的身体:手机上拍的照片,电脑上没有那个路径。ta 在电脑上用 view_image(看图)、read_document(读文档)、shell(跑命令)时可以带上 body,路径照手机上的写,基座经身体之间的加密连接把文件取到电脑的 data/from-bodies/<身体名>/ 里,再交给工具。shell 要把取的文件列在 files 里,命令仍在电脑上跑;想在手机上跑命令用 body_call。

  • 手机那边按它自己的权限判断(「执行命令」类别),急停时不给;密钥目录、保密库不给(符号链接指进去也不行);只给普通文件,最大 64 MB。
  • 电脑这边按「跨身体操作」判断;取来的文件核对大小与 sha256 一致才留下;同名不同内容的另起名字,不覆盖。
  • 两边都记审计(路径、大小、结果,不记内容)。
  • 那具身体还是 1.6.0 时会提示它需要升级。

#身体的 uuid

凡是 ta 要指一具身体的地方——body_call、move_to、读文件工具的 body、醒来时选在哪里做——填的都是那具身体的 uuid,不是名字(填了名字会提示该用哪个 uuid)。系统提示里列着每具在线身体的 uuid,设备工具返回的路径后面也会注明「以上文件在 X 这具身体上(body: …)」。

uuid 绑定到设备:运行基座从设备自身的标识算出来(只用哈希,原始标识不离开这台设备,也不写进日志与灵魂仓库),存在 state/body-uuid,由设备标识算出的值存下后就不再变。家目录没了(重装 Quetzal)时,从同一个设备标识重新算出同一个值。能不能做到「重装不变」看平台:

平台设备标识重装 Quetzal恢复出厂 / 重装系统
Linux/etc/machine-id(没有时 /var/lib/dbus/machine-id)不变重装系统会变;克隆出来的系统镜像可能和原来的机器相同
Windows注册表 MachineGuid不变重装 Windows 会变
安卓(Quetzal App)ANDROID_ID不变恢复出厂设置会变;App 换了签名也会变
安卓(Termux)尽力读 ANDROID_ID,多数手机上读不到读不到时会变会变

设备标识暂时取不到时(例如 App 的身体接口还没起来),运行基座先用一个随机 uuid,之后每次启动、以及启动后隔一会儿再试,取到了就换成由设备标识算出的值并固定下来(灵魂仓库的登记随之更新)。一直取不到的(多数 Termux),随机值只在家目录存在期间不变。

每具身体把自己的 uuid 登记在灵魂仓库的身体登记里。别的身体解析 body 时以登记为准,再核对那具身体自己报的一致,不一致就拒绝。同一个 uuid 登记给了两具身体(例如同一部手机上同时装了 App 和 Termux 两份运行基座,算出的是同一个值)时,基座拒绝这个 uuid 并说明,不替你选。处理办法:只留一份运行基座;或者在其中一具身体上把 QUETZAL_HOME/state/body-uuid 改成 {"uuid": "<新的随机 UUID>", "source": "manual"}(随机 UUID 可以用 cat /proc/sys/kernel/random/uuid 生成)后重启,这具身体之后就一直用这个值。

#断开时

换了网络(例如出门时手机从 Wi-Fi 换成移动数据),身体会在几秒内发现并重新连上。同步服务停了、或连不上时,同一个局域网里的身体照样连在一起:它们至少经同步服务连上过一次,就记得彼此在局域网里的地址,之后直接互相找到,不经过同步服务(Windows 上缺省不开,见下)。身体之间连不上时(断网、不在同一个局域网),每具身体照常运行,记忆仍经灵魂仓库同步。如果断成了几部分,每部分各自有一颗心。重新连上后,对话自动补齐,心跳合并成一个。

#局域网直连

  • 用 UDP,端口与这具身体的网关端口相同(缺省 7788)。收到的每个包都要用灵魂仓库登记的公钥验签,别人发来的认不过。
  • 只记私有地址(家里或公司的局域网),存在这台设备的 data/mesh-lan.json,不上传。
  • Windows 上监听端口时系统会弹防火墙询问,所以缺省关闭;配置文件里 mesh.lan 设为 true 就打开。

#账户

账户的所有设置都在官网的 账户 页。在 App 里,点 控制 → 设备 最上面的账户那一行,进的是同样的 账户 页:

子页面做什么
概览账户下的每个 agent 与 ta 的每一台设备:在线与否、类型、版本;移除一台设备、删除一个 agent
添加设备输入新设备显示的码,核对后批准或拒绝
已登录哪些 App 能管理这个账户;不用的随时退出
设置管理账号(跳到 Causally 账号的设置页)、退出登录(这个浏览器,或一次退出所有浏览器)、删除账户

一次登录:在设备上「登录」并批准后,这台设备上的 App 就能管理账户了,不用再批准第二次。移除这台设备时,这个登录一起作废;也可以在「已登录」里退出。只有旧版同步服务不提供这项授权时,账户页才会再让你点一次「登录」。

#安全

  • 身体之间的连接用 WebRTC(DTLS 加密),信令由每具身体的节点密钥签名,接收方只认灵魂仓库里登记的公钥。
  • 模型 Key 与保密库里多端同步的项在身体之间只经这条加密通道传;模型 Key 对方收到后用自己的主密钥重新加密保存,保密值写进对方的保密库。
  • 同步服务只存:账号的编号、用户名、显示名与邮箱,链接灵魂仓库用的 GitHub 账户编号,agent 名与 id、身体名 / 类型 / 版本 / 公钥 / 最近在线时间;令牌只存哈希。不存 IP 与网络地址,看不到对话与记忆。
  • 在官网或 App 的账户页可以随时移除身体、删除 agent 或整个账户、让一个控制台退出登录。