OpenClaw

Escaleras de Abstracción — L0 a L5

Componentes del Sistema

Flujos de Conocimiento — cómo sube la información

Compromisos arquitectónicos load-bearing

Diagramas — Visualización del Sistema

Modelo de dos repos de código (openclaw-core + openclaw-wany) sobre una sola KB (openclaw-kb) con namespace wany/ embebido en L3 — input para wo-1287 (blueprint de plataforma distribuible).

a) Componentes — Core ↔ Wany ↔ External

graph TB
  subgraph User["Usuario"]
    Browser["Browser
Google OAuth"]
    TGUser["Telegram
grupo personal + bot"]
  end

  subgraph Core["openclaw-core (repo 1)"]
    direction TB
    Dashboard["Dashboard
Next.js · :7001"]
    Antfarm["AntFarm
WO orchestrator"]
    Agents["Agents
SOULs + skills + workflows"]
    Vault["secrets-vault
age-encrypted"]
    TGRouter["Telegram router
topic ↔ workspace"]

    subgraph CoreKB["KB del sistema (una sola, unificada)"]
      direction TB
      KBL1["L1 · Ejecución
antfarm/output/wo-NNNN/"]
      KBL2["L2 · Operativa
memory/ · .learnings/atoms/"]
      KBL3["L3 · Estratégica
openclaw-kb/wiki/ · decisions/ · raw/
(incluye namespace wany/ tag origin:wany)"]
      KBL4["L4 · Distribución
@openclaw/* npm · MCP · idea-files"]
    end
  end

  subgraph Wany["openclaw-wany (repo 2) — sin KB propia"]
    direction TB
    Viewer["Viewer
Express · :3700"]
    Pipelines["Pipelines
providers.yaml"]
    Ingest["Ingest scripts
escriben a openclaw-kb/raw/wany/"]
  end

  subgraph Ext["External"]
    LLM["LLM providers
Anthropic · OpenRouter · Google AI · OpenAI"]
    GoogleOAuth["Google OAuth
client per-instance"]
    TGAPI["Telegram Bot API"]
    Tailscale["Tailscale Funnel
(opcional)"]
  end

  Browser -->|OAuth| GoogleOAuth
  Browser -->|HTTPS| Dashboard
  TGUser --> TGAPI
  TGAPI --> TGRouter
  TGRouter --> Antfarm
  Dashboard --> Antfarm
  Dashboard --> KBL2
  Dashboard --> KBL3
  Dashboard --> Vault
  Dashboard -->|HTTP API + per-instance token| Viewer
  Antfarm --> Agents
  Antfarm -->|escribe outputs| KBL1
  Agents --> LLM
  Agents -->|leen + escriben| KBL2
  KBL1 -->|destila atoms| KBL2
  KBL2 -->|promote validated| KBL3
  KBL3 -->|publish| KBL4
  Pipelines --> Ingest
  Ingest -->|escribe sub-tree wany/| KBL3
  KBL3 -->|HTTP API read| Viewer
  Viewer -->|read-only HTTP| Dashboard
  Tailscale -.->|Funnel opt-in| Dashboard
  

b) Deployment — macOS local con launchd

graph TB
  subgraph Mac["macOS local (1 instancia = 1 usuario)"]
    direction TB

    subgraph Svc["launchd services"]
      DashSvc["ai.openclaw.dashboard
port 7001 · next start"]
      KBSvc["ai.openclaw.openclaw-kb
port 3700 · node server.js"]
      AntCron["ai.openclaw.antfarm-cron
tick 60s"]
      Guardian["ai.openclaw.antfarm-guardian"]
      TGSvc["ai.openclaw.telegram-router"]
    end

    subgraph Data["~/.openclaw (per-instance data)"]
      WO["antfarm/work-orders/
*.json"]
      Locks["antfarm/.locks/"]
      Secrets["secrets/
age-encrypted"]
      Learn[".learnings/
atoms"]
      Mem["memory/
MEMORY.md + *.md"]
    end

    subgraph Repos["~/development-env (portable code)"]
      CoreR["openclaw-core/
dashboard + antfarm + agentes"]
      WanyR["openclaw-wany/
viewer + pipelines"]
      KBR["openclaw-kb/
wiki + decisions + raw
(incluye sub-tree wany/)"]
    end

    Brew["Homebrew deps
node · ffmpeg · whisper · age · gh"]
  end

  DashSvc --> CoreR
  KBSvc --> WanyR
  AntCron --> WO
  AntCron --> Locks
  DashSvc --> Secrets
  DashSvc --> Mem
  AntCron --> Learn
  Brew -.-> Svc
  

c) Onboarding wizard — primer arranque

sequenceDiagram
  autonumber
  actor U as Usuario
  participant W as openclaw-cli wizard
  participant FS as ~/.openclaw
  participant L as launchd
  participant V as secrets-vault
  participant T as smoke test

  U->>W: brew install openclaw (o npx create-openclaw)
  W->>U: chequeo deps (node · age · gh · ffmpeg)
  W->>U: ¿Anthropic key? · ¿OpenRouter? · ¿Google AI? · ¿OpenAI?
  U->>W: BYO keys
  W->>U: ¿Google OAuth client (Cloud Console steps)?
  U->>W: client_id + client_secret
  W->>U: ¿BotFather token + chat_id grupo + topic_id?
  U->>W: token + ids
  W->>V: encrypt + store secrets
  W->>FS: scaffold antfarm/ memory/ .learnings/ secrets/
  W->>L: render plists con paths absolutos del usuario
  W->>L: bootstrap dashboard + viewer + antfarm-cron + tg-router
  W->>T: curl :7001/health · :3700/wany · ping a TG
  T-->>W: all green
  W->>U: dashboard listo en http://localhost:7001
  

d) Data flow L0 → L4 — destilación con hooks actuales

graph BT
  subgraph L0["L0 · Código"]
    Code["git repos · commits"]
  end
  subgraph L1["L1 · Ejecución"]
    WOrun["WO output
antfarm/output/wo-NNNN/"]
    Logs["agent logs"]
  end
  subgraph L2["L2 · Operativa"]
    Atoms[".learnings/atoms/
tagged learning·decision·insight"]
    Memory["memory/MEMORY.md
workspace-scoped"]
  end
  subgraph L3["L3 · Estratégica (KB unificada)"]
    Wiki["openclaw-kb/wiki/
(incl. wany/ namespace)"]
    ADRs["openclaw-kb/decisions/"]
    Raw["openclaw-kb/raw/
(incl. wany/ pipelines)"]
  end
  subgraph L4["L4 · Distribución (dual-track)"]
    direction LR
    subgraph L4code["código compilado"]
      Npm["@openclaw/wany-core
npm package"]
      MCP["MCP server"]
      Public["Viewer público"]
    end
    subgraph L4spec["idea-files (specs abstractas)"]
      Ideas["ideas/
markdown · SemVer · maturity"]
      AgentSpecs["agent-specs/
provider-agnostic SOULs"]
    end
  end

  Code -->|diff-to-atom extractor · post-verify hook| WOrun
  WOrun -->|floor tag+dedupe · wo-1250 WIP| Atoms
  Logs --> Atoms
  Atoms -->|human review + promote · brain-commit ritual| Wiki
  Atoms -->|human review| ADRs
  Memory -->|validated patterns| Wiki
  Wiki -->|npm publish · kb-contract.json semver| Npm
  ADRs --> Npm
  Raw --> Npm
  Npm --> MCP
  Npm --> Public
  Wiki -->|abstrae intención| Ideas
  Wiki -->|extrae SOUL/skills| AgentSpecs
  Ideas -.->|agente del receptor compila| L4code
  

Paradigma idea-file — distribuir intención, no implementación

Inspirado en Karpathy. Documentado en openclaw-kb/wiki/views/company-as-code/idea-file-*.md (7 docs) y convergente con la tesis de shared context: cuando los agentes son indistinguibles entre Claude, Codex y Gemini, la unidad de valor deja de ser código compilado y pasa a ser la spec abstracta que cualquier agente recompila al stack del receptor.

Versionado, git y brain-commit — la KB como organismo evolutivo

Tomado de la tesis de shared-context: "Una KB sin historia es estática — el historial de la KB es tan valioso como la KB misma". La promoción no es un evento opaco: es un commit con mensaje que explica el porqué del cambio.

Estado actual vs. Visión