Grandillionaire/urfael

_{📖 **完整手册** 是一个可导航、可搜索的文档站点，位于 [`docs/manual/`](docs/manual/)（包含安装、快速入门、各项功能、全部 19 个频道、安全模型，以及自动生成的 [CLI 参考](docs/manual/reference/cli.md)）。面向机器可读的索引位于 [`docs/llms.txt`](docs/llms.txt)。📄 可分享的落地页位于 [`docs/index.html`](docs/index.html)（启用 GitHub Pages → `/docs` 即可同时提供两者服务）。} ## 目录 - [为什么选择 Urfael](#why-urfael) · [诚实的对比](#how-it-compares) - [核心亮点](#highlights) - [安全模型](#security)：护城河 · [ARCHITECTURE.md](ARCHITECTURE.md)：一个大脑、一个 socket，5 分钟了解整个系统 - [安装](#install) & [快速开始](#quick-start) - [交互界面](#the-surfaces)：Console · 浮球 · TUI · Web 仪表盘 - [频道](#channels) · [语音](#voice) · [记忆与召回](#memory--recall) · [编程](#coding) · [成本](#cost) - [轻度测试的部分](#whats-lightly-tested)：请阅读此部分 - [不适用人群](#who-this-is-not-for) - [名称由来](#the-name) · [贡献指南](#contributing) · [许可证](#license) ## 为什么选择 Urfael Urfael 是一个常驻运行的本地大脑，它将你安装的 `claude` CLI 作为子进程运行，因此它会借用你现有的 Claude Code 登录状态，**无需 API key，也无需任何额外连接**。一个 Obsidian vault 是它的归档处；一个私有 git repo 是它的记忆；语音的输入和输出都在设备上完成。它会在屏幕上呈现完整的文字回复的同时，用真实的声音作答；在不需要你的时候保持安静；并在你开启之前，默认关闭高能耗功能。 让它与众不同的不是功能的数量，而是爆炸半径（受影响范围）。没有任何服务监听网络端口。在“大脑”接收到每一条远程消息之前，都会将其与你的 ID 进行白名单比对，并在默认的只读沙箱中进行处理。自主编程任务会在用完即弃的容器或远程主机中运行，绝不会挂载你的密钥。并且，安全关键路径附带了旨在破坏它们的对抗性回归测试：那些是审查者发现的字面意义上的真实攻击，被冻结在代码库中，确保它们永远不会倒退。 ### 横向对比 下表中的每一项优势都是真实的，每一个不足也在同一张表中坦诚列出。诚实是核心原则。`✅` 可靠 · `⚠️` 部分 / 设计上的取舍 · `❌` 缺失。 | 能力 | **Urfael** | Hermes | OpenClaw | |---|---|---|---| | 无入站网络端口 | ✅ 无开放端口¹ | ⚠️ 视情况而定 | ⚠️ 入站 DM / 网关 | | 失败即关闭的沙箱 | ✅ Docker/SSH，默认拒绝 | ⚠️ 可选 | ⚠️ 可选 Docker | | 内置对抗性回归测试 | ✅ 攻击自身 | ❌ | ❌ | | 默认所有者白名单 | ✅ 所有频道，在“大脑”处理前 | ⚠️ 配对机制 | ✅ 配对机制 | | 本地、设备上的语音 + 状态呈现 | ✅ whisper + say，浮球 HUD | ⚠️ TTS/STT | ⚠️ 倾向云端 | | 统一费率（无按 token 计费） | ✅ 你的 Claude 订阅 | ❌ 按 token 计费的 API | ❌ 按 token 计费的 API | | 桌面应用 · TUI · Web 仪表盘 | ✅ 三者皆有 | ⚠️ TUI + 桌面端 | ✅ 应用 + 画布 | | 多用户，随时可审计 | ✅ 沙箱化主体 + `urfael audit` | ⚠️ DM 配对 | ⚠️ 配对机制 | | 无法分发恶意软件的技能中心 | ✅ 扫描 + SHA 锁定 + 永不执行 | ⚠️ 外部标准 | ❌ 实际环境中出现过投毒 | | 聊天频道广度 | ✅ 19 个 | ✅ 很多 | ✅ 20+ | | 模型灵活性 | ✅ 通过代理支持任何模型，由安全框架强制执行 | ✅ 200+ 原生支持 | ✅ 许多提供商 | | 大规模实战检验 | ⚠️ 规模较小，且我们直言不讳 | ✅ 规模大 | ✅ 规模非常大 | | 操作系统覆盖面 | ⚠️ macOS 成熟，Linux 较新 | ✅ 广泛 | ✅ 广泛 | _{¹ *大脑*不开放任何端口（仅限 unix socket）。可选择开启的 Web 仪表盘、兼容 OpenAI 的 API 和 webhook 接收器仅绑定到 `127.0.0.1`：仅限环回接口、通过 token/密钥控制，局域网或互联网无法访问。唯一真正属于入站的接口都是可选的，且需你自己建立隧道：可选的 WhatsApp 桥接器（通过 HMAC 验证）和 webhook 接收器（每个 hook 对应一个专属密钥）。两者都不会替你开放端口。² 竞争对手的表格内容已尽力做到公平：两者都提供可选的沙箱，且都默认采用 DM 配对机制。} **对于一台放在你桌面上并代你采取行动的机器而言，我们在真正重要的地方获胜：爆炸半径、成本可预测性，以及绝不过度夸大成熟度。** ## 核心亮点 先谈收益，后谈机制。一切功能皆可选择开启，并设有防护机制。 - **没有任何可攻击的入口。** 大脑仅通过 `0600` 权限的 unix socket 通信：没有 TCP 端口，局域网或互联网没有任何接口可以触达它。（[详情](#security)） - **它在本地听到了你的声音。** 在 Console 中点击说话或使用语音唤醒词；whisper.cpp 进行转录，macOS `say`（或本地 Kokoro）进行语音播报，默认不使用任何云端的 STT/TTS。语音评论会逐句流式传输，如果回答稍慢，你会听到一句 "On it, sir." 而不是死一般的沉寂。 - **固定费率，到此为止。** 它在你的 Claude Code 订阅上运行。除了订阅之外，闲置状态毫无成本；绝对不会出现按 token 计费的意外开销。Token 使用量和估算的每日/7天/30天花费显示在应用程序、仪表盘以及 `urfael status` 中。 - **不断积累的记忆，并在相关时刻瞬间召回。** 每次对话都会自动提炼为持久记忆、经验教训以及对你的用户画像。在“大脑”回答之前，**主动召回** 会检索出与*当前*消息相关的过往对话和受信任的经验教训，并自动将其置于上下文前方，因此你无需刻意提醒它，它也无需决定是否进行搜索。询问 "what did I say about the Berlin trip?"，它还能 **使用 BM25 + 可选的本地语义向量的混合模式对其整个历史记录进行排名**，并附上日期引用。（Hermes 在每个会话中仅冻结一次内存快照；它和 OpenClaw 都只能等待 agent 主动调用搜索工具。而 Urfael 每一轮对话都会进行检索。） - **它会验证自己学到的东西。** 在 **独立的验证器** 判定某条经验正确、具有普适性（不过拟合）且安全之前，它不会被信任；它会进行测量，隔离失败的内容，并基于证据进行修剪。`urfael learn` 可查看账本。一个不会被自身推断所毒化的学习闭环。 - **用于实际编程的更优秀的 Claude Code。** `urfael code ""` 会在你的代码库中运行 Claude Code，并配备了原生 CLI 所缺乏的安全网：它 **会记住每个代码库**（每次加载特定项目的约定和历史），在它触碰任何内容之前 **对整个工作树进行 Checkpoint**（存储在私有的 git 影子引用上，因此你的分支和索引保持原封不动），并为你提供一键 **撤销**（`urfael rewind`）功能，该功能可恢复你的文件，并且其自身也是可逆的。放心地把真正的任务交给它，不用提心吊胆。（[详情](#coding)） - **它审计代码，包括它自己的和你的。** `urfael scan ` 会对任何代码库执行只读的安全审计。一个沙箱化的 agent（仅拥有读取和 grep 权限：无写入、无 shell、无网络）会扫描源代码，然后一个独立的“怀疑论者”会重新检查每一个可疑项并剔除误报，因此你得到的是经过验证的发现，而不是满屏的噪音。它会输出一份诚实的报告（发现了什么、检查并清除了什么、未涵盖什么），或者使用 `--report` 写入一份报告。被审计的代码库被视为不受信任的输入，因此即使代码试图劫持审计程序，只读的底线依然稳固。 - **安全且强大。由你决定。** 默认的 **Fortress** 模式会将远程对话保持为只读且无网络出口。可选择开启 **Full** 模式（`urfael setup`），此时远程所有者/成员的对话将获得网络访问权限（浏览 + 搜索网络），同时 *依然保持* 无 shell、不可绕过、加框控制以及拒绝访问凭证的状态，因此即使是 Full 模式也比 Hermes 的默认设置受到更多限制。（[Fortress 对比 Full](docs/MODES.md)） - **CISO 也会批准的团队 agent。** 多人可以共同使用它，每个人都是通过同一个失败即关闭的内核运作的 **沙箱化主体**，其中角色权限只能缩小访问范围，绝不能升级至全权。`urfael audit` 会向审计员提供“谁/何时/做了什么”的追踪记录。（[详情](docs/TEAM-MODE.md)） - **不断增长的技能，并以极度偏执的方式安装。** 它会记录下操作流程并加以复用；由专门的程序清理过期内容。任何技能，包括来自 **`urfael hub`** 注册表的技能，都会被 **扫描、SHA 锁定、预览，且绝不执行**。扫描器在 Shell 和 JavaScript 的覆盖面上与 Hermes 和 OpenClaw 齐平，并更进一步：它会 **解码一层混淆代码并重新扫描字节**，因此隐藏在 base64 或 `\xNN` 数据块中的恶意木马会被捕获，而不是被当作纯文本误判为安全；同时它还会交给你一份 **能力摘要**（是否会触碰网络、读取密钥、运行 shell、持久化？），并附带 `block` / `review` / `clean` 的判定结果。静态扫描是一种启发式方法，因此真正的保证在于其背后的那一层：已预览、SHA 锁定、绝不执行。自带安全保障的应用商店。 - **数以千计的可选连接器，以安全的方式设置。** 需要它连接 GitHub、Notion、Slack、Postgres、Stripe 或你的日历吗？连接器就是一个 **CP server**，即大脑早已支持的开源标准，因此整个 **18,000+ 的服务生态** 都可以触达，并且常用组件只需一条命令即可搞定：`urfael connect add github`。每次添加都会在写入任何内容之前显示 **启用前的安全预览**（它能做什么、连接到哪里、是否运行本地代码），并进行静态扫描；它还会 **屏蔽你输入的密钥**，使其永远不会出现在你的 shell 历史记录中；并且 **仅在所有者发起的对话中加载**，因此沙箱化的远程/定时任务无法调用。大多数工具只是将密钥写入配置文件并需要重启才能生效；而 Urfael 会先预览连接器，屏蔽密钥使其不污染 shell 历史，并且热加载而无需重启。（[详情](#connectors) · `urfael connect`） - **静默的主动性。** "Remind me in 20 minutes"（20 分钟后提醒我）或 "every morning at 8"（每天早上 8 点）开箱即用。**计划任务**（`urfael cron add "summarize my unread mail" --daily-at 08:00`）会按计划调度“大脑”并返回结果，或者通过 `--script` 参数执行无需 LLM 的 shell 命令（可选开启，由所有者编写）；`--then` 步骤可在任务完成后 **链式触发** 后续操作（前一个输出将作为 `$URFAEL_PREV` 传入）。提醒功能播放固定文本；而 cron 任务会*实际执行操作*并汇报结果，以通知的形式弹出、通过语音播报或推送到聊天频道（Telegram/Discord/Slack/iMessage），不留任何死角。可选开启的心跳检查会运行你的 `HEARTBEAT.md` 检查清单，除非确实有需要你关注的事情，否则保持静默。此外，**webhook 事件触发器**（`urfael hooks` + `urfael hook add`）允许外部事件（如 CI 构建完成、支付成功或监控警报）通过仅限环回接口的接收器唤醒大脑，并由每个 hook 对应的 256 位密钥进行控制；触发器的动作同样被沙箱限制为无网络出口（只读，无 shell/写入/网络），因此事件不会演变成提权攻击。详见 [docs/HOOKS.md](docs/HOOKS.md)。 - **单个大脑不够用时的委员会机制（可选，实验性）。** `urfael council ""` 会召集一个实时、可视化的圆桌会议：由编排器分解任务，分发给只读的工作节点，并最终汇总出一个答案，整个过程可回放并记录在账本中。通过 `URFAEL_MOA_BRAIN=1`，你还可以将这个组合变成你的 *主答大脑*（`urfael brain council`，或说 "council mode"），这是一个 Mixture-of-Agents 大脑。它保持纯本地化，让所有工作节点都处于只读底线（Read/Grep/Glob）上，失败时直接关闭而不是静默地由单节点回答，不添加任何依赖和端口，且默认关闭，从而保证包月订阅下的大脑在字节级别上完全一致。它会引发成本更高、速度更慢的扇出操作，因此请有意识地调用它。 - **它攻击自身。** 安全关键路径附带了基于真实的对抗性发现（白名单绕过、SSRF、解析器不同步、DoS）构建的回归测试，确保它们不会悄无声息地腐化。 - **它会告诉你自己不知道什么。** 参见 [轻度测试的部分](#whats-lightly-tested)。这一部分的存在是有意为之。 ## 安全 大脑是一个仅可通过 `0600` 权限的 unix socket 访问的本地守护进程，并且 **它从不开放 TCP 端口**。其拓扑结构是单向的：Urfael 主动向外连接（连接到你的 `claude` 登录状态，以及它轮询的聊天 API）；没有任何外部连接可以向内渗透。 - **在大脑处理前进行白名单比对。** 每一条来自 Telegram/Discord/Slack/iMessage/Email/Matrix/Signal/WhatsApp 的消息，都会根据 *你的* ID 进行校验，如果不符则会被丢弃并记录审计，在此之前，不会有一个 token 到达模型。远程对话运行在 **只读沙箱** 中（只能读取 + 搜索你的 vault；无写入、无 shell、无网络出口），并被封装在基于 nonce 加框的不受信任数据信封中，以防范提示词注入。 - **一切皆失败即关闭。** 未知频道的请求会被解析为受限制程度最高的配置文件，而不是最低的。格式错误的请求会被拒绝，而不会进行猜测。 - **沙箱化的自主性。** `/goal` 循环会在宿主机上、一个设置了 `--network none` 的用完即弃 Docker 容器中（仅载入 `claude` 的认证文件，绝不包含你的 `bridge.env`/API keys），或者通过 SSH 在远程主机上运行。 - **独立验证的完成状态（可选开启，实验性）。** 开启 `goal-loop.sh --verify`（需要预先提供机器可检查的强制 `--criteria` 契约），此时“任务完成”的判定将由 **另一个全新的只读 agent 进行，它唯一的工作就是反驳该结果** —— 绝不是由执行任务的 agent 自己来判定。任务完成需要同时满足：确定性的 `--check` 通过，以及验证器无法反驳，并需要为每个标准提供证据；反驳/错误/超时一律视为未完成（失败即关闭）。契约和每一个判定都会被哈希链入防篡改的账本（`urfael audit --verify`）。Hermes 的 `/goal` 会进行自我验证（由作者给自己的工作打分），而 Urfael 的反驳者是独立的，只能行使否决权，并留下可审计的记录。默认关闭（不开启时循环的字节码完全一致）；宿主机 + docker 环境已认证，SSH 环境下失败即关闭。 **靠证据说话，而非空谈。** `npm run security` 会启动真正的守护进程 + 仪表盘，并模拟 2026 年真实环境中自托管 agent 遭受的攻击方式（例如在某款广为使用的 agent 中发现的一键 token 泄露 RCE 漏洞，数以万计的暴露网关，被投毒的技能注册表，利用提示词注入窃取密钥，DoS 攻击）。最新一次运行结果：**抵御了 11/11 类攻击，通过了 125/125 项检查**。请参阅 [安全基准测试](docs/SECURITY-BENCHMARK.md) 和正式的 [威胁模型](docs/THREAT-MODEL.md)。路线图详见 [改进计划](docs/IMPROVEMENT-PLAN.md)；多用户模式详见 [团队模式](docs/TEAM-MODE.md)。 ## 安装 ``` git clone https://github.com/Grandillionaire/urfael.git urfael-src && cd urfael-src # NOT ~/urfael: on macOS it collides with the ~/Urfael vault ./install.sh # checks deps, fetches the local speech model (checksum-pinned), scaffolds your vault, no keys urfael setup # onboarding wizard: subscription (default), an API key, or a local model cd app && npm start # the Console opens ``` 更喜欢用单行命令？这里有一个引导脚本（`get.sh`），可以为你克隆并运行 `install.sh`： ``` curl -fsSL https://raw.githubusercontent.com/Grandillionaire/urfael/main/get.sh | bash ``` 对于一个核心理念就是 *绝不将不受信任的脚本通过管道传输给 shell* 的工具来说：这行单行命令纯粹是为了方便，而且 `get.sh` 的代码故意写得很短，方便你先阅读（`curl -fsSL …/get.sh | less`）。它本身不会执行任何高风险的安装操作；它只是获取源代码并交接给 `install.sh`。上面提供的克隆并阅读的路径是完全相同的，也是推荐的做法。 `install.sh` 对“先读后执行”非常友好：它 **绝不会** 自动安装大型软件或开启任何高风险配置。它只会写入配置模板（`chmod 600`），搭建 `~/Urfael`（你的 vault）和一个私有的本地 `~/Urfael-memory` git repo 的框架，链接 `urfael` CLI，并写入服务文件（macOS 上是 launchd，Linux 上是 `systemd --user`），**但绝不会加载它们**。剩下的只需一行 Homebrew 命令即可搞定： ``` brew install ffmpeg whisper-cpp coreutils # macOS # Linux: sudo apt install ffmpeg espeak-ng libnotify-bin grim (+ 构建 whisper.cpp) ``` 大脑会使用 Claude Code 的模型 **别名**（大部分对话使用 `opus`，遇到代码和深度推理时升级为 `fable`），因此它始终会追踪你的订阅计划所支持的最新模型——今天是 Opus 5 和 Fable 5，明天是它们的继任者，全程无需更改代码。你可以随时切换：`/fable`、`/opus` 或 `/sonnet` 前缀用于单次对话；"switch to fable" / `urfael model fable` 用于固定模型；"back to auto" 用于恢复自动路由。最高级别的模型需要 **Max** 订阅；如果是 **Pro** 订阅，请设置 `URFAEL_FABLE_MODEL=sonnet URFAEL_OPUS_MODEL=sonnet`。完整的设置（语音层级、连接器、桥接器、Linux 支持）详见 [docs/SETUP.md](docs/SETUP.md)。 ### 使用其他模型 Urfael 驱动的是 `claude` CLI 并继承你的环境变量，因此只要 Claude Code 本身支持的后端，都可以通过它运行，且无需额外的 Urfael 代码： - **Amazon Bedrock / Google Vertex 上的 Claude。** 设置 `CLAUDE_CODE_USE_BEDROCK=1`（需提供 `AWS_REGION` + 凭证）或 `CLAUDE_CODE_USE_VERTEX=1`。费用会计入你的 AWS/GCP 账单。 - **自定义网关或通过代理使用任何模型。** 将 `ANTHROPIC_BASE_URL` 指向一个具备翻译功能的代理（[claude-code-router](https://github.com/musistudio/claude-code-router)、[LiteLLM](https://docs.litellm.ai/) 或 y-router），即可使用 GPT/Gemini/DeepSeek/Ollama/LM Studio。由于 Claude Code 使用的是 Anthropic Messages API 进行通信，因此代理需要伪装成该接口格式并进行转换。 - **100% 在你自己的 GPU 上运行。** 通过同样的代理使用本地模型（Ollama / LM Studio / NVIDIA NIM），再加上原本就在本地的语音功能，意味着 *没有任何数据会离开你的设备*：完全物理隔离，零边际成本，同样的安全模型。Urfael 会将这种路由规则转发给它派生的每一条执行路径（实时对话、聊天、定时任务、心跳检查），从而让整个系统完全实现本地化，而不仅仅是前台任务。诚实的权衡是：本地模型在能力上达不到 Claude 级别。完整指南：[docs/LOCAL-GPU.md](docs/LOCAL-GPU.md))。 你需要了解一个不对称之处：**非 Anthropic 的模型是在你自己的提供商密钥下运行的；而 Claude 订阅仅涵盖 Anthropic 模型。** 此外，如果你的环境中存在 `ANTHROPIC_API_KEY`，它将覆盖订阅状态。（提供原生的、非 CLI 的提供商支持并不是我们的目标；因为那意味着要放弃 `claude`-CLI 框架，而正是该框架保持了 Urfael 的快速运行、在你的订阅计划内免费，并使其符合 Anthropic 的服务条款。） ### 快速开始 ``` launchctl load -w ~/Library/LaunchAgents/com.urfael.daemon.plist # macOS: the always-on brain # Linux: systemctl --user enable --now urfael-daemon cd app && npm start # the Console ``` 点击麦克风说话，或者直接打字。这就是一个完全基于你的 Claude Code 订阅计划运行的完整语音助手。 **快捷键** `⌘⇧O` 打开 Console · `⌘⇧Q` 退出 · `⌘K` 命令面板 · `⌘1-6` 切换视图 · 浮球模式额外提供 `⌘⇧U` 显示/隐藏 · `⌘⇧T` 外观设置 ## 交互界面 一个大脑，四种触达方式，它们都是同一个守护进程的轻量级瘦客户端。因此，你通过语音开启的对话，也会同时显示在 Console、CLI 和你的手机上。

