Architecture Proposal · 2026-04-25 · Separate from Blueprint

OpenClaw Multi-Agent Platform

Architektura i specyfikacja platformy agentów AI dla Nova AI Ventures — jak działa, z czego się składa, jak komponenty ze sobą współpracują. Bez szczegółów implementacyjnych · bez treści plików konfiguracyjnych.

1. Cel i zakres

Platforma agentów AI dla 15–50 pracowników Nova AI Ventures. Składa się z dwóch typów agentów: osobistych asystentek (jedna per użytkownik) oraz wspólnych agentów specjalistycznych dostępnych dla całego zespołu.

🤖 TYPY AGENTÓW · DWÓCH TYPÓW

Asystentki osobiste (1 per użytkownik)

Każdy pracownik ma własną, spersonalizowaną asystentkę. Zna jego styl pracy, preferencje, kalendarz. Kontaktuje się z nim przez Slack DM, Telegram lub web dashboard.

Wspólni agenci specjalistyczni (dostępni dla całego zespołu)

Użytkownicy mogą bezpośrednio kontaktować się z dowolnym agentem specjalistycznym. Lista otwarta — jeden nowy plik YAML = nowy agent.

🏛️

CTO

Architektura · code review · decyzje techniczne

💻

Developer

Pisanie kodu · PR-y · debugowanie

🧪

Tester / QA

Testy · raporty błędów · E2E

⚙️

DevOps

Deploye · infrastruktura · monitoring

📋

Product Owner

Wymagania · backlog · zatwierdzanie

📢

Marketing

Content · SEO · social media

📈

Sales

Leady · follow-upy · CRM

⚖️

Legal

Przegląd umów · compliance

📊

Analyst

Dane · raporty · insighty

🔒

Security

Audyty · testy penetracyjne

💰

Revenue

Pricing · monetyzacja · metryki

📱

iOS Developer

Swift/SwiftUI · TestFlight

➕

(nowa rola)

Jeden YAML = nowy agent

Co agenci potrafią:

Prowadzić rozmowę przez Slack, Telegram lub web dashboard
Czytać i pisać do kalendarza (Google Calendar, Microsoft 365)
Pisać kod, tworzyć PR-y, mergować zmiany na GitHubie
Budować obrazy Dockerowe i deployować aplikacje na staging/produkcję
Uruchamiać testy (jednostkowe, integracyjne, E2E)
Wysyłać emaile, zarządzać CRM, przeglądać umowy
Przekazywać zadania innym agentom i uczestniczyć w wieloetapowych pipeline’ach

2. Infrastruktura · topologia

Platforma składa się z trzech Hetzner serwerów + Mac Mini w MacStadium dla buildów iOS, połączonych prywatnym vSwitch (10 Gbps, 0.2 ms).

🧠 Gateway

Hetzner CPX31 · 4 vCPU / 8 GB RAM · ~EUR 15/mies.

OpenClaw Gateway
LiteLLM Proxy
PostgreSQL (agenty + audit)
Slack / Telegram boty
Infisical (self-hosted)

🌐 Publiczne IP · port 3000 Studio

🚀 App Server

Hetzner AX52 · 16 vCPU / 64 GB RAM · ~EUR 50/mies.

Traefik (reverse proxy, TLS)
Deployed app stacks (per branch)
PostgreSQL per projekt
Redis per projekt
Prometheus + Grafana

🌐 Publiczne IP · port 80 / 443

🔨 Build Server

Hetzner AX102 · 48 vCPU / 128 GB RAM · ~EUR 99/mies.

Docker daemon (TLS, port 2376)
GitHub Actions runner
Test runners (Playwright, pytest)

🔒 Brak publicznego IP · tylko private vSwitch

🗺️ MAPA SIECI · PRIVATE VSWITCH 10.0.0.0/16

Internet
    │
    ├── GATEWAY         10.0.1.1   · Hetzner CPX31   · 4 vCPU  /   8 GB
    │
    ├── APP SERVER      10.0.1.2   · Hetzner AX52    · 16 vCPU /  64 GB
    │
    └── BUILD SERVER    10.0.1.3   · Hetzner AX102   · 48 vCPU / 128 GB
         (bez publicznego IP · tylko vSwitch)

