docs: add The Design of OpenAB

[chaodu-agent]

What problem does this solve?

OpenAB lacks a document that articulates its design philosophy and architectural decisions. Contributors and users need to understand why OpenAB is built the way it is — not just how to use it.

Summary

Adds docs/the-design-of-openab.md covering the four core design pillars:

1. Thin Bridge — transport layer only; no orchestration, no governance, no memory management
2. Multi-Bot Ready — multiple agents coexist in the same channel; users own the orchestration strategy
3. AI-Native — all operations performed through AI; docs written for AI consumption
4. Security by Design — must run in sandbox (K8s pod); read-only filesystem, process isolation, env_clear() by default; host execution is for local dev only

Also covers:

• Two-tier platform adapter architecture (native vs. gateway)
• ACP stdio bridge design
• Session pool model
• What OpenAB is not (and why)
• Comparison with OpenClaw's sandbox-after-the-fact approach

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: docs: add The Design of OpenAB
• Source: docs: add The Design of OpenAB #735
• Status: moved to PR-Screening
• Generated at: 2026-05-04T22:31:47.945Z
• Discord thread: https://discord.com/channels/1488041051187974246/1500988077684822128

Screening report

## Intent

PR #735 adds a design document intended to explain why OpenAB is architected the way it is, not just how to use it. The operator-visible problem is that contributors, reviewers, deployers, and agent maintainers lack a shared reference for OpenAB’s boundaries, security assumptions, adapter model, and relationship to adjacent systems like OpenClaw.

Feat

This is a docs improvement.

It adds DESIGN.md, described as “The Design of OpenAB,” covering OpenAB’s design pillars:

• Thin bridge: transport-only, no orchestration/governance/memory ownership
• Multi-bot readiness: multiple agents can coexist in one channel
• AI-native operation and documentation
• Security by design: sandboxed execution, read-only filesystem, process isolation, cleared environment by default
• Native vs gateway platform adapters
• ACP stdio bridge design
• Session pool model
• Explicit “what OpenAB is not”
• Comparison with OpenClaw’s sandboxing model

Who It Serves

Primary beneficiaries are maintainers and reviewers who need a stable architectural reference when evaluating changes.

Secondary beneficiaries are deployers, agent runtime operators, and contributors trying to understand OpenAB’s intended boundaries before adding features.

Rewritten Prompt

Add a concise architecture/design document for OpenAB that explains the project’s core design principles, execution model, security assumptions, and non-goals.

The document should:

• Describe OpenAB as a thin bridge between chat platforms and agent runtimes.
• Explain native versus gateway platform adapters.
• Clarify the ACP stdio bridge and session pool model.
• State what OpenAB deliberately does not own, including orchestration, governance, long-term memory, and scheduling.
• Document the expected production security posture: sandboxed execution, read-only filesystem where possible, process isolation, and environment clearing by default.
• Compare OpenAB’s approach to OpenClaw only where the comparison clarifies architectural boundaries.
• Avoid overstating guarantees not enforced by the current codebase.
• Use terminology consistent with existing docs and implementation names.

Acceptance criteria:

• DESIGN.md or equivalent docs path is added.
• Claims in the document are consistent with current implementation.
• Security statements distinguish required production posture from local development behavior.
• The OpenClaw comparison is factual, bounded, and useful to future reviewers.

Merge Pitch

This is worth advancing because architectural docs reduce reviewer drift and help future contributors avoid adding responsibilities that OpenAB intentionally should not own. The PR appears low implementation risk because it is documentation-only.

The main reviewer concern is accuracy: the document may make strong claims about sandboxing, read-only filesystems, env_clear(), session pooling, or OpenClaw comparisons that need to match the actual code and deployment guidance. The merge decision should focus less on prose quality and more on whether the document becomes an authoritative statement the project can stand behind.

Best-Practice Comparison

Relevant OpenClaw principles:

• Explicit delivery routing is relevant because OpenAB’s bridge role depends on clear message routing between platforms and agents.
• Isolated executions are relevant to the security section, especially if OpenAB claims production use requires sandboxed agent execution.
• Run logs, retry/backoff, durable job persistence, and gateway-owned scheduling are mostly not applicable if OpenAB intentionally avoids orchestration and scheduled job ownership.

Relevant Hermes Agent principles:

• Fresh session per scheduled run is not directly applicable unless OpenAB introduces scheduling or task recurrence.
• Self-contained prompts for scheduled tasks are not directly applicable to this docs PR.
• File locking and atomic writes are only relevant if the design document discusses persisted session state or shared runtime state.
• Gateway daemon tick model is relevant only as contrast: OpenAB should clearly state whether it is event-driven bridge infrastructure rather than a scheduler daemon.

The best-practice takeaway is that the document should use OpenClaw and Hermes as boundary references, not as feature checklists. If OpenAB is not supposed to own durable jobs, retries, scheduled runs, or daemon ticks, the design doc should say that plainly.

Implementation Options

Option 1: Conservative docs-only merge
Merge the design document after a factual review for terminology, security claims, and alignment with current code. Keep scope limited to DESIGN.md.

Option 2: Balanced docs plus cross-links
Merge the design document and add references from existing docs such as README.md, contributor docs, or architecture docs. This makes the design statement discoverable without changing runtime behavior.

Option 3: Docs plus verification checklist
Merge the document with a short reviewer checklist or follow-up issue that maps major claims to code locations. This is useful if the document is intended to become an architectural source of truth.

Option 4: Ambitious architecture governance pass
Use this PR as the start of a broader architecture documentation set: design principles, adapter contracts, security model, deployment model, and comparison docs. This should likely be split into follow-up PRs rather than bundled into #735.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative docs-only merge	High	Low	Medium	Medium	Medium	Good
Docs plus cross-links	Medium	Low-Medium	Medium	High	High	Best
Docs plus verification checklist	Medium	Medium	High	High	Medium	Good if claims are strong
Broader architecture governance pass	Low	High	High	High	High	Too large for this PR

Recommendation

Advance with the balanced option: review DESIGN.md for factual accuracy, then add lightweight cross-links from the main docs surface so contributors can actually find it.

This keeps the PR mergeable while making the document useful as a shared architectural reference. Any deeper work, such as formalizing security guarantees, adapter contracts, or OpenClaw/Hermes comparisons, should be split into follow-up issues so this docs PR does not become a sprawling architecture redesign.