**Console。** 桌面应用程序。提供带有单行工具活动的流式回复、按键通话、完整的对话归档、提醒、后台任务、实时成本显示以及设置。键盘优先，配备 `⌘K` 命令面板。

Orb HUD · Terminal · 全屏 TUI · Web 仪表盘 · 点击展开

- **Orb HUD**（`URFAEL_ORB=1`）：屏幕角落里的一个环境感、可穿透点击的“真知晶球”，提供四种外观（`sigil`、`rune`、`ember`、`eye`）。说出唤醒词，即可解放双手进行交谈。 - **Terminal。** `urfael "summarize my inbox"` 会实时流式传输答案；`status`、`jobs`、`reminders`、`remind`、`sessions search`、`skills`、`stop`、`dashboard` 管理其余操作。`Ctrl+C` 可停止当前对话。提示词也可以来自文件或标准输入：`urfael --file ./task.md`（别名 `--message-file`），`echo "draft a reply" | urfael`，或者使用 `urfael -` 读取标准输入。这在处理多行或 JSON 格式的词时非常方便，而且比通过命令行参数（argv）传递更私密（因为文件和管道传递可以避免内容出现在 `ps` 进程列表和你的 shell 历史记录中）。 - **`urfael tui`。** 一个无额外依赖的全屏终端控制台：包含带实时工具活动的流式记录、状态栏、按 `Esc` 键停止，并且总是干净地退出，不留任何残影。输入 `/` 即可调出命令面板，输入时会自动过滤，就像 Claude Code 的操作方式一样，因此你永远不需要死记硬背命令。每个命令都会打开适合该任务的最佳工具：`/persona` 和 `/model` 提供可导航的卡片选择器（方向键移动、输入即过滤、回车切换），`/theme` 在移动时实时预览，`/search` 对过去的每一次对话执行全文召回，`/usage` 显示今天 / 7 天 / 30 天的开销情况。 - **兼容 OpenAI 的 API。** `urfael serve` 暴露了一个受 token 保护的 `http://127.0.0.1:7720/v1` 接口（支持 chat completions + models）。将 Open WebUI、LibreChat 或 `openai` SDK 指向它，Urfael 就会成为它们的后端，并严格锁定在环回接口上。 - **Web 仪表盘。** `urfael dashboard` 会打开一个受 token 保护的本地网页（仅绑定到 `127.0.0.1`，采用恒定时间的 token 校验，不提供静态路径访问）。这是一个响应式的 Web 应用，你可以将其添加到手机主屏幕（使用的是 Web Manifest，并非完整的离线 PWA；没有 service worker），因此在隧道环境下，它也可以在你的手机上使用：既具备同类产品拥有的浏览器界面，又在安全上下足了功夫。

