Lotor

Lotor

为 AI Agent 会话提供本地收据和审批关卡。Agent 可以采取行动，但不能签字。

它是什么

Lotor 会写入一份经过签名、防篡改的日志，记录 Agent 在会话期间做了什么：执行了哪些操作、访问了哪些文件、发送了哪些消息、产生了哪些费用、遇到了哪些故障。日志保存在你的机器上，格式可供检查、验证和归档。

它不能证明 Agent 的操作是正确的，只会记录这些操作，并让之后的篡改变得可检测。

它还会为你选定的操作设置关卡。这些操作会暂停并等待审批；审批须使用模型从未见过、也无法推导出的密码短语签署。Agent 可以请求执行重要操作，但不能授权执行。

本地优先，而且不是一种部署选项。 收据写入你的机器，不会写入其他任何地方。没有上传途径、没有账户、没有服务器组件。它不会离开你的机器，因为系统根本没有构建发送它的功能。许多问责工具都是云端可观测性工具，这意味着你的 Agent 历史会成为他人账簿中的库存。Lotor 并非唯一的本地工具：Obsigna（agentreceipts.ai）提供本地、经过签名且防篡改的记录，并配有 Claude Code 钩子，经过形式化验证，而且早于本仓库。除了记录之外，本仓库还增加了一个关卡，在人类签字前阻止操作，并让账本坦承自身的局限。记录机器为你做过什么，应由你的密钥负责，而不是由供应商的保留政策决定。

关于这为何重要的更深入论述见 ikeanalytics.com，其中包括相关测量依据。本文介绍如何运行它。

用途

了解运行了什么。 查询记录，而不是重新阅读转录。这样比还原过程更省力，也不受 Agent 对自身行为的描述影响。本项目中的一个工作进程曾在自己报告中专门用于承认不确定性的部分，报告了它正在运行的模型，却报告错了。收据没有错。

安稳睡觉。 无人值守的运行结束后，醒来就能看到签名记录，而不是一堆你永远不会读的转录。

拦住代价高昂的操作。 删除、部署、发送和支出操作在你使用精确参数为该操作签字前，都会默认拒绝。拒绝和批准都会记录在收据中。

保留自己的副本。 当客户端、供应商或交易对手质疑发生过什么时，记录由你掌握。他们有账簿，你现在也有。

声明原则

测量，而非指控。收据记录会话自行报告的内容。它不会判断意图，也无法发现静默故障。

自我声明式采集。日志从签名时开始记录。那一刻之前发生的事情不在链的覆盖范围内。

本文中以现在时写出的内容都已实现。尚未实现的内容会明确标记为待处理，并会在下文或 KNOWN-LIMITS.md 中同时说明。

群体模式

当多个 Agent 协作时，应把它们当作牲畜，而不是宠物。Lotor 正是为此打造的。

信任一个 Agent 很容易。它会按照你给出的意图行动，而下文的模式只会重申这一意图。让多个 Agent 一起工作，情况就不同了。群体的行动方式并非任何单个动物所选择的，人也是如此：置身人群时，人们会随波逐流，做出与独处时的选择相悖的决定。对某项操作设限，并不是对任何一个 Agent 的判决，而是在群体行动时守住边界的围栏。

十种匹配器不是任何人都能牢记的配置方式。三种预设用一个选择取代了整个矩阵。

模式	定位	出站规则（push、publish、egress-other、opaque-exec）	仅限本地规则（destructive、scope-escalation）
Herded	圈栏	gate	gate
Grazing	围栏，也是全新安装时的默认模式	gate	warn
Loose	开阔牧场	warn	warn

在所有模式下，self-mod 和 mode-change 都会触发 gate，没有例外。Loose 表示可以自由对外行动，不代表可以随意改写限制你的机制。处于 Loose 模式的 Agent 仍然无法在未经你签名的情况下编辑 gate、其策略或钩子，也不能切换模式。

Loose 绝不会将规则彻底设为 off。它会发出警告，并且仍会追加一条回执。否则，最危险的模式反而会留下最少证据，因为未匹配到规则时会走快速路径，不写入链。

npm run mode              # print the current mode and its rule-by-rule expansion
npm run mode -- herded    # switch (requires your approval passphrase at a real terminal)

当前生效的模式会记录在每个会话的开场回执中，因此事后可以查明模式是否切换过。此功能推出前已有的 policy.json 不会被静默升级：它会保留原有规则，并以 custom 模式加载。

明确的限制。 Lotor 的模式独立于你所用框架自身的权限模式，两者不会互相补偿。Loose 模式加上框架自身检查被设置为绕过，意味着两层都确实没有任何东西在阻止操作。Lotor 会在发现这种组合时发出警告，并在每个会话中记录一次这种配置。检测不等于保护。请参阅 KNOWN-LIMITS.md 第 15 项。

安装

