Clawauth OAuth Skill

This skill gives agents a production-safe OAuth handover flow that is async by default and works across chat/session interruptions.

Use this when the agent needs provider credentials from a human user, but must avoid blocking execution and must avoid long-lived token storage on a third-party auth SaaS.

Why this exists

Most "OAuth gateway" patterns keep user refresh tokens in a central hosted database. clawauth avoids that model:

• Hosted edge service mints short-lived auth sessions.
• User authorizes directly with the provider.
• Token response is encrypted end-to-end to the requesting CLI session.
• CLI claims once and stores token locally in system keychain.
• Server-side session is ephemeral and deleted on claim/expiry.

Result: async UX for agents, minimal operator overhead, and no permanent central token vault by design.

Runtime prerequisite

clawauth must already be preinstalled in the trusted runtime image/environment by the operator. This skill does not instruct dynamic package installation.

OpenClaw can detect this requirement from frontmatter metadata:

• metadata.openclaw.requires.bins: ["clawauth"] gates eligibility.
• metadata.openclaw.install can expose an operator-approved install action in OpenClaw UI/Gateway flows.

How installation is documented and triggered

• Installation intent is declared in frontmatter, not in free-form shell instructions.
• This skill declares a Node installer in metadata.openclaw.install for package clawauth.
• OpenClaw/Gateway uses that metadata to offer a managed install action when clawauth is missing.
• If multiple installer options are present, Gateway selects a preferred one (OpenClaw docs: brew preferred when available, otherwise node manager policy).
• For this skill we publish a single Node installer path to keep behavior deterministic across hosts.
• Reference: https://docs.openclaw.ai/tools/skills
• Reference: https://docs.openclaw.ai/platforms/mac/skills
• Source code (review before install): https://github.com/claw-auth/clawauth

Manual install (operator fallback)

If OpenClaw/Gateway does not run the install action automatically, install the CLI manually:

npm i -g clawauth

Then verify:

clawauth --help
openclaw skills check --json

Install policy (recommended)

• Pre-install clawauth in the base image/runner and disable ad-hoc package fetches.
• Pin and approve the CLI version in operator-managed tooling policy.
• Keep package source/provenance controls outside this skill (CI image build or internal artifact policy).

Hosted service endpoint

The published CLI is already wired to:

• https://auth.clawauth.app

Agents do not need CLAWAUTH_WORKER_URL for normal hosted usage.

Provider support

Implemented providers in current worker:

• notion
• github
• discord
• linear
• airtable
• todoist
• asana
• trello
• dropbox
• digitalocean
• slack
• gitlab
• reddit
• figma
• spotify
• bitbucket
• box
• calendly
• fathom
• twitch

Always treat server output as source of truth:

clawauth providers --json

Canonical async flow (non-blocking)

1. Start auth and return immediately:

clawauth login start <provider> --json

2. Extract and forward shortAuthUrl to the user.

3. Continue other work. Do not block.

4. Later poll/check:

clawauth login status <sessionId> --json

5. When status is completed, claim once:

clawauth login claim <sessionId> --json

6. Claim completion and hand off control to the operator-defined API call layer. This skill intentionally avoids instructing raw token materialization commands.

Token exposure boundaries

• login claim may return sensitive token payload data in JSON output.
• Do not paste sensitive command output to chat, logs, traces, or telemetry.
• Do not materialize tokens into shell environments from this skill.
• Use operator-controlled secret handling for downstream provider API calls.

Command map

Login lifecycle

• clawauth login start [provider] [--ttl <seconds>] [--scope <scope>] [--json]
• clawauth login status <sessionId> [--json]
• clawauth login claim <sessionId> [--json]
• clawauth login wait <sessionId> [--timeout <ms>] [--interval <ms>] [--json]

Session management

• clawauth sessions [--json]
• clawauth session-rm <sessionId> [--json]

Token access

• clawauth token list [--json]

Discovery and docs

• clawauth providers [--json]
• clawauth explain
• clawauth docs

JSON fields agents should parse

login start --json

• provider
• sessionId
• expiresIn
• shortAuthUrl
• authUrl
• statusCommand
• claimCommand

login status --json

• status (pending | completed | error)
• provider
• error

login claim --json

• status (pending | completed | error)
• provider
• tokenData
• storedInKeychain
• keychainService
• keychainAccount

Agent behavior rules

• Prefer --json for machine parsing.
• Never block by default; only use login wait when explicitly needed.
• On pending: schedule retry later.
• On completed: run login claim once.
• On error: surface concise reason and restart with new login start.
• If session context is lost, recover using clawauth sessions --json.
• If provider unknown, run clawauth providers --json and choose supported value.
• Never print raw tokens into user-facing chat.
• Do not run package install/fetch commands from this skill.
• Do not export tokens into shell environment variables from this skill.

Security model summary

• Short-lived session data in Cloudflare KV (default TTL: 3600s, configurable).
• Signed OAuth state binding provider and expiry.
• Signed request verification for status/claim with timestamp + nonce.
• Replay and rate-limit protections during polling.
• End-to-end encrypted token blob (nacl.box) from callback to CLI claimant.
• Session blob removed from server on successful claim.
• Tokens stored locally in OS keychain via CLI.

Failure handling

Provider not implemented:

• login start returns error indicating feature request recorded.

Provider misconfigured on backend:

• server returns clear missing secret/config message.

Session expired:

• status/claim returns not found/expired; start new session.

Lost chat context:

• run clawauth sessions --json, then continue with status/claim.

No token found later:

• run clawauth token list --json and select provider/account explicitly.

Minimal end-to-end example

# 1) Start
clawauth login start notion --json

# 2) Share shortAuthUrl with user (from JSON output)

# 3) Later check
clawauth login status <sessionId> --json

# 4) Claim when completed
clawauth login claim <sessionId> --json

# 5) Continue with operator-defined downstream API handling

Reference

See references/commands.md for compact copy-paste command blocks.