Private vSwitch Hetzner · 10 Gbps · 0.2 ms

MacStadium M2 Mac Mini      ~$109/mies.    · SSH z Gateway lub Build Server
    └── Xcode + Fastlane — buduje aplikacje iOS

Dlaczego 3 osobne serwery (nie jeden)?

Problem	Rozwiązanie
10+ równoległych buildów Dockera zużywa 40+ rdzeni — zabiłoby Gateway	Build Server oddzielony · crash buildera nie wpływa na agentów
Deployed aplikacje potrzebują stałego IP + wildcard DNS	App Server ma stały publiczny IP + Traefik
Gateway musi być stabilny 24/7	Nie builduje, nie serwuje aplikacji — tylko orkiestruje

Jak Gateway rozmawia z Build Serverem: docker polecenia przez Docker Remote API (TLS) na prywatnej sieci tcp://10.0.1.3:2376. Z perspektywy agenta identyczne jak lokalny Docker — ta sama komenda, 0.2 ms opóźnienia.

Jak aplikacje lądują na App Server: Build Server buduje obraz → push do rejestru (GHCR / Harbor) → Gateway przez SSH/Docker context wydaje docker compose up -d na App Server → Traefik wykrywa stack i tworzy routing branch.projekt.nova.dev.

3. Stos technologiczny

Open-source gdzie tylko można. Self-hosted gdzie bezpieczeństwo i niezależność mają znaczenie.

🔧 STOS · CO GDZIE DZIAŁA

Warstwa	Technologia	Rola
Agent platform	OpenClaw (TypeScript, OSS)	Zarządza agentami, rozmowami, toolami
LLM routing	LiteLLM Proxy	Jeden endpoint, wiele modeli
LLM provider	OpenAI API (GPT-4o / GPT-4o-mini)	Inteligencja agentów
Workflow engine	Lobster (wbudowany w OpenClaw)	YAML pipelines · human approval gates
Agent-to-agent	A2A Protocol (plugin OpenClaw)	Komunikacja między agentami
Container builds	Docker (Remote API / TLS)	Izolowane buildy na Build Server
Reverse proxy	Traefik v3	Wildcard TLS, Let’s Encrypt, routing per branch
CI/CD	GitHub Actions (self-hosted runner)	Automatyczne testy i deploye
Monitoring	Prometheus + Grafana	Metryki serwerów, agentów, kosztów API
Alerting	Alertmanager → Slack	Alerty na `#ops-alerts`
Audit	PostgreSQL	Logi każdej akcji agenta
iOS builds	Fastlane na MacStadium	Xcode, TestFlight, App Store
Secrets	Infisical (self-hosted)	Zarządzanie infrastrukturalnymi sekretami
DNS	Wildcard `*.nova.dev`	Auto-routing nowych deploymentów

4. Architektura agentów

Trzy warstwy: od najbardziej końcowego (pipeline) do najbardziej osobistego (asystentka per użytkownik).

Warstwa 3 · Pipeline Workflows

Sekwencje kroków między agentami

Lobster YAML definiuje multi-agent pipeline’y: feature-development, hotfix, contract-review, incident-response. Z human approval gates tam gdzie trzeba.

▼

Warstwa 2 · Role Templates

Rola = jeden plik YAML

Każda rola zdefiniowana przez YAML: narzędzia, uprawnienia, system prompt. Dodanie nowej roli = dodanie jednego pliku bez pisania kodu.

▼

Warstwa 1 · Personal Assistants

Jeden agent per użytkownik

Ma SOUL.md (osobowość), auth profile (OAuth tokeny), kanały (Slack DM / Telegram / Web), uprawnienia roli.

👤 DWIE KRYTYCZNE KONCEPCJE

SOUL.md · osobowość agenta

Każdy agent ma plik SOUL.md definiujący styl komunikacji, ton, nawyki. Nadpisywany per użytkownik. Przykładowo: jeden woła krótkie odpowiedzi, inny szczegółowe wyjaśnienia.