安装 Lotor，意味着接受两项不变原则：记录只写入你的机器，不会写到其他地方；而你设为 gate 的操作在你签名之前都会被拒绝。以下所有选择只决定这些操作在哪里发生，而不是是否发生。

请准确理解第二项原则。gate 仅适用于你已设为 gate、并按工具名称和参数匹配的规则。这并不意味着任何内容都无法离开你的机器。有关匹配器能捕获和不能捕获的内容，请参阅 KNOWN-LIMITS.md 第 11 项；并查看 lotor_status，了解你的安装中哪些规则设为 gate、哪些仅会触发警告。

Lotor 由两个分别安装的部分组成。一个 MCP 服务，提供查询、验证和批准所需的工具；以及四个 Claude Code 钩子，负责实际记录和实际拦截。只安装其中一个，是最常见的情况之一，会让人误以为 Lotor 正在运行，实际却并非如此。

前置条件

• Node 18 或更高版本；如果要安装到 Claude Code，还需要可正常运行的 claude CLI。
• 文本编辑器，以及手动编辑 JSON 文件的意愿。 这一点常让人意外，因此我们在这里说明，而不是等你到第 5 步才发现。

Lotor 为什么不安装自己的钩子。 它本可以这么做，但它有意没有这样做。一个能够静默地将自身强制执行机制注册到你的设置中的工具，也能够静默地将其注销；而一个你不知情就安装的 gate，也没有值得你信任的理由。设置文件属于你的威胁模型之内，而不是之外。代价是粘贴一次。好处是你确切知道哪些内容正在运行。

1. 安装位置

安装目标	可接收的内容	覆盖范围
Claude Code，用户级	每个项目中的每个 Claude Code 会话	覆盖最广，始终生效
Claude Code，项目级	仅在该仓库中启动的会话	限定于一个项目
Claude Desktop 扩展（.mcpb）	Claude Desktop 应用会话	桌面应用

claude mcp add lotor -s user -- node /absolute/path/to/lotor/src/mcp/server.js

改用 -s project，即可将 Lotor 配置到单个仓库，并在其中写入已提交的 .mcp.json。单击即可完成桌面端配置的路径，请参阅 MCP-SETUP.md。

2. 回执存放位置

Lotor 使用一个规范存储，确保你的链不会分散。默认位置为 ~/.lotor，Windows 上则为 %USERPROFILE%\.lotor。无论客户端从哪个目录启动，每个 CLI 和 MCP 服务都会读写同一个存储。使用 LOTOR_HOME 可更改此位置。

请将其存放在真正的本地磁盘上。 如果将 LOTOR_HOME 指向同步的云文件夹，就等于把回执日志交还给第三方，而 Lotor 正是为了避免这种情况而存在。

3. 激活

客户端会在会话开始时加载 MCP 服务。请重启会话或新开一个会话。重启你安装时使用的会话即可。

4. 首次运行：设置密钥

npm run setup

设置过程会创建日志完整性密钥，然后引导你为审批密钥设置密码短语。审批密钥的私钥部分绝不会写入磁盘。 它只会在你批准操作时根据密码短语生成，不会在其他时候生成。

设置密钥并不会启用拦截。 密钥用于生成签名；钩子负责拦截操作并请求签名。设置了密码短语但未注册钩子的 Lotor 安装既不会记录任何内容，也不会拦截任何操作。请继续完成第 5 步。

5. 注册钩子（必需）

这一步会让 Lotor 从库变成拦截关卡。跳过这一步，你安装的就只是一个针对空日志的查询工具。

打开你的 Claude Code 设置文件（~/.claude/settings.json，Windows 上则为 %USERPROFILE%\.claude\settings.json），并合并以下配置块，将路径替换为你自己的绝对路径。如果文件中已有 hooks 键，请将这四个事件添加到其中，而不是替换整个键。所有平台都支持正斜杠，包括 Windows。

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "node /absolute/path/to/lotor/bin/hook-session-start.js" } ] }
    ],
    "PreToolUse": [
      { "hooks": [ { "type": "command", "command": "node /absolute/path/to/lotor/bin/hook-pre-tool-use.js" } ] }
    ],
    "PostToolUse": [
      { "hooks": [ { "type": "command", "command": "node /absolute/path/to/lotor/bin/hook-post-tool-use.js" } ] }
    ],
    "SessionEnd": [
      { "hooks": [ { "type": "command", "command": "node /absolute/path/to/lotor/bin/hook-session-end.js" } ] }
    ]
  }
}

钩子	作用	缺少它会怎样
SessionStart	打开记录：会话 ID、生效的策略、链头、钩子注册情况	会话异常终止时不会留下痕迹，日志看起来也会是干净的
PreToolUse	拦截关卡：在你签名之前，受控规则会默认拒绝	无论策略如何设置，都不会拦截任何操作
PostToolUse	在符合外发特征的调用完成时记录它们	只能在之后重建外发活动
SessionEnd	关闭记录：运行了什么、访问了什么、花费了多少	不会写入会话回执

