clawmail

Clawmail

joelclaw 的规范 Agent 协作约定。

joelclaw mail 是 pi Agent 唯一受支持的邮件访问接口。 不要在 Agent 提示词或角色说明中直接调用 mcp_agent_mail HTTP 端点。

拓扑结构

Agent-mail 是一项中央服务，而不是每台机器各自拥有一个邮箱：

• Flagg 在 127.0.0.1:8765 上运行权威守护进程。
• Blaine 和 Panda 运行 com.joelclaw.agent-mail-tunnel，通过 SSH 将各自本地的 127.0.0.1:8765 转发到 Flagg。
• 卫星节点/Relay 客户端继续使用默认的本地 URL。隧道在不向 tailnet 暴露未经身份验证的服务的情况下，保留了 CLI 约定。
• 不要在卫星节点上启动独立的 agent-mail 守护进程。健康的客户端必须报告与 Flagg 相同的邮箱/项目数量。

受版本控制的连接器资源：

• infra/agent-mail-tunnel.sh
• infra/launchd/com.joelclaw.agent-mail-tunnel.plist

接口

规范接口

• joelclaw mail ...（CLI）

Pi 封装工具（允许使用，但仍由 CLI 提供支持）

这些封装工具在底层通过 shell 调用 joelclaw mail：

工具	对应的 CLI 命令
mail_send	joelclaw mail send
mail_inbox	joelclaw mail inbox
mail_read	joelclaw mail read
mail_reserve	joelclaw mail reserve
mail_release	joelclaw mail release
mail_status	joelclaw mail status

必需协议（共享工作时默认遵循）

1. 操作文件前先检查收件箱
   • joelclaw mail inbox --agent <AgentName> --unread
2. 声明当前工作范围
   • joelclaw mail send --from <AgentName> --to <AgentName|team> --subject "Starting: <work>" "intent + paths + expected output"
3. 编辑前预留文件路径
   • joelclaw mail reserve --agent <AgentName> --paths "path/a.ts,path/b.ts" [--ttl-seconds 900]
4. 如果工作耗时较长，续订预留租约
   • joelclaw mail renew --agent <AgentName> --paths "path/a.ts" [--extend-seconds 900]
5. 工作期间发送状态/交接更新
   • joelclaw mail send --subject "Status: ..." ...
6. 提交/交接后释放预留
   • joelclaw mail release --agent <AgentName> --paths "..."
   • 或在所有预留路径都处理完毕后使用 --all

主题分类（便于搜索和协调）

始终使用以下前缀：

• Starting: — 开始工作/意图声明
• Task: — 交接或任务分配
• Status: — 进度更新
• Blocked: — 需要干预的依赖问题/事件
• Done: — 完成情况及产物/提交 ID

每日协调会使用这些信号来检测协议偏离情况。

命令速查

# server + inbox health
joelclaw mail status

# register / refresh identity metadata
joelclaw mail register --agent MaroonReef --program pi --model gpt-5.4 --task "interactive"

# send a coordination message
joelclaw mail send --from MaroonReef --to BlueFox --subject "Task: update prompt docs" "Please edit SYSTEM.md and roles/*.md"

# inbox / read
joelclaw mail inbox --agent MaroonReef --unread
joelclaw mail read --agent MaroonReef --id 12

# reservations
joelclaw mail reserve --agent MaroonReef --paths "SYSTEM.md,roles/interactive.md" --ttl-seconds 900
joelclaw mail renew --agent MaroonReef --paths "SYSTEM.md" --extend-seconds 900
joelclaw mail release --agent MaroonReef --paths "SYSTEM.md,roles/interactive.md"
joelclaw mail release --agent MaroonReef --all

# audit/search
joelclaw mail locks
joelclaw mail search --query "Starting:"

可靠性检查

快速验证协议健康状况

joelclaw mail status
joelclaw mail locks
joelclaw mail search --query "Starting:"
joelclaw mail search --query "Status:"

当本地 git-mailbox 仓库可用时，joelclaw mail locks 应反映 file_reservations/ 资源中活跃的建议性文件预留情况。这一点很重要，因为原始 /mail/api/locks 端点可能会少报文件预留情况，同时仍显示邮箱内部的归档/提交锁。

搜索功能降级时（数据库/工具错误）

• 不要依赖信号计数。
• 仍然按协议继续操作（声明/预留/释放）。
• 升级处理邮件后端健康问题，并记录调查结果。

CLI 标志被意外拒绝时

• 你编译的 ~/.bun/bin/joelclaw 可能比源代码版本旧。
• 从 packages/cli/src/cli.ts 重新构建 CLI，然后重试。

如果包装器输出 ok: true，但嵌套结果包含错误

• 将该操作视为失败。有些 CLI 路径会返回成功的封装，但 result.result 或 result.raw 中包含后端错误，例如 Too many open files、Agent not found 或过时的项目元数据。
• 验证预留、注册和收件箱调用时，应读取嵌套结果，而不只看顶层的 ok 标志。
• 如果后端表示已释放缓存的仓库，则重试一次；如果仍然失败，只继续进行低风险编辑，并在最终摘要中报告协调失败。
• 如果反复出现 Too many open files. Freed 0 cached repos，请检查 lsof -p $(pgrep -f 'mcp_agent_mail.*serve-http') | rg '\.(archive|commit)\.lock'。持久修复方案位于 joelhooks/mcp_agent_mail：关闭孤立的锁 FD，避免将缺少元数据的锁立即视为过期，并通过 infra/agent-mail-daemon.sh + infra/launchd/com.joelclaw.agent-mail.plist，使用 NumberOfFiles=8192 运行 com.joelclaw.agent-mail。

提示词编写清单（完善提示词）

任何提及协调的提示词／角色／系统约定都应：

1. 将 clawmail 作为规范协议技能。
2. 声明邮件访问通过 joelclaw mail 进行（允许使用包装器，不允许直接使用 MCP）。
3. 至少包括：检查收件箱、公告、预留、释放。
4. 要求在协调消息中注明路径上下文。
5. 建议使用主题前缀（Starting:、Task:、Status:、Blocked:、Done:）。
6. 如果不涉及共享编辑或协调，则避免加入无关的邮件说明。

转向循环集成

pi/extensions/session-lifecycle 每天运行一次监控与转向审查，并生成：

• agent-mail/steering.reviewed

快照路径：

• ~/.joelclaw/workspace/agent-mail-steering/YYYY-MM-DD.json

检测到偏离时，使用转向提示来加强协议遵循。

相关内容

• skills/agent-mail/SKILL.md（兼容性别名）
• joelclaw mail --help
• ADR-0172：通过 MCP Agent Mail 使用 Agent Mail