Auth Profile · izolacja danych użytkownika

Każdy agent ma własny zaszyfrowany profil auth w ~/.openclaw/agents/<agentId>/auth-profiles.json. Przechowuje tokeny OAuth (Google Calendar, M365, GitHub, Slack). Zero wycieku między agentami — agent Jana nigdy nie widzi tokenów Marka.

Jak użytkownik łączy konta

Admin tworzy profil agenta

openclaw agent create --name "Asystent Jan" --template developer

Jan otwiera OpenClaw Studio

Web dashboard · widzi listę dostępnych integracji

Jan klika “Connect Google Calendar”

Standardowy OAuth flow w przeglądarce

Token zapisany tylko w profilu Jana

AES-256 encryption · klucz pochodny od OPENCLAW_SECRET + agentId

5. Przepływ pracy

Jak wygląda typowy request — od wiadomości na Slacku do działającego kodu w repo.

🔁 TYPOWY REQUEST · END-TO-END

Jan na Slacku: “Napisz mi test dla funkcji validateEmail”
        │
        ▼
Slack Bot odbiera wiadomość → przekazuje do OpenClaw Gateway
        │
        ▼
Gateway identyfikuje agenta Jana (developer-jan)
Ładuje: auth profile Jana + role template developer + SOUL.md Jana
        │
        ▼
LiteLLM Proxy → OpenAI GPT-4o-mini (lub GPT-4o dla złożonych zadań)
        │
        ▼
Agent czyta repozytorium GitHub Jana
Pisze test, commituje na branch
Uruchamia testy przez Docker Remote API na Build Server
Raportuje wynik Janowi przez Slack DM
        │
        ▼
Każda akcja zapisana w PostgreSQL audit log

Kiedy jeden agent wywołuje drugiego (A2A)

Przykład: developer-jan tworzy PR → automatycznie triggeruje pipeline Lobster → tester-agent uruchamia testy → po-agent przegląda → devops-agent deployuje.

🤝 A2A · AGENT CALLS AGENT

dev-jan: “PR gotowy”
    → Lobster triggeruje pipeline ‘feature-development’
    → tester-agent: uruchamia E2E testy na staging URL
    → po-agent: dostaje notyfikację, przegląda, zatwierdza (human approval gate)
    → devops-agent: merguje PR, deployuje na produkcję
    → #deployments: powiadomienie o sukcesie

6. Deploy pipeline · od kodu do produkcji

8 kroków. Pełna automatyzacja z wyjątkiem human approval gate dla produkcji.

Dev Agent pisze kod

Pushuje branch na GitHub

BUILD (Build Server)

Gateway → Docker Remote API (10.0.1.3:2376) · docker build → docker push (GHCR/Harbor)

DEPLOY STAGING (App Server)

docker compose -p "{projekt}-{branch}" up -d · Traefik auto-tworzy: https://feature-xyz.projekt.nova.dev

WERYFIKACJA (Dev Agent)

curl health endpoint · inspekcja DB, logów, plików przez private vSwitch · Playwright z Build Server targetujący App Server URL

QA (Tester Agent)

Playwright E2E testy na staging URL · raport dla PO

APPROVAL (PO Agent)

Human approval gate w Lobster · przegląda live staging + raport testów

PRODUKCJA (DevOps Agent)

docker compose -p "{projekt}-main" up -d · health check przez 5 minut · post do #deployments

CLEANUP

Stare branch stacks usuwane po 7 dniach (configurable TTL)

Routing subdomen (Traefik)

🌐 TRAEFIK · WILDCARD ROUTING

*.nova.dev → App Server (wildcard DNS)
    │
    Traefik dynamicznie routuje po Docker labels:
    │
    ├── main.nova-pa2.nova.dev           → produkcja projektu nova-pa2
    ├── feature-auth.nova-pa2.nova.dev   → branch feature-auth
    ├── staging.nova-mgmt.nova.dev       → staging nova-management
    └── traefik.nova.dev                 → dashboard Traefik (auth)

Dostęp agenta do działającej aplikacji