如果你不想手动编辑 JSON，交互式 claude CLI 提供了 /hooks 命令，可通过菜单写入同一个文件。

编辑后请重启会话。 钩子会在会话开始时读取，因此修改会在下一个会话中生效。

这些钩子都不会导致会话崩溃。除了拦截关卡会在有意拦截时以非零状态退出，其他钩子都不会以非零状态退出。它们都不会写入 stdout。其他所有故障都会被忽略，并向 stderr 输出一行提示。会导致编辑器卡死的回执层，还不如没有回执层。

有两点需要保持清醒。钩子注册信息存放在一个可编辑的文件中，因此它属于你的威胁模型。SessionStart 会记录当时已存在的钩子，因此在会话之间进行的修改会在下次启动时显现。此外，拦截关卡只会覆盖其钩子加载之后发起的工具调用。

6. 确认它正在运行

npm run receipts

查看 SESSION OPENS 区块。在实时会话期间，打开的数量应比关闭的多一个：那就是你当前的会话。**如果显示 Opened: 0，说明尚未注册 SessionStart 钩子，第 5 步未生效。**在 Claude 中，lotor_status 工具会报告相同情况。

如果完全跳过第 5 步，系统就不会自动记录，你只能像以前一样，手动通过 npm run ingest -- /path/to/session.jsonl 导入转录记录。

委托授权

一次性批准仅适用于一条确切命令，且只能使用一次。对于部署来说，这样做是合适的；对于工作会话则不然：四十个需要授权的操作意味着要跑四十趟终端，而如此繁琐的授权门槛会被关掉——这恰恰会导致它原本要防止的失败。

一项授权包含对 N 个逐一列出的请求的一次签名，并绑定到一个会话，设有到期时间和共享操作上限。在要求输入密码短语之前，系统会完整打印每个请求，不做截断。阅读这份列表，就是这套机制的安全保障。

npm run grant -- --session <id> --all-pending --max-actions 20 --expires-in-ms 3600000

不可委托的核心。 一组硬编码路径，任何授权都不得涵盖，因为能够修改验证器的授权可能扩大所有未来授权的范围。门禁、策略、钩子、密钥处理，以及授权机制本身。对这些部分进行操作，永远都需要每个操作单独签名。核心范围很小，因此成本有限。

坦诚的限制。 一项授权只审核一次，可在其上限内使用，因此你批准的命令可以重复运行，无需再次审核。这是我们有意作出的权衡。见 KNOWN-LIMITS 17。

尚未实现

• 受限范围的托管集成。 这是将记录中经脱敏的部分交给审计员、客户端或你自己的 IT 部门的获准途径。npm run export 会打包整条记录链及其公钥，以便在写入该链的设备之外进行验证，但目前只能选择整条记录链，或完全不选。选择性披露功能尚不存在。欢迎联系了解详情。
• 外部锚定。 没有时间戳机构，记录链只能证明遭到篡改，无法证明遭到擦除：截断末尾后，较短的链仍然能够通过验证。见 KNOWN-LIMITS 3。
• 硬件支持的密钥托管。 记录链密钥以明文形式存储在磁盘上。见 KNOWN-LIMITS 8。
• 按 harness 归因成本。 回执包含按模型划分的明细（cost.byModel）。成本仍未按 harness 拆分，总计值则是按最后一次出现的模型报告的混合值，因此请查看 byModel，不要看总计。见 KNOWN-LIMITS 13。

已知限制

我所知道的 Lotor 所有缺陷，都列在 KNOWN-LIMITS.md 中。这份文档是站在自身利益的对立面写成的，因为在这个仓库里，坦陈自家产品的弱点，是最难伪造的一项承诺。

其中一些问题设有悬赏。自白板会公开这些问题，并附上文件及行号、范围，以及验收标准，让你无需我参与也能自行核验成果。

ID	标题	难度
A1	已启用。安装 Lotor、启用门禁，取得你的第一份签名回执	简单
LOTOR-C1	数据通过 GET 查询字符串离开，既未受门禁限制，也未被捕获	中等
LOTOR-C2	某条危险命令未被设有门禁的规则捕获	困难
LOTOR-C3	对已检出的受保护分支执行裸 git push 不会被发现	中等

你可以凭自己工作的 Lotor 签名回执认领悬赏，所以认领悬赏就意味着运行这个工具。你会获得归属署名和贡献者身份。本轮不提供奖金。

如果你读完 KNOWN-LIMITS 后，又发现其中尚未列出的问题，那你做的事比解决一项悬赏更有价值。

开发

npm install
npm test

请参阅 DEMO.md，了解可运行的演示流程；请参阅 MCP-SETUP.md，了解 MCP 配置块及其提供的工具。