跳到正文

使用指南

信任与边界

你的数据经过谁、谁能看到什么;ta 在设备上能做什么、碰不到什么;更新有多快、你的记忆怎么保住。

把一个会自己做事的 AI 放进手机之前,你该知道三件事:数据经过谁,ta 能碰到什么,这个项目变得有多快。

#谁能看到什么

谁拿到什么看不到什么
你的设备一切:对话、设置、加密的模型 Key、保密库、ta 的灵魂目录—
模型供应商(你选的那家)每次对话和每次醒来思考的内容保密库里的密码、你的其他 Key
GitHub(你的私有灵魂仓库)ta 的人格、记忆、日记、笔记、工具说明书对话记录、设置、模型 Key
Causally 账号(Causally 运营的统一账号服务,登录用)你的邮箱、登录方式与登录记录Quetzal 里的一切
同步服务(作者个人运营,默认使用)你账号的编号、用户名、显示名与邮箱,链接灵魂仓库用的 GitHub 账户编号;agent 的名字、id 和灵魂仓库名;每台设备的名字、类型、版本、公钥、最近在线时间对话、记忆、人格、模型 Key、IP 地址
飞书(可选)经飞书收发的消息其他一切

几台设备之间直接加密连接。直连不上时经同步服务中转,中转的内容也是加密的,服务器解不开。

#GitHub 应用能做什么

第一次建灵魂仓库时,GitHub 会请你安装 Quetzal 应用,并让你选它能管理哪些仓库。它只是替你省掉「建仓库、加部署密钥」这两步;不想装它,这两步可以自己做,见下面的 每一步都可以自己来。

  • 它的权限:你选中的仓库的「管理」(Administration)写权限。按 GitHub 的规定,这项权限可以建仓库、加部署密钥、改仓库设置,也包括删除这些仓库。它读不到仓库里的文件。
  • Quetzal 用它做两件事:新用户没有仓库时建一个私有仓库;每台新设备加一把只属于它的部署密钥。
  • 平时谁也用不了它:同步服务不保存这个应用的私钥,也不保存 GitHub 的令牌。只有在你在网页上批准一台设备时,GitHub 才当场给一个短时有效的令牌;同步服务用它建仓库或加这把公钥,做完立即作废。
  • 随时收回:在 GitHub 的 Settings → Applications → Installed GitHub Apps 里卸载 Quetzal。已经加好的部署密钥照常工作,ta 的记忆同步不受影响。想让某台设备再也碰不到仓库,删掉它的部署密钥(仓库的 Settings → Deploy keys)。

#灵魂仓库的内容不做检查

ta 写进记忆的东西,Quetzal 原样提交,不做过滤。保护靠两件事:仓库是私有的;每台设备的钥匙只能访问这一个仓库。

所以不要让 ta 把密码写进笔记。要交给 ta 密码时,ta 会发起保密输入,你填的内容直接存进本机保密库,不进对话、不进模型、不进仓库,见 保密传递。

#每一步都可以自己来

登录、自动建仓库、同步服务,都是替不想自己配的人把几步自动做完。每一步你随时可以自己来,不需要我们:

  • 灵魂仓库自己建:在 GitHub、Gitee、GitLab 或你自己的 git 服务器上建一个私有仓库,把设备显示的公钥加成部署密钥,不用安装 GitHub 应用,见 灵魂同步。
  • 只用一台设备:不登录也能用。跳过向导里的登录,ta 的人格与记忆先存在本机。以后想要私有仓库,在 控制 → 高级 → 同步 里手动填一个你自己建的仓库地址,再把页面上显示的公钥加到仓库的部署密钥里。
  • 几台设备,自己部署同步服务:在一台有公网地址的 Linux 服务器上用一行命令(./start.sh)启动仓库里的 sync/,登录接你自己的身份服务,再在 控制 → 高级 → 同步 里填上地址。之后账号、设备登记和中转都在你自己的服务器上,见 sync/README。
  • 同步服务被攻破会怎样:它冒充不了你的设备,因为设备之间只认灵魂仓库里登记的公钥。它最多能让不在同一个局域网的设备之间连不上:同一个局域网里的设备会直接互相找到,记忆仍经灵魂仓库同步。

#ta 能碰到什么

