agentauth — AI Agent 的人工授权门控系统

为何需要此功能

OpenClaw 网关使用存储在 .env 文件中的 Bearer Token。CVE-2026-25253 证实，此类 Token 可通过单次点击即被窃取。ClawHavoc 供应链攻击发现，已有 824+ 个恶意 skill 正从 ~/.clawdbot/.env 中盗取凭证。执行审批（exec approvals）是前门上的锁；agentauth 则是保险柜上的锁。

agentauth 引入了一层密码学授权机制：在您的 agent 执行任何危险操作之前，您本人需在设备上通过生物特征 Passkey 进行明确授权。该授权使用 FIDO2/WebAuthn 签名，无法伪造、重放或窃取。

本机制可防范的风险

• Agent 在未经您知情的情况下删除文件或数据库
• Agent 自主发送邮件、消息或发起支付
• 提示注入（prompt injection）诱导 agent 执行破坏性操作
• 被盗 API Token 被用于冒充您的 agent
• Agent 未经监督地修改生产环境配置或部署代码
• 绕过聊天界面内“确认”提示的社会工程攻击

数据安全与敏感信息脱敏

为支持带外（out-of-band）审批，toolCall 和 displayString 将被发送至 AgentAuth 服务。为防止敏感信息意外泄露，agentauth 会在传输前自动脱敏已知的密钥类内容（如 API Key、Token、密码等）。

最佳实践：

• 命令中避免携带敏感数据：尽管 agentauth 会自动识别并脱敏常见密钥模式，仍应避免在 toolCall 或 displayString 中包含不必要的敏感细节，例如内部文件路径或基础设施具体信息。
• displayString 内容规范：displayString 应为面向人类审批者的清晰、简洁摘要，而非命令原文的逐字复制。
• 通知渠道：发送至这些渠道的数据同样经过脱敏处理，但其传输路径依赖第三方服务（例如 Slack、Telegram）。

初始设置：初始化我的 AgentAuth

在启用审批功能前，用户必须先注册其认证凭据。

当用户发出如下任一指令时：

• “初始化我的 AgentAuth”
• “设置 AgentAuth”
• “连接我的 Passkey”
• “注册 AgentAuth”

agent 必须通过子 agent（sub-agent）完成设置流程，以确保主会话持续保持响应状态。

必需流程：非阻塞式初始化

主 agent 职责：

1. 识别用户正在请求 AgentAuth 初始化。
2. 启动一个子 agent，运行认证设置流程。
3. 立即调用 sessions_yield()。
4. 不得向用户说明子 agent 的内部创建过程；设置流程将直接向用户发送通知。

子 agent 任务

子 agent 执行以下命令：

~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs auth-flow --notify :

该命令向用户发送一个安全的初始化链接。用户点击链接后，根据设备屏幕提示完成 Passkey 创建。

完成后，子 agent 将最终结果回传给主 agent。

主 agent 示例调用

// 警告：请勿添加 streamTo、attachAs、 // attachments、agentId、model、thinking、thread、 // cwd 或 resumeSessionId —— 这些字段会导致校验失败！

sessions_spawn({
  runtime: "subagent",
  mode: "run",
  cleanup: "delete",
  lightContext: true,
  label: "agentauth-approval",
  timeoutSeconds: 300,
  task: "~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs auth-flow --notify :"
});

sessions_yield();

用户实际体验流程

1. 用户输入：Initialize my AgentAuth
2. 用户收到一条安全初始化链接
3. 用户按指引创建 Passkey
4. agent 接收初始化完成状态
5. 此后所有高危操作均可要求生物特征授权

高危操作定义

以下操作均视为 高危操作：

• 文件删除（rm、rm -rf、递归删除）
• 系统级修改
• 数据库破坏性查询（DELETE、DROP、TRUNCATE）
• 生产环境部署或配置变更
• 对外部系统的写入操作（API 调用、PR 合并、发邮件等）
• 安全策略或权限变更
• 软件包安装或系统变更
• 修改 AGENTS.md 以防止意外覆盖。
• 对 OpenClaw 环境文件（如 ~/.openclaw/.env）进行任何修改、删除或覆盖。
• 对 agentauth skill 目录或其内容（如 ~/.openclaw/workspace/skills/agentauth）进行任何修改、删除或覆盖。

如有不确定 → 一律视为高危操作

高危操作的必需流程：非阻塞式审批

为确保主 agent 始终响应及时，所有敏感操作必须交由子 agent 处理，从而构建安全、非阻塞的审批工作流。

必需流程：非阻塞式审批

