OpenClaw ACP Architecture

The Dockyard

The Dockyard is the dedicated Telegram control surface for project-specific ACP harnesses. It separates coding-agent operations from The Ark’s general coordination space, so every topic maps cleanly to one repository, one runtime, and one durable session.

Telegram forum topics OpenClaw routing ACPX backend Harness inferred from binding

Core request pathgroup → topic → binding → harness

Telegram TopicHuman asks inside a simple project topic, e.g. Cafein.

→

OpenClaw BindingPeer id + account route to an internal ACP agent id.

→

ACP HarnessPersistent coding runtime starts in the configured repository cwd.

What The Dockyard does

It is a port for work: each topic docks one project/harness combination, keeping context, cwd, and routing predictable.

Why this exists

1Reduce cross-talk. The Ark remains the shared coordination/home base. The Dockyard is for operational ACP control, where messages should usually become coding-agent work.
2Keep topic names simple. A topic name should identify the project. The harness is inferred from the OpenClaw binding/runtime, not encoded in the public topic name.
3Preserve ongoing work. Existing BTA/zainf sessions are left untouched unless explicitly migrated. The Dockyard starts clean with Cafein.
4Keep the system self-describing. The architecture should be clear enough that any agent or human can understand the boundary without relying on chat history.

Current live state

Public version: Telegram numeric IDs and private repository details are intentionally redacted. Internal config retains the exact peer IDs, repository cwd, and remote URL.

GroupThe Dockyard
Telegram group id [redacted]

GeneralTopic 1, allowlisted with requireMention: true.

CafeinTopic 7, allowlisted with requireMention: false.

Peer[redacted]:topic:7

Topic model

ACTIVE

Cafein

Bound to pi-cafein. The configured runtime runs OpenCode through ACPX in the Cafein project repository.

PLANNED

zainf

Intended Codex ACP route. Existing topic/session should not be disturbed until explicitly migrated.

LEAVE AS-IS

BTA

BTA still uses Claude because Zain has Claude Teams. Do not move or reset ongoing work casually.

Cafein binding details

{
  "type": "acp",
  "agentId": "pi-cafein",
  "match": {
    "channel": "telegram",
    "accountId": "optimus",
    "peer": {
      "kind": "group",
      "id": "[redacted]:topic:7"
    }
  },
  "acp": {
    "label": "cafein-opencode"
  }
}

Cafein runtime details

agent id: pi-cafein
runtime: acp
backend: acpx
harness: opencode
mode: persistent
cwd: [redacted local repository path]
remote: [redacted repository remote]

Operational rules for agents

AOne topic = one workstream. Do not reuse Cafein’s topic for BTA, zainf, or generic bot chatter.
BRespect persistent sessions. If cwd/runtime changes, old ACP sessions may need reset before the harness sees the new config.
CDo not rename internal IDs just for aesthetics. IDs like pi-cafein may preserve bindings even if display/runtime changed.
DVerify with a smoke prompt. Ask the topic to report cwd and repo root before assigning real work.

Smoke test

After creating or changing an ACP binding, send this in the target Dockyard topic:

Report your current working directory and list the repository root. Do not modify files.

The Cafein topic should report:

[redacted local repository path]

Future expansion model

Topic namingFuture docks should use simple project names, e.g. Cafein or zainf. The harness remains an implementation detail inferred from the binding/runtime.

Access boundaryGeneral remains a low-noise, mention-required coordination topic. Project topics are expected to be direct control surfaces and can be non-mention-required when intentionally bound.

Runtime boundaryEach dock should resolve to one configured ACP runtime with one repository cwd. That keeps persistent sessions predictable and reduces accidental cross-project context.

Migration policyExisting BTA and zainf ACP work should be migrated deliberately, not implicitly. The Dockyard can host those docks later, but current workstreams remain stable until moved on purpose.

Verification patternAny newly created or changed dock should first prove its current working directory and repository root before it receives implementation work.

Known caveats

!Auth can be separate from routing. A topic may route correctly while a model/harness auth is expired.
!SSH remotes may fail on this host. Cafein is currently bound over an HTTPS remote in internal config, which is intentional after SSH permission failure.
!Persistent ACP state can outlive config changes. Reset sessions if a topic keeps reporting an old cwd.

Short summary

The Dockyard is an ACP operations port. Its job is to give each project a clearly named Telegram topic that routes to exactly one configured repository, one coding harness, and one durable working context. The first live dock is Cafein; repository and harness details are represented at the architecture level, with private repository details redacted in this public version.