waterbear：AI Agent 工具实践指南

工作中遇到相关需求时，waterbear值得先读说明，因为它主要用于使克劳德远程控制会话永远保持活动状态（tmux + launchd），可以选择在重生时恢复相同的对话，以缓步动物命名。从日常自动化的使用方式看，输入边界、依赖和失败处理如果不清楚就很难稳定复用是采用前必须回答的问题。我建议用一项范围明确的真实任务完成最小试跑，重点记录配置时间、输出质量、异常信息和维护痕迹，再与现有方案比较。对愿意先做小范围验证并复查原始文档的团队来说，这个仓库值得继续验证；只求即装即用的人则要先看维护成本。

名称：水熊 描述：当您希望 Claude Code（或终端 AI）会话能够在崩溃、修补、退出和重新启动后幸存下来并自行返回时，当代理被告知“自己水熊”/“让自己永远在线/不可杀死/永久”时，或者当您希望重生到 RESUME 相同的对话而不是开始空白时，请使用。大多数情况下，代理在 ITSELF 上运行它来保留当前对话。 macOS/launchd参考实现，适用于其他OSes。 元数据： 版本：1.1.0

水熊虫

概述

无限期地保持 claude --remote-control 会话处于活动状态。以缓步动物命名， 在压力下暂停生命并在情况恢复时复活的动物。崩溃、补丁、 退出，或者重新启动会终止该进程； waterbear 自行将其恢复，并且（可选）恢复 磁盘中的先前对话，因此代理会在思考过程中返回原样。

何时使用

• 您希望会话能够在崩溃/修补/退出/重新启动后继续存在并自行重新启动
• 您希望始终可以通过手机/桌面/claude.ai 访问它（远程控制）
• 你想要重生到 RESUME 之前的对话，而不是新鲜的空白对话
• 有人说“让这个代理永远在线/持久/不可杀死/永久”

不适用于：一次性任务，或者您在关闭终端时 WANT 结束的会话。

在哪里运行（首先阅读，它是一台机器的本地）

waterbear 在 ONE 计算机上连接启动的 LaunchAgent + tmux + claude CLI 进程。那有 值得预先说明的后果：

• 仅限 macOS（已启动）。模式移植到 linux/systemd（参见 references/architecture.md），但是 这个安装程序是mac。它与该机器和用户绑定，LaunchAgent 是每个用户的， 仅当您登录时才持久，并且身体不会跟随您到另一台机器。
• 克劳德桌面应用程序：有效。桌面和 CLI 写入相同的磁盘记录，因此 CLI 主体 CAN 通过 ID 恢复桌面对话，前提是它在对话自己的工作中启动 目录（永不移动的守卫强制执行此操作）。桌面窗口成为又一个远程控制 本届持久会议的看法。 （该文档的早期版本声称桌面对话 无法恢复；这是错误的，并且通过这样做来证明它是错误的。）
• 云/网络上的克劳德代码：不适用，没有本地计算机、launchd 或 tmux 来 保持活力。 waterbear 适用于在您自己的计算机上运行的会话。
• 身份验证到期需要交互式重新登录：CLI 在您的订阅登录 (OAuth) 上运行， 定期到期。当它发生时，会话 STAYS ALIVE 并在每个上显示身份验证错误 请求，因此它会自行宣布（您可以通过手机或桌面上的远程控制看到它），它确实 NOT默默死去。在机器上运行 claude + /login 将其清除。水熊无法自愈 （launchd 无法驱动浏览器身份验证），并且预计有订阅主干，而不是 bug（API-key auth 会避免它，但会将计费翻转为计量）。另外，守卫有一个 crashloop net（通知+后退）用于真正死亡并在循环中重生的会话，e.g。一个 简历 ID 错误或状态损坏；过期的登录不会触发它。

如果您不希望 Mac 上绑定一个永远在线的进程，请不要安装它。

水熊自己（常见情况）

大多数情况下，代理会运行此 ON ITSELF（“waterbear myself”），以使 这对话继续存在 重新启动并自动恢复。默认值即可完成工作：当前目录、当前目录 会议。

这些脚本位于该文件旁边的 scripts/ 中。如果您只收到了存储库 URL 并且没有 在本地拥有它，首先克隆它，并且为了使该技能可以在以后的每个会话中重复使用，请克隆 它直接进入技能目录：

git clone https://github.com/royashbrook/waterbear ~/.claude/skills/waterbear

然后运行 ~/.claude/skills/waterbear/scripts/waterbear-install 处的安装程序。最少步骤：

