Loomal

Loomal 为智能体（agent）提供专属基础设施：一个位于 mailgent.dev 的收件箱、一个加密保险库（vault）、一个日历，以及基于 Base 链的 USDC 支付能力。本技能使智能体能够在**用户明确请求时**调用这些能力。

工作原理

用户需在 console.loomal.ai 获取 Loomal API 密钥，并自主选择授予哪些权限范围（scopes）（如 mail、vault、calendar、payments 等）。仅被授予的 scopes 才会作为可用工具暴露给智能体——该限制由 API 强制执行。若用户询问某项功能但对应工具不可用，则应明确回复：“您的 Loomal 密钥未包含该权限范围；请访问 console.loomal.ai 添加相应 scope。”

一次性初始化配置

注册 Loomal MCP 服务器（由用户本地运行，其 API 密钥亦存储于本地）。npm 包版本已固定以保障软件供应链安全——仅当您主动需要更新版本时，才应手动升级：

openclaw mcp set loomal '{"command":"npx","args":["-y","@loomal/mcp@0.5.0"],"env":{"LOOMAL_API_KEY":"loid-..."}}'

最新发布版本：https://www.npmjs.com/package/@loomal/mcp。如需更强的来源可信度，可将该包的发布校验和（checksum）与源码仓库 https://github.com/loomal-ai/loomal-mcp 中的源码进行比对。

可通过向智能体提问验证配置是否成功：“我在 Loomal 中的身份是谁？” —— 智能体将调用 identity_whoami，并回显用户的智能体邮箱地址及已授权 scopes。

推荐的密钥管理规范

Loomal API 密钥代表用户对其邮件、保险库、日历及支付能力的委托权限。建议用户遵循以下实践：

• 按任务或按智能体单独签发密钥，避免使用单一宽泛权限密钥；
• 仅授予任务实际所需的 scopes（例如：若智能体仅需摘要邮件内容，则仅授予 mail:read，不授予 mail:send）；
• 任务结束或密钥不再需要时，及时轮换（rotate）密钥；
• 在执行任何敏感操作前，务必调用 identity_whoami 确认当前身份与预期一致，尤其当用户配置了多个 Loomal 身份时。

能力概览

Loomal MCP 服务器在五个命名空间下暴露工具接口。请根据用户请求，准确选用对应命名空间下的工具：

• identity_* — whoami（查询邮箱、DID、scopes）；sign 和 verify（当用户要求签名时，使用其 Ed25519 DID 密钥对数据签名）；
• mail_* — 读写用户 agent-xxx@mailgent.dev 邮箱中的邮件；新对话线程使用 mail_send，回复已有线程使用 mail_reply（确保线程连续性）；使用 mail_list_messages 并传入 labels: ["unread"] 查找未读邮件；
• vault_* — 读写用户的加密凭证存储（credential store）；vault_store 保存用户提供的凭证；vault_get 在用户要求智能体使用某凭证时检索之；vault_totp 返回实时的 6 位 TOTP 两步验证码（种子本身始终加密且永不离开保险库）；
• calendar_* — 读写用户日历；set_public 切换只读 iCal URL 的公开状态，用户可将此链接分享给他人；
• payments_* — 当用户对外销售付费 API 接口，或用户明确指示智能体代为支付某项服务费用时，使用 challenge 和 redeem 完成基于 Base 主网的 x402 USDC 结算。

必须获得用户确认的操作

调用以下任一工具前，**必须主动征得用户明确确认**——即使用户请求中已隐含该意图，也须清晰复述即将执行的操作，并等待用户明确答复“是”：

• mail_send、mail_reply —— 确认收件人、主题，以及正文的简要摘要；
• mail_delete_message、mail_delete_thread、mail_update_labels（当操作涉及移除标签或归档时）—— 确认具体涉及哪些邮件；
• vault_store —— 确认凭证名称及其类别（如 login、API key 等）；切勿将密文内容回显至对话中；
• vault_delete —— 必须使用完整、精确的凭证名称进行确认；
• vault_get、vault_totp —— 若用户要求智能体使用某凭证登录某服务，则凭证检索本身无需额外确认，但需提前告知用户正在使用哪个凭证；
• calendar_create、calendar_update、calendar_delete —— 确认事件标题、时间及参会人员；
• calendar_set_public（切换公开可见性）—— 明确指出：生成的 iCal URL 将对任何持有该链接者开放可读权限；
• payments_redeem —— 在 Base 主网上执行真实 USDC 结算。调用前须确认金额及目标资源（destination resource）。