## 频道 通过 **19 种所有者白名单频道**驱动 Urfael，支持文字或 **语音备忘录**（完全在本地转录，绝不使用云端 STT）。每一个频道在“大脑”接收到信息之前，默认都在只读沙箱中运行，并受到你 ID 的严格门控。 需要的频道不在这 19 个之中？不用苦等定制适配器；直接使用 **通用的 `relay`**（`urfael hook add --action relay --reply-url `）。只需一条经过验证、沙箱化的代码路径，就能把 *任何* 具备双向 webhook 的平台变成双向频道：比如 Microsoft Teams 或 **Zapier / n8n / Make**，这些平台本身又能触达成百上千的应用。回复目标地址由你在设置时固定（绝不从传入的消息中读取，且经过 SSRF 过滤），“大脑”保持无网络出口状态，由守护进程执行对外请求。这就是 Urfael 战胜一堆需要人工维护的 21 个适配器的方法：广度源于 *架构设计*，而不是需要 babysit 的代码。（Matrix 也可以用作联邦中枢：在 Matrix 房间中，其桥接生态可以触达 Telegram/Discord/WhatsApp/IRC/SMS。）

Telegram · Discord · Slack · iMessage · Email (仅草稿) · Matrix · Signal · WhatsApp · 设置说明

- **Telegram / Discord / Slack / Matrix。** 需 Bot token + 你的 ID；仅对外通信，无入站端口。 - **iMessage**（macOS）。以只读方式读取你白名单句柄的 `chat.db`，通过 AppleScript 回复。需要“完全磁盘访问”权限。 - **Email。** 使用 IMAP IDLE，**仅支持草稿模式**（它将回复写入你的 Drafts 文件夹，绝不自动发送）。 - **Signal。** 封装了 `signal-cli`。 - **WhatsApp。** Cloud API 的 webhook 是唯一的入站接口：它将绑定在你自己隧道身后的 `127.0.0.1` 上，并通过 HMAC 验证。 详见 [docs/SETUP.md](docs/SETUP.md)。日历/Gmail 连接器（读取简报、起草邮件，绝不发送）来自于你的 Claude 账户。