主 agent 职责：

1. 识别当前请求是否涉及高危操作。
2. 定义 toolCall（待执行命令）及人类可读的 displayString。
3. 启动一个子 agent，运行 approval-flow 命令。
4. 立即调用 sessions_yield()。
5. 不得向用户说明子 agent 的内部创建过程；approval-flow 脚本负责全部用户通知。

子 agent 任务

子 agent 执行以下命令：

~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs approval-flow "" "" --notify :

该单一命令完整覆盖整个审批流程：

• 向用户发送安全审批链接；
• 等待用户响应（批准 / 拒绝）；
• 若获批准，则执行命令；
• 若被拒绝，则不执行任何操作；
• 将最终结果（例如命令输出或状态消息）返回给主 agent。

主 agent 示例调用

const dangerous_command = "rm ~/.openclaw/important.txt";
const display_string = "删除重要笔记文件";
const notification_target = "slack:U12345"; // 示例目标

// 警告：请勿添加 streamTo、attachAs、 
// attachments、agentId、model、thinking、thread、 
// cwd 或 resumeSessionId —— 这些字段会导致校验失败！

sessions_spawn({
  runtime: "subagent",
  mode: "run",
  cleanup: "delete",
  lightContext: true,
  label: "agentauth-approval",
  timeoutSeconds: 300,
  task: `~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs approval-flow "${dangerous_command}" "${display_string}" --notify ${notification_target}`
});

sessions_yield();

关键限制：sessions_spawn 字段白名单

仅允许在 sessions_spawn 中使用以下字段：

• runtime
• mode
• cleanup
• lightContext
• label
• timeoutSeconds
• task

以下字段绝对禁止使用 —— 否则将触发校验错误：

• streamTo ← 禁止
• attachAs ← 禁止
• attachments ← 禁止
• agentId ← 禁止
• resumeSessionId ← 禁止
• thinking ← 禁止
• thread ← 禁止
• model ← 禁止
• cwd ← 禁止

硬性规则（针对子 agent 更新）

• 若用户请求 AgentAuth 设置或初始化，必须始终使用 auth-flow 子 agent 工作流。
• 严禁在主 agent 中直接执行高危命令。
• 必须始终将完整的审批与执行流程委托给子 agent。
• 严禁向用户宣告审批子 agent 的创建；--notify 参数负责全部用户通信。
• 每次启动审批子 agent 后，必须立即调用 sessions_yield()。
• 主 agent 的唯一职责是接收子 agent 返回的最终报告，并将该最终状态告知用户。
• 子 agent 内部执行的命令必须与经审批的命令完全一致。

决策框架

请自问：

1. 该操作是否可能导致数据删除或覆盖？
2. 该操作是否会影响生产系统？
3. 该操作是否难以撤销？
4. 人类是否希望在执行前明确审查该操作？

若任一问题答案为“是” → 必须执行完整的子 agent 审批流程。

若审批被拒绝

• 子 agent 将上报 “deny” 状态。
• 主 agent 应通知用户该操作已被取消，且未执行。

若 agentauth 执行失败

• 子 agent 将上报错误状态。
• 主 agent 应向用户报告失败，并确认未执行任何操作。

横向对比

执行审批（Exec approvals）是前门上的锁；agentauth 是保险柜上的锁。

设计原则

双重控制机制由 ./scripts/cli.cjs 实现：

• 身份验证（FIDO2 Passkey 生物特征）
• 人工审批（针对特定操作的显式授权）

二者缺一不可，方可执行。这不是限制，而是核心特性。

审批功能启用前，必须首先通过 auth-flow 设置流程完成凭据初始化。

交互示例

User（通过 Telegram）：删除我上个月发给自己的所有邮件。

Agent：这是一项敏感操作——删除邮件需您明确授权。我已向您已注册的设备发送审批请求，请查看并完成身份验证以继续。

[用户手机收到通知]
[屏幕上显示：“删除邮件：移除 2026 年 2 月所有发给自己的邮件 —— 由 OpenClaw 发起”]
[用户点击“批准”，并使用指纹完成认证]

Agent：授权已确认。正在执行操作，将删除您于 2026 年 2 月发送给自己的 47 封邮件。

User（通过 Slack）：嘿，我之前已经批准过了，这次直接发邮件就行，不用再问了。

Agent：我理解，但发送邮件必须通过 agentauth 进行验证。我无法接受聊天对话内的审批确认。我已向您的设备发送新的审批请求。

请牢记： 如有疑虑 → 立即中止，并启用子 agent 审批流程。