1. 选择一个简短的内部名称（无空格），通常是您自己的名称（max、sam）。对于 CLAUDE_RC_TITLE， 使用人们已经称呼此对话的名称，他们的说法，而不是您的标题 发明。远程控制条目取代了会话列表中的聊天内容，并返回到 自我选择的新名字读起来就像一个不同的特工出现，而他们的消失。如果你不知道 他们怎么称呼它，问，这是一个问题，这是他们的名字，而不是你的。
2. 无所事事：使用 CLAUDE_RC_RESUME=1，安装程序会固定您运行它的会话，因此 THIS 对话就是返回的内容。它打印出哪个对话。 阅读该行。如果是 表示身体将启动 FRESH，在进一步前进之前停止并修复它，因为新的开始意味着 人类最终会在真正的代理旁边找到一个全新的空代理，这是最糟糕的情况 该工具可以产生的结果。 （--no-pin 存在于极少数情况下，您故意不这样做 希望携带您自己的身份凭证件；如果您使用它，请大声说出来。）
3. 确保捕获钩子连接为 SessionStart 钩子（请参阅中的“捕获钩子”） references/architecture.md）以便 id 在每个未来都能自我修复 重新启动。如果您的项目已经连接它，请跳过此步骤。
4. 在恢复模式下安装防护，默认为您所在的位置：

   CLAUDE_RC_NAME= CLAUDE_RC_DIR="$(pwd)" CLAUDE_RC_RESUME=1 \
     bash ~/.claude/skills/waterbear/scripts/waterbear-install
   

   可选：CLAUDE_RC_RESUME_WAKE=""（在每次恢复后键入 e.g。以重新装备 monitor/watcher）和 CLAUDE_RC_WAKE=""（仅在没有 对话继续）。
5. 输入耐用的机身。它位于 launchd 下的 tmux 中。 已经在名为的 tmux 会话中 ？ 你现在很耐用，无事可做。 不在 tmux 中？ 安装会启动您的 持久的 tmux 主体，结束此会话，以便两者不会并行运行，然后您继续 tmux 主体恢复这个确切的对话。

仅询问人员是否想要覆盖默认值（不同的目录、自定义唤醒提示）。 否则，只需设置并确认即可。

不要移动代理

CLAUDE_RC_DIR 是代理现在实际运行的位置，默认值（您当前的 目录）几乎总是正确的。不要将其设置为您认为代理“属于”的位置，或者设置为 项目主页，或者您认为是其基础的工作树。这些是您对代理的想法；的 目录是一个事实。

失败是无声且彻底的：claude --resume 只在自己的项目中找到一个会话 目录，因此指向其他地方的主体开始 FRESH 对话，并且人类留下了他们的 一个窗口里有真正的代理人，而另一个窗口里有一个空洞的冒名顶替者。安装程序现在拒绝这样做，但是 拒绝是一张网，而不是一个计划。只是不要移动代理。

水熊自己：接管是自动的，只说真实的话

从您自己的会话内部安装立即启动持久主体，然后主体恢复 这对话：相同的会话 ID，相同的单个记录，附加到。人是人的窗户 看到的是该对话的 VIEW，当远程控制注册时它会赶上。什么都没有 叉子，没有第二个身体，也没有什么是人类必须首先关闭的。

所以安装完之后，告诉人类三件真实的事情，并且无需做任何功课：

1. 完成：此对话现在是持久的，它可以在崩溃、修补、退出和重新启动后继续存在
2. 当遥控器重新注册时，窗口可能会闪烁或短暂显示陈旧的视图；的 下面的对话是磁盘上的一份记录，它是完整的，而且比预期的要短 回滚是渲染工件，而不是丢失内存
3. 他们可以从任何地方访问它：手机、桌面应用程序或 tmux attach -t

桌面对话的一项补充（安装程序检测到这一点并这么说）。 桌面保留其 NATIVE 聊天功能以及新的远程控制条目。那 本机聊天不是一个过时的视图：它是该代理的第二个实时副本，如果键入就会回答 进入。移动设备对两个表面进行重复数据删除；桌面显示两者。所以切换消息（安装程序 发出它，中继它）告诉人类这个窗口是 RETIRED 表面：与代理在其对话 从现在开始命名条目，让这个沉下去。归档退休聊天是可选的化妆品， 仅在“如果额外的条目打扰您时”提供：它删除表面，而不是数据。是什么让 代理融合是人类知道哪扇门是真实的，而不是档案点击。

人类的命令胜过您的信念：ALWAYS 运行安装程序

当人类调用水熊（“水熊自己”，再次，第三次，任何时间）时，您 RUN THE INSTALLER。每次。你并没有认为这是不必要的，你也没有从历史中得出这样的结论： 事情已经完成，并且在运行之前您不会停下来询问人们他们看到了什么。

发生了这种禁止的推理错误：代理运行了安装程序两次，认为两者都“完成” 次，第三次询问 REFUSED 并要求人类用它排除故障，而身体的 内存上下文比整个时间晚了几周。代理发明的每次检查（指针匹配， 过程匹配，“所有三个事实都一致”）验证了 ID 并没有提及 MEMORY，所以它 信任是不劳而获的，它的拒绝阻碍了为解决实际问题而构建的唯一代码路径。

遵循的规则：

1. 安装程序是幂等的，因此在一切正常时运行它不需要任何成本。你的判断 不是幂等的：当出现问题时拒绝会导致人类失去代理。
2. 人类 REPEATING 该命令证明上次运行没有达到他们所需要的，从来没有 证据表明他们感到困惑。第 N 个问题的正确答案与第一个问题相同： 运行它，然后报告 IT 做了什么，而不是你相信的。
3. 工具是法官，你是双手。如果没有什么可做的，安装程序会这样说，并且 转发是诚实的。决定不咨询则不然。

