Home/Docs/System Architecture

How the workspace fits together

This is a human-supervised personal AI workspace. It combines a conversational assistant, connected tools, memory, scheduled automation, and an optional layer for persistent specialist tasks.

The key is knowing which part owns the conversation, which part tracks the work, and where you check the result.

Three layers, three jobs

LayerMain jobWhat to expect
OpenClawConversation, tools, memory, and scheduled jobsThe assistant interface and gateway to connected capabilities
PaperclipPersistent tasks, roles, and execution runsAn optional work layer for bounded assignments with owners, status, and deliverables
MissionControlPrivate dashboard, controls, and healthA place to inspect activity and manage the workspace

These are separate execution paths. A chat request does not automatically become a specialist task. A dashboard showing a configured role does not prove that role has run or produced useful work.

Direct work or a tracked assignment?

Use the conversational assistant for a question, a small tool request, or a draft you can review in the same session.

Use a persistent task when the work needs a named owner, a clear deliverable, verification, or a handoff. For example, a research assignment might ask for a short comparison, source links, and unresolved questions. The result belongs with that task so the coordinator can reconcile it with the original request.

Creating a task is only the start. Completion means the requested result exists, the relevant checks are recorded, and the next owner can inspect it.

Models and providers

In this workspace, Codex through the existing OpenAI subscription is the primary execution path. Claude Code is a deliberate exception for selected coding and architecture work, and Riley uses Claude Opus for communication drafting. See model routing for thinking, execution, and cross-family review. Local models are optional when they fit the task, hardware, and data requirements.

This describes the workspace's provider choices. It does not promise that a particular plan, model, or integration is available to every reader. Check current support, authentication, usage limits, and terms before choosing your own setup. Subscription access and separately billed API access should be treated as distinct choices. Never silently switch to a paid fallback when the intended route is unavailable.

Memory and data boundaries

Keep only the context a task needs. Separate personal, teaching, and client work, and give tools the narrowest useful permissions. A workspace boundary helps organize access; it is not an operating-system security barrier.

Local storage does not guarantee local inference. Before using a cloud model, check what the prompt and tool results will send. Keep credentials out of prompts, logs, and published examples.

Drafting and delivery are separate permissions. Sending messages, publishing content, changing records, and making consequential decisions require explicit authorization. A draft does not close a reply obligation.

Deployment and execution boundaries

Conversation routing and named roles do not create OS isolation. Decide separately whether the gateway is native, in a container, or in a VM, which tools are sandboxed, and which bridges can reach host apps. See Native, VM, or Docker?.

Start small

Begin with one assistant and one useful task. Add a tool, then one bounded automation after you can inspect its inputs and outputs. Add Paperclip only when persistent ownership and handoffs solve a problem you actually have. MissionControl is an optional private management surface, not a prerequisite for learning.

Architecture describes responsibilities. Operational readiness still needs a dated, end-to-end check.