# Overview

How OpenClaw functions and how its systems and services relate.

# Functional Overview

OpenClaw is the coordination layer for Christopher Tan’s personal AI and homelab workflows. It routes conversations to the configured default OpenAI model, can delegate coding work to the local OpenVINO model, records durable context in workspace and BookStack documentation, and connects approved integrations such as email, Paperless-ngx, Home Assistant, UniFi, Proxmox and chat channels.

## Operating principles

- Prefer read-only inspection and reversible changes.
- Trial newly requested ongoing actions once before promoting them.
- Keep credentials in protected storage; documentation contains names, relationships and safe configuration references only.
- Require approval for external, destructive, public, credential, scheduler and live-configuration actions.
- Verify API-backed changes with a fresh read-back.

## Relationship summary

OpenClaw is the orchestrator; BookStack is the human-readable knowledge base; workspace files hold agent behaviour and identity; model providers supply hosted or local inference; plugins and skills provide capabilities; service integrations expose narrowly scoped operational data.

# Systems and Services Diagram

```mermaid
flowchart LR
  U[Christopher / chat channels] --> O[OpenClaw Gateway]
  O --> M[OpenAI GPT-5.6 Luna
Default model]
  O --> L[OpenVINO / LocalAI
Local coding model]
  O --> B[BookStack
Documentation]
  O --> E[Email accounts and IMAP/SMTP]
  O --> P[Plugins and skills]
  P --> S[Approved services]
  S --> N[UniFi network and Protect]
  S --> X[Proxmox inventory]
  S --> H[Home Assistant]
  S --> D[Paperless-ngx]
  W[Workspace files
AGENTS / SOUL / USER / IDENTITY] <--> O
```

The diagram is conceptual. Credentials, tokens and passwords are intentionally omitted. Relationships are implemented through protected configuration and approval-gated workflows.

# Plugins

Plugins extend the Gateway with provider-specific tools and channel or UI capabilities. They are selected by capability and policy, not by embedding credentials in pages.

## Documented relationships

- Channel plugins deliver conversations and outbound messages after approval.
- BookStack integration publishes and verifies documentation through the protected API.
- Email tooling connects to IMAP/SMTP using protected account credentials; message content is handled separately from configuration.
- Browser, canvas, voice and dashboard plugins provide interaction surfaces; they do not replace service authentication.
- Proxmox, UniFi, Home Assistant and Paperless integrations are service-specific and should remain least-privilege.

Plugin names and runtime settings may be inspected in the redacted runtime configuration page. Secrets are never copied here.

# Skills

Skills are reusable procedures that tell OpenClaw how to perform a class of work safely. They sit above plugins and APIs: a skill selects tools, applies validation and approval boundaries, and specifies what evidence is required.

## Documented relationships

- `bookstack-controlled-sync` uses the BookStack API and requires fresh read-back verification.
- `paperless-ngx` uses the Paperless REST API for document workflows.
- `proxmox-readonly` limits Proxmox work to inventory and health reads.
- `configure-channel`, `add-model-provider` and protected-secret procedures handle setup without exposing credentials.
- Browser, email, voice and control-UI skills use their corresponding plugins or provider tools.

Skills describe procedures, while plugins expose capabilities and services hold the underlying data.

# Email Accounts/Connections

OpenClaw can use separate email connections for IMAP retrieval and SMTP delivery. Account passwords and app passwords remain in protected credentials and are not documented here.

## Relationships

- IMAP is used for controlled inbox retrieval and document or workflow triage.
- SMTP is used only for explicitly approved outbound delivery.
- AgentMail is a separate API-based agent inbox service, not the same as a personal IMAP/SMTP mailbox.
- Gmail and mail.com connections are separate accounts with separate protected credentials and host allowlists.
- Email skills and automations call the connection layer; BookStack records the safe configuration model, not message secrets.

## Safe configuration references

Documented settings include provider hostname, protocol, port, enabled state and workflow ownership. Credentials, tokens, mailbox contents and message bodies are excluded.