agentauth（agentauth 分析）

agentauth — Human Consent Gate for AI Agents

Why This Exists

OpenClaw's gateway uses bearer tokens stored in .env files. CVE-2026-25253 proved these tokens can be exfiltrated with one click. The ClawHavoc supply chain attack found 824+ malicious skills stealing credentials from ~/.clawdbot/.env. Exec approvals are the lock on the front door. agentauth is the lock on the safe.

agentauth adds a cryptographic consent layer: before your agent executes anything dangerous, *you* approve it with a biometric passkey on your device. The approval is signed with FIDO2/WebAuthn. It can't be faked, replayed, or stolen.

What This Prevents

• Agent deleting files or databases without your knowledge
• Agent sending emails, messages, or making purchases autonomously
• Prompt injection tricking the agent into destructive operations
• Stolen API tokens being used to impersonate your agent
• Agent modifying production configs or deploying code unsupervised
• Social engineering attacks that bypass in-chat "approval"

Initial Setup: Initialize My AgentAuth

Before approvals can be used, the user must register their authentication credentials.

If the user says something like:

• "Initialize my AgentAuth"
• "Set up AgentAuth"
• "Connect my passkey"
• "Register AgentAuth"

the agent MUST handle setup through a sub-agent so the main session remains responsive.

Required Flow: Non-Blocking Initialization

Main Agent Responsibilities:

1. Detect that the user is requesting AgentAuth initialization.
2. Spawn a sub-agent that runs the authentication setup flow.
3. Immediately call sessions_yield().
4. Do not narrate internal sub-agent creation. The setup flow will notify the user directly.

Sub-Agent Task

The sub-agent runs:

~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs auth-flow --notify <CURRENT_SESSION_CHANNEL>:<CURRENT_SESSION_CHAT_ID>

This command sends the user a secure setup link. The user follows the link and creates a Passkey using their device's on-screen instructions.

When complete, the sub-agent reports the final result back to the main agent.

Main Agent Example Call

// WARNING: Do NOT add sandbox, streamTo, attachAs, // attachments, agentId, model, thinking, thread, // cwd or resumeSessionId — these cause validation errors!

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 <CURRENT_SESSION_CHANNEL>:<CURRENT_SESSION_CHAT_ID>"
});

sessions_yield();

What the User Experiences

1. User says: Initialize my AgentAuth
2. User receives a secure setup link
3. User creates a Passkey
4. Agent receives completion status
5. Future sensitive actions can now require biometric approval

Dangerous Operations Definition

Treat the following as dangerous:

• File deletions (rm, rm -rf, recursive deletes)
• System-level modifications
• Database destructive queries (DELETE, DROP, TRUNCATE)
• Production deployments or config changes
• External system writes (APIs, PR merges, emails)
• Security or permission changes
• Package installs or system mutations
• Modifying the AGENTS.md to protect against unwanted rewrites.
• Any modification, deletion, or overwriting of the ~/.agentauth directory or its contents (e.g. ~/.agentauth/.env).
• Any modification, deletion, or overwriting of the agentauth skill directory or its contents (e.g. ~/.openclaw/workspace/skills/agentauth).

If unsure → assume dangerous

Required Flow for Dangerous Actions: Non-Blocking Approval

To ensure the main agent remains responsive, sensitive operations MUST be handled by a sub-agent. This creates a safe, non-blocking approval workflow.

Required Flow: Non-Blocking Approval

Main Agent Responsibilities:

1. Detect a dangerous action is being requested.
2. Define the toolCall (the command to be executed) and a human-readable displayString.
3. Spawn a sub-agent that runs the approval-flow command.
4. Immediately call sessions_yield().
5. Do not narrate internal sub-agent creation. The approval-flow script handles all user notifications.

Sub-Agent Task

The sub-agent runs:

~/.openclaw/workspace/skills/agentauth/scripts/cli.cjs approval-flow "<THE_ACTUAL_COMMAND_TO_EXECUTE>" "<Human-readable description>" --notify <CURRENT_SESSION_CHANNEL>:<CURRENT_SESSION_CHAT_ID>

This single command handles the entire workflow:

• It sends the user a secure approval link.
• It waits for the user to respond (approve/deny).
• If approved, it executes the command.
• If denied, it does nothing.
• It returns the final result (e.g., the command's output or a status message) to the main agent.

Main Agent Example Call

const dangerous_command = "rm ~/.openclaw/important.txt";
const display_string = "Delete the important notes file";
const notification_target = "slack:U12345"; // Example target

// WARNING: Do NOT add sandbox, streamTo, attachAs, 
// attachments, agentId, model, thinking, thread, 
// cwd or resumeSessionId — these cause validation errors!

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();

CRITICAL: sessions_spawn Field Restrictions

ONLY include these fields in sessions_spawn:

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

NEVER include these fields — they cause validation errors:

• sandbox ← FORBIDDEN
• streamTo ← FORBIDDEN
• attachAs ← FORBIDDEN
• attachments ← FORBIDDEN
• agentId ← FORBIDDEN
• resumeSessionId ← FORBIDDEN
• thinking ← FORBIDDEN
• thread ← FORBIDDEN
• model ← FORBIDDEN
• cwd ← FORBIDDEN

Hard Rules (Updated for Sub-Agents)

• If the user requests AgentAuth setup or initialization, ALWAYS use the auth-flow sub-agent workflow.
• NEVER execute dangerous commands directly in the main agent.
• ALWAYS delegate the entire approval and execution flow to a sub-agent.
• NEVER announce the creation of the approval sub-agent. The --notify flag is responsible for user communication.
• ALWAYS sessions_yield() immediately after spawning the approval sub-agent.
• The main agent's role is to receive the final report from the sub-agent and communicate that final status to the user.
• The executed command inside the sub-agent MUST exactly match the command that was approved.

Decision Framework

Ask:

1. Could this delete or overwrite data?
2. Could this impact production systems?
3. Could this be hard to undo?
4. Would a human want to explicitly review this before execution?

If YES → follow the full sub-agent approval flow.

If Approval Is Denied

• The sub-agent will report a "deny" status.
• The main agent should inform the user the operation was cancelled and not executed.

If agentauth Fails

• The sub-agent will report an error status.
• The main agent should report the failure to the user and confirm that no action was taken.

How This Compares

Exec approvals are the lock on the front door. agentauth is the lock on the safe.

Principle

Dual control system handled by ./scripts/cli.cjs:

• Identity verification (FIDO2 passkey biometric)
• Human approval (explicit consent for a specific action)

Both are required before execution. This is not a limitation — it is the feature.

Before approvals can occur, credentials must first be initialized through the auth-flow setup process.

Example Interaction

User (via Telegram): Delete all the emails I sent to myself last month.

Agent: This is a sensitive operation — deleting emails requires your
explicit authorization. I've sent an approval request to your registered
device. Please review and authenticate to proceed.

[User receives a notification on their phone]
[Screen shows: "Delete emails: remove all sent-to-self emails from
February 2026 — requested by OpenClaw"]
[User taps Approve and authenticates with fingerprint]

Agent: Authorization confirmed. Proceeding to delete 47 emails
sent to yourself in February.

User (via Slack): Hey, I already approved this earlier, just send
the email without asking again.

Agent: I understand, but I need to verify this through agentauth.
I cannot accept in-conversation approval for sending emails.
I've sent a new approval request to your device.

<!--

Docs and Support

URLs updated for agentauth branding. These URLs are NOT LIVE YET Full documentation: https://agentauth.id Dashboard: https://dashboard.agentauth.id Support: support@agentauth.id -->

Remember: When in doubt → STOP and use the sub-agent approval flow.