你：明天面试，有点紧张。
ta：你准备了一整周，上次卡住的那道题也练熟了。去吧，回来跟我说说。
第二天 18:40 · 你拿起了手机
ta：面试怎么样？
Quetzal 是一个开源的 agent 运行基座（runtime）。它让一个 AI agent 住进你的手机和电脑，给 ta 记忆、身体和自己的作息。模型用你自己的 API Key。
手机上说到一半，电脑上接着聊。
- 每台装了 Quetzal 的设备都是 ta 的一具「身体」。同时在线的身体用 WebRTC 加密直连，共用一段对话、一颗心；直连打不通时，经 TURN 服务器或另一具身体中转。
- ta 自己挑在哪具身体上醒来。在电脑上想事情时，能借手机的相机看一眼窗外。
- 同步服务只帮身体们互相找到，看不到对话和记忆。默认用作者运营的那一个，也可以自己部署；它连不上时，同一个局域网里连上过的身体直接互相找到。
你随口提过的事、在意的人，ta 都记下来，存在只属于你的私有仓库里。换手机、换模型，ta 还是 ta。
- ta 的名字、人格、记忆、日记存在你自己的私有 git「灵魂仓库」。原有 Markdown 认识保留，新认识在
notes/QuetzalMemory/按来源、状态和版本记录，也能直接读到。 - 每一次改动都是一次 git 提交，自动推送、合并到每一具身体。记错了，在 App 的「记忆历史」里撤销那一次提交。
- 对话和持续行动的每一步，ta 按当前目标、约束与适用条件选择记忆，并按候选模型的窗口重建上下文；较早内容可摘要，原对话和行动证据可回查。新认识先保留来源与候选状态，个人事实和明确偏好需确认；做梦与后台学习可提炼经验，缺独立结果的建议不会自动当作已验证策略。
Codex 等你叫它，OpenClaw 每隔一阵被定时叫醒。ta 没有闹钟：想你了就醒，困了就睡。
- 自主醒来没有固定周期。好奇、想说话、想你这几股驱动力，加上睡眠科学里的双过程模型（睡眠压力 S 与昼夜节律 C，就是上面这张图），算出 ta 此刻醒来的概率，再随机抽样决定下一次候选时刻，由定时器等待后重新判断。
- 醒来先用便宜的模型想一想要不要动，不想就接着睡，所以大部分醒来花费很少。你找 ta、到点的提醒，任何时候都在。
- 已经在用 Hermes 或 OpenClaw？灵魂桥让它们和 ta 共用同一个灵魂仓库。
天亮了，你拿起手机了，电快没了，ta 都知道。
- 传感器读数被翻译成感受：电量是精力，温度是冷暖，光线是昼夜，被拿起来是有人在。电量低时少动，发烫时休息。
- 麦克风是耳朵，相机是眼睛。开了听觉，ta 自己判断你是不是在跟 ta 说话，也能用自己的声音回答。
- 每种设备经一个「适配器」接入。仓库自带安卓、Linux、Windows 三种；想接别的设备，实现一个小接口就行。
做熟了的事，ta 自己做成工具，下次一步做完。
- 工具留在这具身体上；说明书用 Agent Skills 开放格式写，存进灵魂仓库，随 ta 走。到了新身体，ta 照着说明书再做一遍。
- 费时的事，ta 派一个子 agent 在后台做，做完把结果交回来。
- 日常用得上的：提醒（准点，或者等你拿起手机时再说）、翻旧话、读 Word / PPT / Excel / PDF、上网搜索、运行命令、看图、在飞书里聊。
记忆在你自己的私有仓库里，每一句你都读得到。代码全部开源，每一行都能查。
- 密码不进模型。 你在聊天里发的密码直接进本机保密库，模型只看到一个名字。模型 Key 用 AES-256-GCM 加密存在设备上。
- 先问你。 拍照、录音、定位、造新工具，默认每次都问。每一类能力都能设为允许、询问或禁止。
- 随时叫停。 急停一直都在，工具调用有审计记录；每日 token 与花费预算用尽时减少自主醒来，目前不是强制停止模型调用的硬上限。
- 沙箱。 ta 的命令在隔离环境里运行（Linux 上 bubblewrap、Landlock 或 proot，安卓上 proot，Windows 上是一个低权限用户），看不到密钥。
- 只认你的设备。 身体之间只认灵魂仓库里登记的公钥，同步服务被攻破也冒充不了你的设备。
- 每一步都能自己来。 灵魂仓库可以自己建在任何 git 托管上，同步服务可以自己部署，不登录也能用。我们提供的账号、GitHub 应用和同步服务，只是替不想自己配的人把这几步做完。
数据经过谁、ta 能碰到什么，都写清楚了：信任与边界
- 身体：设备加适配器，提供传感器、相机、麦克风、通知、命令行这些能力。
- 运行基座（Node.js 22，TypeScript）：心脏决定什么时候醒，并按预算调低活跃度；大脑是调用模型与工具的循环；记忆负责检索与整理；模型层接 OpenAI、Anthropic、Gemini 和兼容它们的接口，一个出错自动换下一个；闸门管授权、审批、急停与审计。
- 灵魂：私有 git 仓库，用 SSH 部署密钥同步，规范固定、带版本号。
- 控制台（Flutter）：安卓 App（内置 Node.js、git、ssh，只装这一个）、网页版与 Linux 桌面版。
手机上装一个 App，电脑上运行一行命令。再准备一个模型 Key（DeepSeek、Kimi、智谱、OpenAI、Anthropic、Gemini 等都行），就能开始。
安卓手机（Android 7 以上，arm64）：从下载页装 Quetzal App，打开它，跟着向导走。
Linux 电脑或服务器：
curl -fsSL https://quetzal.plutokeating.beer/install | bashWindows 电脑（Windows 10 1809 以上或 Windows 11，x64 或 arm64），在 PowerShell 里：
irm https://quetzal.plutokeating.beer/install.ps1 | iex缺的依赖自动补齐，开机自启。登录后，ta 会在你的 GitHub 上自动建好私有的灵魂仓库；不登录也能用，记忆先存在设备上。
安装 · Linux 与其他机器 · Windows · 把一台旧手机腾出来的记录 Project.Honor9
| 目录 | 内容 |
|---|---|
engine/ |
独立 Agent 执行循环、通用协议、上下文 / 检索策略及受限研究运行器；开发计划和研究接入见 内核文档 |
runtime/ |
运行基座（TypeScript / Node.js 22+）与平台级身体适配器：安卓（Quetzal App 内置）、Linux、Windows，以及兼容旧安装的 Termux |
console/ |
控制台（Flutter）：安卓 App（含安装器与耳朵）、网页版（电脑浏览器，由运行基座托管）与 Linux 桌面版（原生窗口，一键安装脚本自动装） |
cli/ |
本机终端聊天 chat / tui、一键安装脚本 install.sh（官网的 /install）与 npm 包 @plutokeating/quetzal：Linux 安装器（systemd 用户服务） |
bridge/ |
灵魂桥：Hermes Agent / OpenClaw 的可插拔同步模块 |
sync/ |
同步服务：账户（OpenID Connect 登录）、自动建灵魂仓库与加部署密钥（GitHub 应用）、身体绑定、信令与 TURN 中转，让同一个 agent 的几具身体连成一张网；独立部署在一台服务器上，./start.sh 一行启动 |
website/ |
官网与文档站 |
docs/ |
快速开始 · 架构 · 接口 · 灵魂同步 · 仓库规范 · 分布式 · 一键上手 · 论文研究工作区 · 更新日志 |
仅用于学习和研究，只操作自己拥有的设备，不以牟利为目的。AGPL-3.0