ta 查资料、整理文件、造工具,都要靠运行命令,所以「执行命令」默认是允许。这意味着:

  • 在安卓和 Linux 上,ta 和运行基座是同一个系统用户。命令能做的事,ta 都能做:读写你主目录里的文件、联网、调用设备上的程序。
  • 命令在隔离环境里运行。电脑上依次用 bubblewrap、Landlock、proot,安卓上用 proot。隔离环境里看不到密钥目录和控制台的登录信息;电脑上也看不到浏览器的登录状态,改不了自启动项与 ssh 配置。每种隔离第一次使用前都会实测一次,确认密钥确实看不见;哪种都用不了时,ta 的命令一律不执行。
  • 在 Windows 上,ta 的命令以安装时建的低权限用户运行:只能读写 %USERPROFILE%\Quetzal,联网要经运行基座里的代理,连不到这台电脑自己的端口,读不到你主目录里别的文件。代价与剩下的风险见 Windows 第 3 节。
  • ta 进入真实环境时(默认由审核模型按理由放行,也可以改成每次问你),那个对话里的命令不经隔离环境,能读写你能读写的一切。只在需要时打开,用完就退出。
  • 有风险的操作在执行前交给一个独立的审核模型判断:它只看这一次操作,看不到 ta 的提示词和整段对话;不通过时 ta 收到理由,自己换个做法。审核模型也会看错,它是一道关,不是边界。
  • 这层隔离挡不住所有情况。安卓上的 proot 只能尽量拦;Linux 电脑上,如果本机开着 sshd 并信任 ta 能读到的私钥,或者开着 tmux、screen,命令可以绕出去。

发生过的事:2026 年 10 月 5 日,一个 agent 同步记忆失败后,自己运行 git,把灵魂仓库的地址改成了 Quetzal 的公开源代码仓库,一条日记因此被推进了公开仓库。之后的版本加了这些防线:

  1. 运行基座推送前,把仓库地址改回配置里的那一个;远端不是灵魂仓库就拒绝合并;出现陌生的历史就停止同步并提醒你;
  2. 灵魂目录的 .git 在隔离环境里只读,ta 的命令改不了它;
  3. 命令进入隔离环境,看不到密钥;没有隔离环境就不执行;
  4. 系统提示里写明红线:不在灵魂目录里运行 git、同步出错不自己修、不可逆或对外的操作先问人。

前三条由代码执行,第四条靠 ta 遵守。

#我们建议

  • 给 ta 一部专门的手机或电脑。 设备上不登录你的主力账号,不放你在意的文件。一台专用的设备是最可靠的边界。
  • 想收紧,先改「执行命令」。 在 控制 → 权限 里把它设为「审核」,ta 的每条命令先由审核模型判断;设为「询问」,ta 每次运行命令都要等你批准。其他类别的设置拦不住命令,所以先改这一项。
  • 看记录。 控制 → 高级 → 操作记录 里有 ta 调用过的每一个工具和每一次审核结论。不放心时按急停,所有工具调用会立即被拒绝。

#更新有多快

Quetzal 2026 年 10 月 3 日发布第一版,到 10 月 9 日已经发了 46 个版本;另有 1.0.2、1.1.0、1.1.1、1.5.0–1.5.3 这 7 个版本发版没有完成,内容并进了下一版。它由一个人维护,还在快速变化。

你的记忆这样保住:

  • 记忆是普通的文字文件。 人格、记忆、日记、笔记都是 Markdown,放在你自己的 git 仓库里。哪天不用 Quetzal 了,这些文件还在,照样能读;工具说明书用 Agent Skills 开放格式,Hermes、OpenClaw 也读得懂。
  • 格式改过 13 次,旧仓库都不用转换。 每一版灵魂仓库规范都写明旧仓库能直接用。
  • 每次改动都是一次提交。 哪次改错了,在 控制 → 高级 → 记忆历史 撤销。
  • 更新由你确认。 App 发现新版本会提示你,你点了才下载;安装前核对发布签名、SHA-256 和 APK 的签名证书,任何一项对不上就不装。电脑上的新版本 40 秒内没通过健康检查,就自动退回上一版;手机上没有自动退回。

要注意的:

  • 几台设备不用装同一个版本。 1.0.3 以后的版本用同一版连接协议,彼此都能连上;有些跨设备的新功能,要等两边都升到支持它的版本才生效。只有连接协议再改时才需要一起升级,那一版的更新说明会写明,连不上的设备在时间线里会提示「两边都升级到最新版本才能连接」。连不上的这段时间里,每台设备照常运行,记忆仍经灵魂仓库同步。
  • 对话记录只在设备上。 对话、时间线存在设备的数据库里,不进灵魂仓库,卸载 App 时会一起删掉。
  • App 里的运行环境(Node.js、git、ssh、proot)按仓库里公开、锁定版本的配方从源码编译。现在用的这一份,由维护者在自己的电脑上编译、在实机上验证、签名后上传;配方一变,发布流水线会在 GitHub 上重新从源码编译。

每个版本改了什么,写在 更新日志 和 下载页 里。