Co	Jak
Logi kontenerów	`docker logs -f` przez Docker Remote API na App Server
Pliki aplikacji	SSH + read `/var/apps/{projekt}/{branch}/`
Baza danych	Bezpośrednie połączenie PostgreSQL przez private vSwitch
Shell	`docker exec` dla debugowania runtime
HTTP	`curl` endpointów, sprawdzenie odpowiedzi
Browser	Playwright na Build Server targetujący URL App Server

7. Integracje zewnętrzne

Co agenci podpinają i po co — cztery kategorie integracji.

📅 Kalendarze

Google Calendar API — OAuth 2.0 per user · pełny CRUD + koordynacja zespołu
Microsoft Graph API — OAuth 2.0 per user · pełny CRUD
Read/write eventów, proaktywne sugestie, wykrywanie konfliktów, znajdowanie wspólnych slotów

💬 Komunikacja

Slack Bot — DM + kanały + wątki
Telegram Bot — per-user chaty
OpenClaw Studio — web dashboard z chat UI

💻 Development

GitHub — PAT lub GitHub App · pełna autonomia (PR, merge, issues, releases)
Docker Remote API — TLS mutual auth do Build Server
SSH — per-agent klucze do App Server i MacStadium

💼 Biznesowe

Email — Gmail (Google API) + Outlook (Graph API) · OAuth per user
Jira / Linear — task management
Notion — dokumentacja i notatki
CRM — HubSpot / Pipedrive API

8. Zarządzanie sekretami i hasłami

Dwie całkowicie oddzielone kategorie poświadczeń — infrastrukturalne (wspólne) i użytkownika (izolowane per agent).

🔒 DWIE KATEGORIE SEKRETÓW

Kategoria	Przykłady	Kto ma dostęp
Infrastrukturalne (wspólne)	OpenAI API key, Postgres password, LiteLLM master key, OpenClaw secret, TLS certs	Tylko administratorzy platformy
Użytkownika (izolowane per agent)	Google Calendar OAuth token, M365 OAuth token, GitHub PAT, Slack token	Wyłącznie agent danego użytkownika

Kluczowa zasada: żaden agent nie ma dostępu do sekretów infrastrukturalnych ani do poświadczeń innego agenta.

Sekrety infrastrukturalne · Infisical (self-hosted)

Zamiast ręcznych .env plików używamy Infisical — open-source secrets manager (porównywalny do HashiCorp Vault, ale prostszy).

🗄️ INFISICAL · ENVIRONMENT STRUCTURE

Infisical (self-hosted na Gateway)
    │
    ├── Environment: gateway
    │   ├── OPENAI_API_KEY
    │   ├── LITELLM_MASTER_KEY
    │   ├── POSTGRES_PASSWORD
    │   └── OPENCLAW_SECRET
    │
    ├── Environment: app-server
    │   ├── TRAEFIK_DASHBOARD_CREDENTIALS
    │   └── GRAFANA_PASSWORD
    │
    └── Environment: build-server
        └── DOCKER_TLS_CERT (path reference)

Dlaczego Infisical a nie .env pliki:

Web UI z przeglądem wszystkich sekretów (kto, kiedy, co zmienił)
Role-based dostęp — nowy admin dostaje tylko te sekrety, które potrzebuje
Secret versioning — historia zmian, możliwość rollback
Audit log — każde odczytanie sekretu jest logowane
SDK/Docker integration — serwisy pobierają sekrety przy starcie dynamicznie
Self-hosted → sekrety nigdy nie opuszczają infrastruktury Nova AI Ventures

Alternatywa (prostsza): .env pliki szyfrowane przez sops + age. Prostsze, ale brak UI i auditu.

Sekrety użytkownika · OpenClaw Auth Profiles

👤 AUTH PROFILES · IZOLACJA PER AGENT

~/.openclaw/agents/
    ├── developer-jan/
    │   └── auth-profiles.json    ← zaszyfrowany AES-256, tylko dla agenta Jana
    ├── developer-anna/
    │   └── auth-profiles.json    ← izolowany, tylko dla agenta Anny
    └── devops-shared/
        └── auth-profiles.json    ← token GitHub Org, tylko devops-agent