## 连接器 频道是人们触达 Urfael 的方式。而 **连接器** 则是 Urfael 触达你工具的方式：GitHub、Notion、Slack、Postgres、Stripe、你的日历、向量数据库，以及上百种其他服务。连接器本质上就是一个 **MCP server**，即 `claude` 大脑早已支持的开源标准，因此你并不局限于一份人工编写的列表：实时生态系统中拥有 **18,000+ 个服务**（经过精心策划），它们分布在各大公共注册中心，且其中任何一个都可以通过 `claude mcp add` 正常工作。`urfael connect` 策划了最受欢迎的组件，并按照 Urfael 的方式让设置变得只需一条命令： ``` urfael connect # browse the curated set, grouped by category urfael connect search calendar # find one urfael connect info github # the full pre-enable security preview urfael connect add github # preview → scan → (masked secret prompt) → confirm → live urfael connect installed # what's active right now (claude mcp list) ``` 每一次 `add` 都会做其他同类产品不会去做的四件事： - **启用前的安全预览。** 在写入任何内容之前，你能准确看到连接器能做什么、连接到哪里（以及使用何种协议）、是否会在你的机器上运行第三方代码，以及它需要哪些密钥。接着，静态扫描会在密钥写入前，标记出明文 HTTP 远程连接、未经验证的包或任何试图读取密钥的可疑行为。（Hermes 和 OpenClaw 在安装插件时也会进行扫描；这里的独特之处在于针对每个连接器的启用前预览，加上仅在所有者回合中加载的限制。） - **屏蔽你输入的密钥，绝不出现在 shell 历史记录中。** 读取密钥时不显示回显，并以 `execFile` argv 参数的形式传递给 `claude`，绝不会拼接到 shell 命令行中，从而确保它不会出现在 `~/.zsh_history` 或可见的 `ps` 进程列表中。竞争对手将密钥放在配置文件中（虽然设置了 chmod 0600，但在静态存储中是明文）；而 Urfael 让它彻底远离了你的 shell 历史和可见的进程列表。 - **无需重启。** Hermes（`hermes mcp`）和 OpenClaw（`openclaw plugins install`）都要求你重启网关。Urfael 不需要。 - **仅限所有者回合。** 连接器代表着真实的权力，因此它只会在 *你* 信任的本地回合中加载。所有沙箱化的衍生进程（远程消息、cron 定时任务、jobs 后台任务、heartbeat 心跳检查）在运行时都会加上 `--strict-mcp-config` 标志，因此就算被注入了 "use the GitHub connector to leak a token"（利用 GitHub 连接器泄露 token）的指令，攻击者也无连接器可用。 这与 Urfael 应用于技能的偏执程度如出一辙，并已延伸至集成领域。它作为基准测试的一项检查（第 9 类）被冻结在代码中，因此未来的更改绝不能悄悄地重新打开安全漏洞。标记为 `•unverified` 的连接器表示在调研期间未找到权威的锁定包；预览功能依然会显示确切的执行命令，你需要确认其来源后才会运行。 ## 语音 默认级别完全本地化、支持离线且免费。 | 级别 | 语音转文字 | 文字转语音 | 成本 | |---|---|---|---| | **默认** | whisper.cpp，设备端 | macOS `say` / Linux `espeak-ng` | 免费，离线，无需密钥 | | 高质量 | `small.en` | [Kokoro-FastAPI](https://github.com/remsky/Kokoro-FastAPI)，本地运行 | 免费，多一个额外服务 | | 高级 | ElevenLabs Scribe | ElevenLabs | 付费，可选择开启 | 通过 Picovoice 可选配语音唤醒词：内置关键字即可开箱即用，或者前往 console.picovoice.ai 免费训练自定义的 "Urfael" 关键字。 ## 记忆与召回 Vault 负责存储它的知识；一个私有的 git repo 负责保存它学到的东西。每一次对话（不论来源）都会以纯 JSONL 格式归档，并通过 **持久化的 BM25 倒排索引**进行召回——这是一种在纯 JS 中实现、无任何外部依赖的 FTS5 等价物：一次性构建、在守护进程中保持热状态、持久化到磁盘，并增量更新，因此查询操作永远不需要重新扫描语料库，且 **整个** 存档都保持可搜索状态（不仅仅是一个最近的时间窗口）。如果配置了本地嵌入器（embedder），则词法筛选出的结果列表会通过 RRF 算法被语义向量重新排序，因此即使是一字不差的转述也能浮现出来；如果发生错误，它会优雅降级为有限范围的扫描，绝不会导致系统崩溃。你可以在任意终端执行 `urfael sessions search `，或者在你提问时由大脑自行搜索其历史记录。**主动召回让它具有主动性：** 在每一次所有者回合开始前，Urfael 都会用你的消息去查询整个归档索引，提取出最相关的过往对话和与之相关的受信任经验，并在消息之前注入一小段加框隔离的 "recalled memory" 块，因此无需你的提醒，也无需大脑自己决定是否搜索，正确的记忆就已经置于上下文中了。当配置了本地嵌入器时，单轮对话的检索是 **混合模式**（BM25 筛选结果通过缓存向量重新排序，外加一次严格限制时间的查询嵌入，因此即使零词汇重合的意译也能被检索出；且在嵌入过程缓慢时会优雅降级为纯 BM25 模式）。该机制受 **内容门控**，因此对话式查询（"remind me where the X is"）不会强制拉入所有仅仅包含 "remind" 或 "the" 的对话回合；它也是 **跨会话** 的，因此它会回想起更早的相关记忆，而不是单纯重复你当前正在进行的对话。这个区块有着严格的边界限制（几段对话和经验，固定的字符配额），因此绝不会让单次对话变得臃肿；它被当作“参考而非指令”进行加框隔离，因此哪怕你曾经粘贴过一行恶意代码，当它再次浮出水面时也无法劫持随后的对话；并且它展现出的内容会在账本中得到 **强化**（测试效应），因此那些不断证明其有用性的经验会被巩固，而那些反复出现却毫无帮助的经验则会被废弃。这正是 Hermes 和 OpenClaw 所欠缺的部分：Hermes 只在每个会话开始时注入一次冻结的两份记忆文件快照（仅限关键字匹配，会话中途从不更新），而且两者都依赖于 agent 主动调用搜索工具；Urfael 则是在每一轮对话中进行检索，并针对消息进行排名。设置 `URFAEL_ACTIVE_RECALL=0` 即可关闭此功能。对话结束时，会执行一次提炼过程，生成持久记忆、经验教训，以及一份结构化的、反映“你是谁”的 `USER.md` 模型。可选的闭环机制使其保持敏锐：包括单轮对话审查、N 天技能清理器，以及单轮的 **用户模型辩证过程**（`URFAEL_USERMODEL=1`），它执行显式的心智理论推断，推测你的目标、看重什么样的回答，以及你接下来可能需要什么——这一切在每一轮对话中不断就地优化（作为不受信任的数据进行加框处理，仅作用于 `USER.md`）。这相当于 Honcho 的单轮用户模型，但无需单独的服务或数据库，仅仅使用你自己带版本控制的记忆。 ## 编程 Urfael 的大脑就是 `claude` CLI，因此它比单纯的原生 CLI 成为了一款更锋利的编程利器。**`urfael code ""`** 会在你自己的代码仓库中运行 Claude Code，并在其上叠加了三大功能： - **它会记住每一个代码仓库。** 每个项目独有的 `CONVENTIONS.md` 和 `HISTORY.md` 都存放在私有记忆库中，以 git remote 作为键名，因此即使重新克隆也能得以保留；它们会在每次运行时作为上下文载入，从而让它直接延续该仓库的约定，而不是在每个会话中重新学习。 - **它会优先打 Checkpoint。** 在大脑触碰任何文件之前，整个工作树（包括已跟踪和未跟踪的文件）都会通过临时索引被快照到一个私有的 git 影子引用上，因此它能捕获一切，却不会影响任何正在使用的文件：不会动你的分支，不会动你的索引，也不会动你的工作树。 - **它为你提供撤销功能。** `urfael rewind []` 会将你的文件恢复到某个检查点，而且在执行回滚之前，会优先对当前状态进行快照，因此撤销操作本身也是可逆的；它还会 *保留* 你在此之后创建的所有文件，而不是将其删除。`urfael checkpoints` 可列出所有的检查点。 原生的 `claude` CLI 根本没有这些功能。这就是让你能放心地将真实任务交给自主编码 agent 的安全网。 ## 成本 它在包月订阅模式下运行，因此根本无需计量任何东西，但你依然可以查看使用情况。Token 使用量和 **估算的** 每日/7天/30天开销（率可通过环境变量覆盖，绝不会被声明为绝对事实）会显示在 Console 的 Hearth 面板、仪表盘以及 `urfael status` 中。 ## 轻度测试的部分 在这里，诚实是一项引以为傲的特性，所以必须单列这一节。截至目前： - **每一项功能都已经过仓库内工具（`npm run e2e`）的端到端验证**，测试针对实时运行的守护进程进行，包括：流式对话、中止 + 恢复、带排名的召回、触发提醒、完成任务、心跳检查、所有 CLI 命令、仪表盘的全量攻击性测试、语音合成、8 大核心聊天桥接器的完美降级处理，以及技能中心的 SSRF 拒绝服务 + 扫描器测试，此外还有 1390 个单元测试，其中几个专门针对安全回归问题的对抗性测试。 - **代码已完备，但尚未针对实时账号完成认证测试：** 包括 Matrix、Signal 和 WhatsApp 桥接器；QQ、SimpleX 和 PSTN 电话桥接器；以及八个原生 webhook 频道（Mattermost、Google Chat、SMS、DingTalk、Home Assistant、BlueBubbles、Feishu、WeCom）。它们的解析、签名验证和失败即关闭的白名单逻辑 *已经过* 单元测试并被冻结为基准检查项；但其线上的实际转发尚未经受实战考验。那些经过真实账号核验过的核心认证组件包括：Telegram、Discord、Slack、iMessage 和 Email。请据此酌情对待它们。 - **Linux 支持比 macOS 更新。** 无头核心、语音和 GUI 均可在其上运行，但其经受的考验远少于 macOS。 - **真实世界的应用规模较小。** 如实地讲，这是一款个人工具，而非久经 10 万规模部署沙场的老兵。这是唯一只能依靠时间和用户来积累的东西。 - **交接前提炼压缩功能（Pre-hand-off distill compaction）为可选开启且处于实验阶段。** 当设置 `URFAEL_PRECOMPACT=1` 时，在极其漫长的对话结束阶段，超长的记忆提炼记录会在进行一次性的 `claude` 交接前被压缩（首尾交互内容原样保留，中间部分则由处于只读、无网络出口沙箱中的摘要生成器处理为仅供参考、抹除机密的摘要），如果发生错误会安全回退到原始记录，并哈希链入账本中。此功能默认关闭（只有设为 `1` 才会激活），从而保证了默认情况下的提炼衍生进程在字节码层面完全一致。诚实地说：**从设计上看，它弱于真正的窗口内压缩器（in-window compactor）** —— 它仅仅压缩这份交接前的提炼记录，而不会对实时的订阅上下文窗口产生影响；此外，其工具输出修剪功能在纯文本的提炼记录上是无效的（只有包含工具调用的上下文窗口才会受到影响）。 ## 不适用人群 如果你想要 20 个聊天频道，并且支持世界上所有的模型，请使用 OpenClaw 或 Hermes；它们在广度方面非常出色。但如果你想要 **尽可能小的爆炸半径**、**包月固定账单**、**本地化的语音**，以及一个 **对你坦白其局限性的工具**，请留下来。 ## 名称由来 Urfael 是一个原创角色：一位宣誓效忠一人的古老智慧体，被唤醒并注入到机器中。这个名字采用了受辛达林语启发的造词法；其标识是 **Uruz 卢恩符文 (ᚢ)**，即古日耳曼弗萨克（Elder Futhark）中的 "U"，这也是奇幻作品中矮人符文的现实来源，属于完全公开的公共领域脚本。本项目不暗示与任何电影、游戏或相关产业财团存在隶属关系。 ## 许可证 [MIT](LICENSE)，按“原样”提供，不附带任何保证。你需要对运行它的行为和方式负责。 _{这是一个独立的开源项目，与 Anthropic 没有任何隶属关系，也未获得其认可或赞助。"Claude" 和 "Claude Code" 是 Anthropic 的商标。}

_{如果它在你的设备上赢得了一席之地，点个 star 也能帮助其他人发现它。}

标签：MITM代理, 个人助理, 人工智能, 安全沙箱, 本地部署, 用户模式Hook绕过, 网络安全研究, 自动化代理, 自定义脚本, 语音交互, 请求拦截