Each file in this directory captures one architecture decision: the context, the choice, and its consequences. See the ADRs section in AGENTS.md for the rules on adding, updating, naming, and citing ADRs.
- Local Runtime Architecture
- Bun Workspaces Monorepo
- Approval And Audit Substrate — supersedes Trust Substrate
- Browser Fill-Secret Tool
- Browser Stealth Identity
- Browser Automation Engine — In-Process playwright-core, Not agent-browser
- Per-Agent Browser Domain Policy
- Instances And Control Surface
- Agent Loop With Native Tool Calling
- Deferred Tools (Load-On-Demand Catalog)
- Self-Config Registry as Deferred Direct Tools
- Subagent Delegation
- Agents Replace Profiles And Drive Runtime Behavior
- Per-Agent Provider Settings (Editable Override + In-Chat Settings Tab)
- Model-First Selection (Models With Routes, Not Providers With Models)
- Transient Provider Fallback (An Unconfigured Provider Degrades, It Doesn't Block)
- Approval Mode (three-state policy) — supersedes dangerouslyAutoApprove
- Per-Agent Memory Isolation
- Connector Secret Storage
- Skills As Packages, Connectors As Credentials
- Typed, Named Credentials Referenced By Name
- Approval Execution Abort Protocol
- Turn Model-Call Abort Protocol
- Runtime Update Surface And Automatic Restart
- Always-Up Supervision For launchd-Managed Instances
- Sha-Keyed Production Serving For The Web Control Plane
- Crash Reporting And Issue Filing
- Resume In-Flight Tasks After A Gateway Restart
- Connector + Provider Vocabulary, Spec Compliance, And Meta-Skills
- Provider extraBody Escape Hatch And Reserved-Key Denylist
- Native Anthropic Messages Provider (First-Party Claude)
- Amazon Bedrock Provider via the Converse API (Model-Agnostic, SigV4)
- Azure OpenAI As A First-Class Provider
- Pinned in_memory Prompt-Cache Tier, No Active Warming
- Telegram Messaging Bridge
- Discord Messaging Bridge
- Email Watch
- Pre-LLM Job Hooks
- Job Concern Fan-Out
- Job Skill Attachments
- Skill Learning From Task Outcomes
- Runtime Identity Injection With Tell-Once + Delta + Periodic Refresh
- Runtime Identity Files (INSTRUCTIONS.md, SOUL.md, USER.md)
- Identity-File Long-Horizon Design
- Openclaw Migration
- BFF Trust Boundary For Privileged POSTs
- Gateway Reverse-Proxies The Web App As A Single Origin
- Tunnel Connectivity
- Owner-Token-Only Authentication — supersedes Device-Pairing Authentication (superseded)
- Mobile Push Notifications (APNs + NSE Enrichment + Inline Actions)
- Codex Session-Rotation Retry, UA Mirroring, And auth.json Race Handling
- Authorization vs SetupRequest
- User Choice Prompt (ask_user / chat.choice)
- User Confirmation Primitive (request_confirmation / confirmation.request)
- Skill Env Containment For terminal_exec And skill_run
- Per-Skill Connector Consent Grant
- Declarative Approval Gating For Skill Scripts
- Multiple Tagged Google Accounts For The Workspace Skills
- Web Onboarding Flow
- Managed Deployment Mode
- Chat-Driven Credential Provisioning
- Provider Re-Authentication Guidance
- Voice Messages With Gateway-Side Local Speech-To-Text
- Chat File Attachments — Capability-Driven Delivery
- Outbound Chat Attachments — Agent → User Images
- Agent-Authored Inline Cards And The Direct Draft-Send Affordance
- Server-Side Chat Message Queue
- Task Containers And Runs (Unified Task Model) — supersedes in part Chat → Topics → Tasks → Subagents
- Job Delivery Policy
- One Chat Per Agent, Threads, And Job Channels
- Connector-Backed Web Search
- In-App Doc References Render Inline
- Per-Agent Structured Database Primitive
- In-App Log Viewing
- Comprehensive Token Usage Accounting
- Docker + Xvfb Deployment
- PostHog MCP Analytics with Chat Masking