agent-auth-kit

Pluggable authentication orchestration for AI agents across OpenClaw, Codex, and Claude Code.

agent-auth-kit helps an agent detect missing auth, request a human approval step, validate the provider state, and resume the original task once. It is designed for OpenClaw auth skill, Codex auth skill, Claude Code auth workflow, device code login for agents, and browser login orchestration for AI agents.

Why This Exists

Most agent teams start with fragile auth glue:

• one-off shell scripts
• credentials pasted into chats
• tool-specific retries with no audit trail
• browser sessions that fail silently and never recover

agent-auth-kit turns that into a reusable workflow:

1. detect auth failure
2. create a challenge
3. notify the human operator
4. validate the provider state
5. resume the task once

Dual Entry

Human Quickstart

If you are a developer integrating auth recovery into an agent runtime:

python3 -m pip install -e .
agent-auth --help

If agent-auth is not on your PATH, use:

python3 -m agent_auth_kit.cli --help

Run the fake device-code provider:

python3 -m agent_auth_kit.providers.fake_device reset
agent-auth ensure --provider fake-device --resource fake-demo --no-wait
python3 -m agent_auth_kit.providers.fake_device complete
agent-auth ensure --provider fake-device --resource fake-demo

Agent Quickstart

If you are wiring this into OpenClaw, Codex, or Claude Code:

• OpenClaw: see integrations/openclaw/install.sh
• Codex: see integrations/codex/install.sh
• Claude Code: see integrations/claude-code/install.sh

What It Solves

• human approval for agent authentication
• device code login for agents
• browser login orchestration for AI agents
• resume agent task after authorization
• notifier and provider contracts that keep auth logic composable

Supported Agent Ecosystems

Ecosystem	Status	Entry
OpenClaw	First-class	integrations/openclaw
Codex	First-class	integrations/codex
Claude Code	First-class	integrations/claude-code

Security Model

• Never paste tokens, cookies, or passwords into chat.
• Keep provider secrets in provider-native stores whenever possible.
• Persist only challenge metadata and audit events.
• Separate human approval from provider validation.
• Fall back explicitly when browser session writeback cannot be done safely.

See SECURITY.md and docs/en/security.md.

Provider And Notifier Plugin Model

Provider contract

Each provider exposes:

provider status
provider login
provider validate

And returns JSON like:

{
  "provider": "example-provider",
  "state": "authenticated",
  "message": "summary",
  "login_url": "https://example.com/device",
  "user_code": "ABCD-EFGH",
  "raw_output": "sanitized output"
}

Notifier contract

Each notifier exposes:

• send_challenge(challenge, recipient)
• send_text(message, recipient)

Why Not Just Hand Tokens To The Agent?

Approach	Problem	Why agent-auth-kit is safer
Paste tokens into chat	credential leakage and replay risk	keeps secrets out of chat
One-off shell scripts	no shared contract	standard CLI and JSON contract
Raw browser takeover	unclear operator control	explicit human challenge and lifecycle
Per-tool retry hacks	impossible to scale	reusable provider/notifier interfaces

Documentation

• Human start: docs/en/get-started-human.md
• Agent start: docs/en/get-started-agent.md
• Architecture: docs/en/architecture.md
• OpenClaw: docs/en/openclaw.md
• Codex: docs/en/codex.md
• Claude Code: docs/en/claude-code.md
• Security: docs/en/security.md
• Case study: docs/en/case-study-openclaw.md
• Chinese README: README.zh-CN.md

Install

GitHub install

git clone https://github.com/<your-github-username>/agent-auth-kit.git
cd agent-auth-kit
python3 -m pip install -e .

PyPI install

python3 -m pip install agent-auth-kit

Repo Layout

src/agent_auth_kit/        core package and CLI
skills/                    agent-facing skills and templates
integrations/              OpenClaw, Codex, Claude Code integration packs
examples/                  fake providers and integration demos
docs/                      bilingual docs site
assets/                    architecture and social preview assets

Status

This repository is the public core. Internal provider implementations such as ByteDance-only or inference.sh-only adapters live in a private companion repository.