1. Scopo e confini

Il gateway è il processo di myclaw. Non una libreria, non un insieme di script: un singolo processo FastAPI che parte a boot (via systemd --user), ascolta su 127.0.0.1:42618, e resta vivo finché il PC è acceso. Tutto ciò che succede in myclaw passa da qui.

Cos'è

• Il processo che ascolta richieste da canali (CLI, Telegram, futuro).
• Il gestore delle sessioni conversazionali.
• Il routing hub per webhook in ingresso e callback per approvazioni.
• Lo scheduler dei cron job.
• Il punto di autenticazione per l'admin API e per i canali.
• L'orchestratore che, per ogni richiesta, istanzia AgentRuntime.handle() e cura il ciclo di vita della ExecutionTrace.

Cosa non è

• Non è il reasoning loop (→ agent_runtime).
• Non implementa i canali: li accoglie via adapter (→ channel.html).
• Non ha logica di Policy (→ policy.html).
• Non serve pagine web agli utenti finali (l'eventuale dashboard è un endpoint in più, ma la UI vera vive nei canali di messaging).

2. Topology: dove sta il gateway

3. Gli endpoint HTTP

Tutte le route sono su 127.0.0.1:42618. Nessuna è esposta su 0.0.0.0 di default. L'accesso da altro host della LAN (o remoto via tunnel) richiede reverse-proxy esplicito, fuori scope di questo doc.

Endpoint pubblici (per canali)

Endpoint approvazioni (usati dai canali per risolvere le ApprovalRequest)

Endpoint admin

Endpoint interni

4. Sessioni: ciclo di vita e persistenza

Una sessione è una conversazione logica con un sender su un canale. Ha uno stato (memoria di chat, autonomy corrente, batch attivi) e un ciclo di vita. Il gateway le gestisce in memoria con write-through su SQLite.

Identificazione

session_id := hash("{channel}:{sender_id}:{autonomy_level}")
# esempio: hash("telegram:@roberto:supervised") = "s_4a7b..."

La stessa persona su due canali = due sessioni distinte. Lo stesso sender che cambia autonomy = nuova sessione (la vecchia diventa archived). Questo mantiene chiaro il confine di autonomia.

Binding con la memoria

Per evitare confusione cross-doc, fissiamo qui la chiave di recupero usata da memory:

Il Gateway espone Session.sender come unica chiave che la Memory deve leggere; non espone session_id alla Memory (la session è un oggetto di conversazione, non di identità).

Stati

Persistenza

In memoria per il ciclo di vita, con write-through su SQLite per sopravvivere ai restart del gateway:

workspace/state/sessions.db          # SQLite
  └─ sessions(session_id, channel, sender, autonomy, created, last_activity, closed_at)
  └─ messages(session_id, step_idx, role, content, trace_id, timestamp)
  └─ batches(batch_id, session_id, effect_class, expires_at)

4.1 Flusso approvazione: chi costruisce ApprovalRequest

La revisione incrociata dei doc ha trovato un buco di responsabilità: la ApprovalRequest (approval_ux §9) è il dato chiave del flusso, ma né la Policy né il broker la costruiscono. È il Gateway, e qui è il motivo: solo il Gateway conosce insieme il session_id, il trace_id in costruzione, il canale e il sender attivo. La Policy non ha queste informazioni contestuali; il broker è un consumatore puro.

# Pseudocodice del Gateway (vive accanto a ingest()):
def _on_policy_approve_required(
    self,
    draft: ApprovalRequestDraft,      # da Policy
    trace_id: UUID,
    session: Session,
) -> ApprovalRequest:
    return ApprovalRequest(
        request_id=uuid4(),
        trace_id=trace_id,
        sender=session.sender,
        channel=session.channel,
        tool_name=draft.tool_name,
        args=draft.args_preview,              # redacted
        effect_class=draft.effect_class,
        summary=draft.summary,                # preferibilmente da tool.dry_run()
        reversibility=draft.reversibility,
        risk=draft.risk,
        requested_at=now_utc(),
        timeout_at=now_utc() + channel.default_approval_timeout(),
        # fonte: il Channel possiede il default per-canale (vedi approval_ux §8).
    )

async def _await_approval(self, req: ApprovalRequest) -> Approval:
    # Il broker si occupa di batching, tutor mode, pausa lettura, revoca:
    return await self.broker.request(req)

5. Canali in ingresso: webhook, polling, long-poll

Tre strategie, una per tipo di canale. Il gateway ne orchestra fino a N in parallelo, ciascuna in un task asyncio dedicato.

Come i canali parlano col gateway in risposta

Il gateway non mantiene una connessione bidirezionale coi canali esterni (Telegram, MQTT). Il canale ha un proprio task che, oltre a ricevere, sa anche rispondere via API sua (es. sendMessage di Telegram). Il runtime, a fine loop, passa il final_response al channel adapter via coda asyncio. Il channel adapter fa la chiamata outbound verso il mondo.

6. Cron e compiti ricorrenti

Il gateway ha uno scheduler interno basato su APScheduler (o equivalente asyncio-native). Gli utenti aggiungono job via comando (myclaw cron add "ogni sera 22:00" "riassumi log di oggi").

Semantica del cron myclaw

Un cron job non è un comando shell. È un'intenzione che, a tempo stabilito, viene iniettata come messaggio utente in una sessione dedicata:

CronJob(
  id="cj_daily_22",
  when="0 22 * * *",
  channel="telegram:@roberto",
  autonomy="supervised",          # stessa policy di un messaggio utente
  intent="riassumi gli errori in /var/log/syslog di oggi, se ce ne sono notificami"
)

Alle 22:00, il gateway crea una sessione cron-owned, inietta l'intent come messaggio utente, lascia che l'agent_runtime risponda. Se la risposta contiene "notifica", il canale dedicato la recapita. Se una tool-call richiede approvazione e Roberto dorme, la richiesta va in Pending con timeout di 2h.

Storage

workspace/state/cron.yaml          # file YAML editabile anche a mano
  jobs:
    - id: cj_daily_22
      when: "0 22 * * *"
      channel: "telegram:@roberto"
      intent: "..."
      created_at: "2026-04-21T18:00:00Z"
      last_run: "2026-04-20T22:00:00Z"
      last_outcome: "success"

7. Autenticazione: admin vs per-canale

Admin API

Un singolo bearer token in config/secrets.env:

MYCLAW_ADMIN_TOKEN=<32 random bytes in hex>

Richiesto in header Authorization: Bearer <token> su ogni path /admin/*. Il CLI lo legge dal file (chmod 600) alla partenza. Niente OAuth, JWT, o roba complessa: è un singolo token per un singolo amministratore (Roberto) su un singolo host. Semplicità batte sofisticazione.

Canali

8. Hardening systemd

Il gateway gira come systemd user service per roberto. L'unità è pesantemente indurita: myclaw deve fare cose potenti (vedi nota operativa di Roberto: "sandbox abbastanza potente da permettere azioni concrete"), ma il gateway stesso non deve avere più privilegi di quelli necessari ad ascoltare HTTP e invocare la sandbox.

# ~/.config/systemd/user/myclaw-gateway.service
[Unit]
Description=myclaw gateway
After=network.target

[Service]
Type=simple
ExecStart=/opt/myclaw/.venv/bin/python -m myclaw.gateway
Restart=on-failure
RestartSec=5s

# ---- Hardening ----
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/opt/myclaw/workspace /opt/myclaw/.runtime
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectControlGroups=yes
RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
RestrictNamespaces=yes
RestrictRealtime=yes
LockPersonality=yes
MemoryDenyWriteExecute=yes
SystemCallFilter=@system-service
SystemCallErrorNumber=EPERM

# ---- Limits ----
LimitNOFILE=4096
MemoryHigh=512M
MemoryMax=1G

# ---- Env ----
EnvironmentFile=/opt/myclaw/config/secrets.env

[Install]
WantedBy=default.target

Scelte giustificate

9. Contratto Python

from typing import Protocol
from fastapi import FastAPI
from dataclasses import dataclass
from datetime import datetime
from uuid import UUID

@dataclass
class Session:
    session_id: str
    channel: str
    sender: str
    autonomy: str                 # "readonly" | "supervised" | "full"
    created_at: datetime
    last_activity: datetime
    state: str                    # "new" | "active" | "idle" | "closed"
    pending_approvals: list[UUID]

class Gateway(Protocol):
    app: FastAPI
    runtime: AgentRuntime         # iniettato
    sessions: SessionStore
    broker: ApprovalBroker
    scheduler: CronScheduler

    async def start(self) -> None: ...
    async def shutdown(self) -> None: ...

    async def ingest(
        self,
        channel: str,
        sender: str,
        message: str,
    ) -> ExecutionTrace:
        """Punto d'ingresso unificato usato da tutti gli adapter canale."""
        ...

class SessionStore(Protocol):
    async def get_or_create(
        self, channel: str, sender: str, autonomy: str,
    ) -> Session: ...
    async def close(self, session_id: str) -> None: ...
    async def archive_on_autonomy_change(
        self, session_id: str, new_autonomy: str,
    ) -> Session: ...

class CronScheduler(Protocol):
    async def add(self, job: CronJob) -> str: ...    # ritorna job_id
    async def remove(self, job_id: str) -> None: ...
    async def list_jobs(self) -> list[CronJob]: ...
    async def run_now(self, job_id: str) -> ExecutionTrace: ...

10. Alternative considerate

11. Test di conformità

12. Riferimenti

Continua a leggere

myclaw — gateway microprogettazione v1.0 — 2026-04-21
Primo dei 4 classici. Prossimo: channel.html.