Szyfrowanie: AES-256 z kluczem pochodnym od OPENCLAW_SECRET + agentId
Zero dostępu cross-agent na poziomie aplikacji i systemu plików
Backup: codziennie szyfrowany backup całego ~/.openclaw/agents/ na Backblaze B2

Co nigdy nie trafia do git

.gitignore blokuje: pliki .env, klucze TLS (*-key.pem), klucze Apple (.p8), auth-profiles.json, katalog secrets/. Git zawiera wyłącznie szablony bez wartości (np. .env.example).

Backup sekretów

Co	Gdzie	Częstotliwość	Szyfrowanie
Infisical (eksport)	Backblaze B2	Codziennie	age encryption (klucz offline przez admin)
`~/.openclaw/agents/`	Backblaze B2	Codziennie	AES-256
TLS certyfikaty Docker	Backblaze B2	Po każdej zmianie	age encryption

Rotacja poświadczeń

OpenAI API key — rotacja w panelu OpenAI → aktualizacja w Infisical → restart serwisów
OAuth tokeny użytkowników — automatycznie odświeżane przez OpenClaw (refresh token flow)
TLS certs Docker — ważność 10 lat · rotacja ręczna z procedurą

Onboarding nowego admina

Nowy admin dostaje:

SSH key dodany do wszystkich serwerów
Konto w Infisical z uprawnieniami do konkretnych środowisk (nie wszystkiego)
Klucz deszyfrowania backupów — przekazany offline, fizycznie lub przez zaszyfrowany kanał

9. Bezpieczeństwo sieciowe i RBAC

Każdy agent ma uprawnienia wynikające z szablonu roli. Approval gates na krytycznych operacjach. Izolacja tokenów i TLS mutual auth wszędzie tam, gdzie to możliwe.

🛡️ ZASADY BEZPIECZEŃSTWA

Każdy agent ma uprawnienia wynikające z szablonu roli (YAML)
Approval gates na krytycznych operacjach (deploy prod, merge do main, emaile)
Izolacja tokenów — zaszyfrowane per agent, zero dostępu cross-agent
TLS mutual auth dla Docker Remote API
Private vSwitch — Build Server i App Server nie są dostępne z internetu
Per-agent SSH keys — każdy agent ma własny klucz do produkcji

RBAC · macierz uprawnień

Uprawnienie	CTO	DevOps	Developer	Tester	PO	Marketing	Sales	Legal
GitHub push	✓	✓	✓	✗	✗	✗	✗	✗
GitHub merge	✓	✓	✗	✗	✓	✗	✗	✗
Deploy staging	✓	✓	✓	✓	✗	✗	✗	✗
Deploy prod	✓	✓	✗	✗	approve	✗	✗	✗
Kalendarz team	read	✗	✗	✗	r/w	✗	✗	read
Email send	✓	✗	✗	✗	✓	✓	✓	✓
DB prod	✓	RO	✗	✗	✗	✗	✗	✗
CRM write	✗	✗	✗	✗	✗	✓	✓	✗

10. Audit trail i monitoring

Każda akcja każdego agenta zapisana · pełna observability dla serwerów, agentów i kosztów API.

📝 AUDIT TRAIL · POSTGRESQL

Każdy zapis zawiera:

Kto: agent_id · user_email
Co: action_type: tool_call · deploy · email_send · calendar_write · llm_request
Na czym: target: URL, plik, serwer
Wynik: success / failure + error_message
Koszt: tokeny · koszt USD · model
Kontekst: pipeline_id · session_id

Krytyczne akcje (deploy prod · merge main · email zewnętrzny) → natychmiastowa notyfikacja na Slack #agent-audit.

Monitoring

Co	Narzędzie	Gdzie widać
CPU/RAM/Disk serwerów	Prometheus + node-exporter	`grafana.nova.dev`
Aktywne agenty, queue	OpenClaw metrics	`grafana.nova.dev`
Koszty OpenAI API	LiteLLM metrics → Prometheus	`grafana.nova.dev`
Success rate pipeline’ów	Lobster metrics	`grafana.nova.dev`
Alerty ops	Alertmanager	Slack `#ops-alerts`
Uptime	UptimeRobot	Email / Slack

