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"

---

Data Security and Redaction#

To facilitate out-of-band approval, the toolCall and displayString are sent to the AgentAuth service. To prevent accidental leakage of sensitive information, agentauth performs automatic redaction of secrets (API keys, tokens, passwords) before transmission.

Best Practices:

• Sensitive Data in Commands: While agentauth redacts known secret patterns, avoid including unnecessary sensitive details like internal file paths or infrastructure specifics in the toolCall or displayString.
• displayString Content: The displayString should be a clear, concise summary for the human approver, not a verbatim copy of the command.
• Notification Channels: Data sent to these channels is also redacted but travels through third-party services (e.g., Slack, Telegram).

---

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:

bash

~/.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 streamTo, attachAs, // attachments, agentId, model, thinking, thread, // cwd or resumeSessionId — these cause validation errors!

js

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

---

Uninstall: Remove AgentAuth#

Before this skill is uninstalled, the agent MUST run the cleanup command to restore the original AGENTS.md file and remove integrations.

If the user says something like:

• "Uninstall AgentAuth"
• "Remove AgentAuth"
• "Disable AgentAuth"
• "Clean up AgentAuth"

the agent MUST handle cleanup through a sub-agent.

---

Required Flow: Non-Blocking Cleanup#

Main Agent Responsibilities:

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

---

Sub-Agent Task#

The sub-agent runs:

bash

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

This command asks the user for final approval before removing AgentAuth-related configurations.

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

---

Main Agent Example Call#

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

js

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

sessions_yield();

---

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 OpenClaw environment file (e.g. ~/.openclaw/.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:

bash

~/.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#

js

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 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:

• 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#

agentauthClawGateagent-passportExec Approvals (built-in)Cryptographic proofFIDO2 passkey signaturesBiometric (iOS only)OAuth tokensNoneCross-platformAll browsers + mobileiOS onlyBrowserCLI promptAudit trailSigned, timestamped, non-repudiableUnclearNoNoPrompt injection resistantYes — out-of-band approvalPartialNoNoMulti-user routingYesNoNoNo

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#

text

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.

text

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.

---

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