Chapter 5: Paperclip rollout design

Design goal: prove Paperclip can safely replace our custom PM/Dev orchestration layer while preserving OpenClaw Telegram intake, GitHub source of truth, and Codex execution.

Non-goals

No hosted Paperclip SaaS for the first pilot.
No broad machine, GitHub org, or private-data access.
No automatic merges.
No migration away from GitHub issues as durable public memory.
No direct Telegram-to-Paperclip bridge until the local pilot is stable.

Architecture

Component	Role	Pilot setting
OpenClaw main obot	Telegram intake, user-facing summaries, final escalation.	Remains current front door.
Paperclip	Agent-team control plane: org chart, tickets, heartbeats, budgets, audit.	Self-hosted local loopback only.
PM agent	Portfolio audit, issue hygiene, queue selection, Human ToDo gate.	Read/write only inside obot-claw pilot scope.
Dev agent	Codex-backed implementation, checks, PR evidence.	One safe repo, docs-only first task.
GitHub	Public source of truth and PR workflow.	Existing obot-claw issues/PRs remain canonical.
Codex	Executor for PM/Dev reasoning and repo work.	Local Codex first; cloud/GitHub Codex later.

Phase 0: source and security review

Clone Paperclip from the official GitHub repo into a dedicated local directory.
Pin exact commit and record SHA in a local setup note.
Inspect package scripts, install hooks, environment variables, telemetry defaults, ports, database storage, and adapter docs.
Disable telemetry before any private context enters the system.
Run only on localhost. If remote access is needed later, use tailnet/VPN rather than public exposure.
Create a low-scope GitHub token or GitHub App installation for the pilot. No personal broad token.

Phase 1: install and local smoke test

Install in a dedicated workspace, not inside the main OpenClaw repo.
Use embedded/local database first.
Create one company: Open Source OrangeBot.
Create roles: Jeremy as board/approver, obot as orchestrator, PM agent, Dev agent.
Run one no-op task that records a heartbeat and completion artifact.

Phase 2: PM-only pilot

Create a Paperclip ticket linked to the GitHub autonomous workflow issue.
PM agent reads current queue, Hub reports, and GitHub issue state.
PM agent produces a portfolio audit note and chooses a Dev candidate or declines with reason.
OpenClaw sends Telegram summary only after Paperclip and GitHub artifacts exist.

Phase 3: Dev pilot

Pick a safe documentation-only task in obot-claw.github.io.
Dev agent uses Codex local with scoped write access.
Dev opens or updates one PR. No merge.
Paperclip must show owner, task, heartbeat, budget/cost if available, approval status, and output artifact.

Acceptance tests

Test	Pass condition
Started vs triggered	Paperclip distinguishes accepted ticket from running agent with heartbeat.
Stall detection	Artificially stalled agent is marked failed and surfaced without Jeremy asking.
GitHub linkage	Paperclip task links to GitHub issue/PR without replacing GitHub source of truth.
Telegram hygiene	OpenClaw sends under-500-character plain text summary only after durable artifact exists.
Security containment	Telemetry off, localhost only, scoped token only, no broad secrets.
PM → Dev handoff	PM can assign Dev through Paperclip and Dev can create a PR with evidence.

Implementation issues to create

Issue	Purpose	Owner
Project: Autonomous agent orchestration pilot	Parent Project issue for Paperclip pilot.	PM
Requirement: Paperclip local security review	License, install, telemetry, secrets, ports, scoped credentials.	PM/security
Requirement: Paperclip PM-only pilot	Read portfolio, produce durable audit, choose/decline Dev target.	PM
Requirement: Paperclip Dev pilot	Codex-backed docs PR with evidence and no merge.	Dev
Task: Telegram summary bridge	OpenClaw reads Paperclip/GitHub state and sends concise summaries.	Dev
Task: Failure injection test	Prove stalled/failed agent is detected and reported.	Dev/testing

Rollback plan

If Paperclip requires broad secrets or hosted SaaS to work, stop the pilot.
If Paperclip cannot expose durable run state, stop the pilot.
If adapter work becomes as large as building our own runner, fall back to the v3 supervised Codex runner plan.
Keep all GitHub issues/PRs as source of truth so rollback does not lose project state.

Next concrete action

Next: create the Project/Requirement/Task issue set for the Paperclip pilot, then run Phase 0 source/security review before installing or giving Paperclip any credentials.