11. Struktura katalogów

Monorepo z trzema obszarami: infra (konfiguracja serwerów), agents (role, osobowości, pipeline’y), docs (ADR-y i specyfikacje).

📁 STRUKTURA PROJEKTU

nova-openclaw-platform/
│
├── infra/
│   ├── gateway/           ← OpenClaw + LiteLLM + Postgres + Infisical
│   ├── build-server/      ← TLS setup Docker Remote API + GitHub runner
│   ├── app-server/        ← Traefik + Prometheus/Grafana
│   ├── macstadium/        ← setup iOS build machine
│   └── scripts/           ← provision, deploy, verify, onboard
│
├── agents/
│   ├── roles/             ← YAML szablony (developer, tester, devops, ...)
│   ├── soul/              ← SOUL.md (domyślny + per-user overrides)
│   ├── pipelines/         ← Lobster YAML (feature-dev, hotfix, ...)
│   └── config/            ← agent-registry.yaml
│
└── docs/
    └── superpowers/
        └── specs/             ← ten dokument + ADR-y

12. Fazy implementacji

Pięć faz. Każda kończy się weryfikowalnym rezultatem — nie “może działa”, tylko działa i udowodniliśmy to.

Phase 1 · Foundation

Gateway + pierwszy agent

Cel: Jeden działający agent który czyta Google Calendar i odpowiada na Slack.

Co powstaje:

3 serwery Hetzner + private vSwitch
OpenClaw Gateway + LiteLLM + PostgreSQL na Gateway
Docker Remote API (TLS) między Gateway a Build Server
Jeden agent (rola: developer) z auth Google Calendar
Slack Bot działający

✅ Weryfikacja: DM do bota na Slacku → agent odpowiada, może odczytać kalendarz.

Phase 2 · Deploy Pipeline

Build & Deploy end-to-end

Cel: Agent napisze Hello World app, zbuilduje go, zdeployuje, dostanie działający URL.

Co powstaje:

Traefik na App Server + wildcard DNS *.nova.dev
Let’s Encrypt TLS
GitHub Actions self-hosted runner na Build Server
Pierwszy kompletny cykl: kod → build → staging URL → weryfikacja

✅ Weryfikacja: https://main.hello-world.nova.dev → 200 OK, TLS, automatyczne routing.

Phase 3 · Multi-Agent

Pipelines + RBAC

Cel: Pełny pipeline feature-development działa end-to-end.

Co powstaje:

Wszystkie szablony ról (developer, tester, devops, PO, CTO, marketing, sales, legal)
Lobster pipelines: feature-development, hotfix, contract-review
RBAC egzekwowany per agent
Wspólne agenty specjalistyczne (tester, devops, po, cto)

✅ Weryfikacja: Dev pisze kod → tester testuje → PO zatwierdza → DevOps deployuje na prod. Zero ręcznej interwencji poza human approval gate.

Phase 4 · Scale + Audit

50 użytkowników, pełna observability

Cel: Onboarding 50 użytkowników + monitoring + alerty.

Co powstaje:

Prometheus + Grafana + Alertmanager na App Server
Audit trail schema + dashboard w Grafana
Onboarding skrypt (jeden user = jedna komenda)
Alerty: serwer down, budget > 80%, pipeline failure

✅ Weryfikacja: Onboarding 5 testowych użytkowników. Wszystkie akcje widoczne w Grafana. Alert na Slacku po przekroczeniu limitu API.

Phase 5 · iOS + Business

Pełna platforma dla wszystkich ról

Cel: iOS builds + email + CRM + task management.

Co powstaje:

MacStadium M2 Mac Mini (Xcode, Fastlane, SSH)
iOS developer agent (rola: ios-developer)
Email integracja (Gmail + Outlook per user)
CRM integracja (HubSpot)
Jira / Notion integracja

✅ Weryfikacja: iOS developer agent builduje aplikację i uploaduje do TestFlight. Sales agent loguje interakcję w HubSpot.