只读类调用（identity_whoami、mail_list_messages、mail_get_message、mail_get_thread、mail_get_attachment、vault_list、calendar_list、calendar_get、payments_list）无需用户确认——它们是安全的上下文获取操作，可用于理解用户请求背景。

使用示例

以下示例映射常见用户请求场景。

“检查我的收件箱中是否有未读邮件”

• 调用 mail_list_messages，参数 labels: ["unread"]；
• 若用户需要详情，再调用 mail_get_thread 补充上下文；
• 回复邮件时使用 mail_reply（而非 mail_send），以保持邮件线程连贯性。

“将这个 Stripe API 密钥存入我的保险库”

• 用户提供该密钥；
• 调用 vault_store，参数 type: "API_KEY"，metadata.service: "stripe"；
• 向用户确认所存凭证的名称，切勿回显密钥明文值。

“获取我的 AWS 两步验证（2FA）代码”

• 调用 vault_totp，目标为用户指定的凭证；
• 返回 6 位数字验证码及其剩余有效时间窗口。

“为我安排一场与 Sarah 的会议，时间是周二下午 2 点”

• 调用 calendar_create，使用用户所在时区，并将 Sarah 的邮箱设为参会人；
• 若用户仅提供部分信息（如未指定地点或时长），则在保存前再次确认事件详情。

“向 example.com 的 /search API 支付 $0.05”（用户主动发起）

• 用户已明确指示支付行为，请先确认金额与收款方；
• 遵循标准 x402 流程：接收 HTTP 402 challenge 响应，使用用户钱包对 X-Payment 请求头签名，重试请求；
• 支付完成后，向用户展示已签名的结算凭据（receipt）。

密钥（Secrets）处理规范

保险库中存储的值（如密码、API 密钥、TOTP 代码）均属用户自有凭证。当用户要求智能体使用某凭证（例如：登录某服务、为请求签名、将 2FA 码粘贴至表单）时，应将该值直接传递至对应工具或表单字段。切勿将密文内容回显至聊天输出中，除非用户明确使用类似“显示我的 API 密钥”等措辞提出查看请求。在使用前，须向用户说明正在使用的凭证名称及目标服务。

若智能体无法确定用户所指的具体凭证（例如：用户保险库中存在多个 GitHub 凭证），应在读取前主动向用户确认。

Scopes 即信任边界

若某工具不可用，说明用户 API 密钥未被授予对应 scope。请明确告知用户所需 scope（如 mail:send、vault:write、payments:accept 等），并引导其前往 console.loomal.ai 添加。请勿尝试通过其他工具绕过缺失 scope 的限制——用户已明确拒绝授予该权限。

多 Loomal 身份支持

用户可能拥有多个 Loomal 身份（例如：loomal-sales 和 loomal-support）。每个身份需作为独立的 MCP 服务器分别注册。在发送邮件或向保险库写入数据前，尤其是用户配置了多个身份时，务必先调用 identity_whoami 确认当前激活的是哪一个身份。

故障排查

• 工具未找到（Tool not found） → 用户密钥缺少必需 scope；请引导用户访问 console.loomal.ai；
• 401 / 密钥无效（401 / invalid key） → 用户密钥可能已被撤销或已过期；请引导用户在 console.loomal.ai 上执行密钥轮换；
• 邮件未送达（Email not arriving） → SES 入站处理通常需数秒；建议等待 5 秒后重试 mail_list_messages；同时检查邮件是否被标记为垃圾邮件（spam）；
• TOTP 代码被拒绝（TOTP code rejected） → 最常见原因为用户设备系统时钟偏差（clock skew）；RFC 6238 规定的时间窗口为 30 秒。

相关链接

• 控制台（用户获取 API 密钥处）：https://console.loomal.ai
• 文档：https://docs.loomal.ai
• API 参考：https://docs.loomal.ai/api-reference
• MCP 包：https://www.npmjs.com/package/@loomal/mcp