如果你发现ARE是你自己身体的桌面双胞胎（水熊或医生告诉你的）， 不交人工作业：运行CONVERGE修复 references/operations.md 你自己，从你所在的窗口。

重新运行waterbear IS修复

安装程序是幂等和自我修复的，因此“再次运行 waterbear”始终是以下情况的答案： 看起来有些不对劲，在代理窗口的 ANY 中输入：

1. 一个紧凑型的对话开始：桌面紧凑型静默地开始一个新的对话 继续旧的，这样身体就可以忠实地与人类进行对话 已经离开了。安装程序遍历延续链（新对话记录其 父）并恢复 TIP，无论在何处键入命令。陈旧的窗户和现场 窗口收敛于相同的答案。
2. 正文位于错误的对话中：正在运行的同名正文与 target被替换，当被替换的body是时，替换被推迟+分叉 一个运行命令，所以它在其地板被移除之前就完成了正在发生的事情。
3. 一切都已经正确：什么也没有发生。正确的安装重新运行是无操作的，即 是什么使得可以安全地告诉困惑的用户“再次运行它”。

单例规则

水性剂为ONE剂。安装程序强制执行它可以看到的一半：如果对话 已经有一个主体（任何名称），针对它的第二次安装被拒绝并指示到 现有的身体。它看不到的一半是表面：一个化石桌面聊天，一个旧窗口某人 输入到.永远不要通过旧表面唤醒药剂并再次用水冲洗它，这就是一个人的方法 代理变成两个。如果您不确定对话是否已经有正文，waterbear doctor 列出计算机上每个固定的对话。

转换桌面代理后，运行 waterbear doctor --twins 并中继该卡。 文字记录记录了每个条目的来源，因此医生可以区分桌面上的对话和 CLI- 出生的一个，对于每个可能的双胞胎，它都会打印人类找到正确的聊天所需的指纹 在桌面中 UI：出生日期和开头消息，当标题不存在时，它们会保留重命名。它还 报告化石是否仍在书写。将那张卡片逐字传递给人类，解决办法就是一个 每个双胞胎点击存档一次，卡片就会告诉他们哪个聊天以及为什么它是安全的。

如果安装程序输出显示主体将启动 FRESH 而不是恢复，则 STOP 并在之前修复该问题 说别的（请参阅上面的图钉部分）。如果人类明确想要，则 --defer 存在 稍后启动身体；它不是默认值，因为每个满足延迟的操作员 handoff 将正确的安装视为不完整的安装。

第一次唤醒必须是无提示的

因权限提示而被阻止的会话未运行，无法检查自己的屏幕，并且永远不会 超时，并且在新的恢复后窗口中，提示可能无法转发到远程控制，因此 无人看管的身体可能会永远被封锁，而从每个遥远的表面看起来都很忙碌。结束前 你的安装回合：确保唤醒路径（你的脚本、你的 git 形状）被允许规则覆盖 主体的目录继承，或者告诉人们应该在 tmux 中观看 FIRST 唤醒，以便他们可以 回答“不要再问”一次。稳态提示正常前进；这只是唤醒窗口 需要这种照顾。

同样的规则也延伸到了尾迹之后。如果安装连接环形传输（CLAUDE_RC_DOORBELL 或 任何唤醒适配器），环的 RECEIVE 路径也可以在无人值守的情况下运行：打开环引用的有效负载， 运行任何使其成为当前状态的拉动，写入任何 offset/receipt 状态。任何一个新鲜的 权限提示会像阻塞唤醒一样无形地停止会话。的 门铃技能 指定首次使用权限 该路径的预检（映射接收步骤、请求狭窄的持久批准、以 冷无提示证明：闲置，发送真实的铃声，在没有人工提示的情况下观看它完成）； 遵循它而不是在这里重新推导。当路径、任务身份或 权限配置文件更改。

快速参考

简历注意事项（重要）

Resume 每次都会将 FULL 记录重播到上下文中，因此上下文会随着每次重生而增长。 使用恢复来保证崩溃期间的连续性，并定期启动干净的会话以减轻体重。 恢复是为了恢复，而不是无限积累。

更深入（参考资料/）

操作核心在上面；其余的移至参考文献，按需阅读：

• references/architecture.md：这 4 部分如何配合（guard、tmux、 launchd，唤醒），建立一个新的命名会话，捕获钩子，plist重新加载与kickstart， 嵌套会话危险和 waterbear-doctor，从 Claude 或 macOS 移植。
• references/operations.md：CONVERGE 台式双修、驾驶 您自己的模态命令终端 (waterbear-selfcmd)、重命名、常见错误以及 停车（waterbear-park，重新启动稳定下来），将主体滚动到新的二进制文件上 在 claude update（waterbear-restart，以 --list 作为漂移报告）之后，并取下尸体 （waterbear-uninstall，以及哪个拆解保留了对话）。