1. Přehled architektury

Synapse a OpenClaw si vyměňují zprávy přes dva HTTP round-tripy. Ven Synapse POSTuje každou zprávu uživatele na plugin route /webhook/synapse. Zpátky plugin POSTuje odpověď agenta na /api/ai/inbound v Synapse, která ji přes SignalR (AiReply event) doručí konkrétnímu uživateli.

iOS aplikace
   │
   ▼  POST /api/ai/message   { "message": "…" }           (Bearer JWT)
Synapse backend
   │
   ▼  POST {gateway}/webhook/synapse  { text, user_id, token }
OpenClaw gateway (plugin route)
   │
   ▼  agent.run(text) → odpověď
OpenClaw plugin outbound handler
   │
   ▼  POST {synapse}/api/ai/inbound   { user_id, text, token }   (inboundToken)
Synapse backend
   │
   ▼  SignalR AiReply → user:{userId} skupina
iOS zobrazí odpověď
            

• Dva tokeny, dva směry. Gateway Token autorizuje Synapse → OpenClaw. Inbound Token autorizuje OpenClaw → Synapse.
• Per-user allowlist. Admin musí explicitně povolit každého uživatele. Nepovolený uživatel dostane 403 a v iOS ani neuvidí dlaždici chatu.
• Není E2E šifrované. Na rozdíl od běžných Synapse chatů proudí zprávy agentovi jako čistý text přes váš backend do vaší OpenClaw instance. Zacházejte s tím jako s jakoukoliv jinou integrací, která vidí obsah zpráv.

2. Co je potřeba předem

• • Nasazený Synapse backend s admin přístupem (vaše instance synapse-communicator).
• • Běžící OpenClaw gateway dostupná přes HTTPS s platným Gateway Tokenem (OPENCLAW_GATEWAY_TOKEN).
• • SSH (nebo ekvivalent) přístup na OpenClaw server, nebo možnost instalovat pluginy přes váš OpenClaw control plane.
• • Zdrojový kód pluginu @synapse/openclaw-synapse-channel (v repu Synapse ve složce openclaw-synapse-plugin/).

3. Krok 1 — Nastavení gateway v Synapse Admin

1. Přihlaste se do Synapse admin portálu a otevřete Integrations → OpenClaw.
2. Gateway URL — zadejte base URL vaší OpenClaw gateway (např. https://openclaw.example.com nebo http://openclaw:18789). Nepřidávejte koncovku /webhook/synapse — Synapse si ji připojí sama.
3. Gateway Token — vložte token, který odpovídá hodnotě channels.synapse.token v configu pluginu. Pokud plugin ještě nemáte nainstalovaný, token si zapište — stejnou hodnotu pak použijete v kroku 2.
4. Klikněte Test connection. Má vrátit „Connected successfully" s latencí.
5. Klikněte Save.
6. Ve zobrazené sekci Plugin setup klikněte Generate u Inbound Token. Token okamžitě zkopírujte — zobrazí se pouze jednou.
7. Zkopírujte Synapse Inbound Webhook URL zobrazenou nad tokenem. Oba tyto údaje vložíte do configu pluginu.

4. Krok 2 — Instalace Synapse channel pluginu na OpenClaw

Plugin registruje route POST /webhook/synapse na gateway a propojí outbound odpověď agenta s inbound endpointem Synapse.

2.1 — Přenos pluginu na OpenClaw host

Z vaší pracovní stanice:

cd <váš-synapse-checkout>/openclaw-synapse-plugin
tar czf openclaw-synapse-plugin.tgz --exclude=node_modules --exclude=.git .
scp openclaw-synapse-plugin.tgz <user>@<openclaw-host>:/tmp/

2.2 — Rozbalení a instalace závislostí

Na OpenClaw hostu:

ssh <user>@<openclaw-host>
sudo mkdir -p /opt/openclaw/plugins/synapse
sudo tar xzf /tmp/openclaw-synapse-plugin.tgz -C /opt/openclaw/plugins/synapse
cd /opt/openclaw/plugins/synapse
sudo npm install --omit=dev

Pokud vaše OpenClaw distribuce má vlastní plugin installer, raději ho použijte:

openclaw plugins install /opt/openclaw/plugins/synapse

2.3 — Konfigurace kanálu

Upravte openclaw.config.yaml na gateway serveru a pod channels: přidejte blok synapse. Použijte přesné hodnoty z Synapse Admin → Integrations.

channels:
  synapse:
    # Stejná hodnota, kterou jste uložili jako Gateway Token v Synapse Admin.
    token: "<OPENCLAW_GATEWAY_TOKEN>"

    # Vložte "Synapse Inbound Webhook URL" z panelu Plugin setup.
    incomingUrl: "https://<vaše-synapse>/api/ai/inbound"

    # Vložte Inbound Token, který jste vygenerovali (zobrazený jen jednou).
    inboundToken: "<INBOUND_TOKEN>"

    # "open" = kdokoli povolený v Synapse může psát agentovi.
    # "allowlist" = navíc požadovat composite ID v allowedUserIds.
    dmPolicy: open
    # allowedUserIds:
    #   - "<companyId>:<userId>"

2.4 — Restart gateway

Webhook route se registruje při startu, takže restart je nutný.

# Vyberte podle vašeho deploymentu:
sudo systemctl restart openclaw
# nebo
docker restart openclaw
# nebo
pm2 restart openclaw

2.5 — Ověření ze serveru

curl -i -X POST http://localhost:18789/webhook/synapse \
     -H 'Content-Type: application/json' \
     -d '{"text":"ping","user_id":"00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000","token":"<OPENCLAW_GATEWAY_TOKEN>"}'

Očekávané: HTTP 200 nebo 202. Pokud dostanete 404, plugin se nenačetl — ověřte cestu a logy serveru. Pokud 401, token nesedí.

5. Krok 3 — Povolení uživatelů

Přístup k OpenClaw je per-user. Uživatel, který není v allowlistu, nemůže posílat zprávy a ani neuvidí dlaždici „OpenClaw Agent" v iOS seznamu konverzací.

1. V Synapse Admin otevřete Users.
2. Najděte sloupec OpenClaw. Každý řádek má přepínač.
3. Přepněte ON u každého člena, který má mít přístup k agentovi. Změna je aplikovaná okamžitě.

Allowlist je uložený v CompanySettings.OpenClawAllowedUserIds. Je to standardní součást per-company settings JSON a zálohuje se společně s databází.

6. Krok 4 — Ověření end-to-end

6.1 — Z Synapse Admin

V Integrations → OpenClaw klikněte Send test message. Dostanete raw status code, response body a interpretační hint.

• HTTP 200/202 — plugin přijal testovací payload. Pokračujte na iOS.
• HTTP 404 — plugin není načtený. Zkontrolujte krok 2.3 a restart.
• HTTP 401 / 403 — Gateway Token nesedí mezi Adminem a channels.synapse.token.
• HTTP 400 — neshoda schématu payloadu. Aktualizujte plugin na verzi dodanou s vaším Synapse release.

6.2 — Z iOS

1. Přihlaste se jako povolený uživatel. Nahoře v seznamu konverzací se objeví dlaždice OpenClaw Agent.
2. Klikněte na ni, napište zprávu, odešlete.
3. Odpověď dorazí asynchronně přes SignalR — typicky v rámci běžné latence agenta.

7. Prompty pro agenta — automatizace z OpenClaw

Pokud vaše OpenClaw instance obsahuje agenta s shell/filesystem nástroji, může si kroky 2.1 – 2.5 provést sám. Vložte následující prompty přímo agentovi a placeholders v lomených závorkách nahraďte konkrétními hodnotami.

Prompt A — Instaluj Synapse channel plugin

Běžíš na OpenClaw hostu a máš shell přístup.
Nainstaluj Synapse channel plugin, aby tato gateway uměla přijímat a odesílat zprávy přes Synapse.

Inputy:
  SYNAPSE_GATEWAY_TOKEN   = <vlož z Synapse Admin → Integrations → Gateway Token>
  SYNAPSE_INBOUND_URL     = <vlož z Integrations → Plugin setup → Synapse Inbound Webhook URL>
  SYNAPSE_INBOUND_TOKEN   = <vlož z Integrations → Plugin setup → Inbound Token (jen jednou)>
  PLUGIN_TARBALL_URL      = <URL k openclaw-synapse-plugin.tgz, nebo /tmp cesta pokud už je nahrán>
  OPENCLAW_CONFIG_PATH    = <absolutní cesta k openclaw.config.yaml na tomto hostu>

Udělej toto v tomto pořadí:
  1. Vytvoř /opt/openclaw/plugins/synapse, pokud neexistuje.
  2. Stáhni nebo zkopíruj plugin tarball do té složky a rozbal ho.
  3. V adresáři pluginu spusť `npm install --omit=dev`.
  4. Edituj OPENCLAW_CONFIG_PATH a pod `channels:` vlož (nebo uprav):
       synapse:
         token: "${SYNAPSE_GATEWAY_TOKEN}"
         incomingUrl: "${SYNAPSE_INBOUND_URL}"
         inboundToken: "${SYNAPSE_INBOUND_TOKEN}"
         dmPolicy: open
     Zachovej ostatní existující kanály. Nikdy nepřepisuj nesouvisející klíče.
  5. Před uložením zvaliduj YAML. Pokud je soubor rozbitý, abortuj a nahlas chybu.
  6. Restartuj službu OpenClaw (nejprve zkus `systemctl restart openclaw`; pokud selže,
     zkus `docker restart openclaw`; pokud ani jedno neexistuje, nahlas, jak služba běží).
  7. Počkej 5 sekund a zavolej curl `http://localhost:18789/webhook/synapse` s ping body:
       {"text":"ping","user_id":"00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000","token":"${SYNAPSE_GATEWAY_TOKEN}"}
  8. Nahlas HTTP status + body. Jakékoli non-2xx je instalační chyba — vysvětli pravděpodobnou příčinu.

Nikdy nevypisuj hodnoty tokenů v plaintextu na stdout nebo do jiného souboru než samotného configu.

Prompt B — Bezpečně rotuj Inbound Token

Jsi na OpenClaw hostu. Rotuj inboundToken používaný Synapse channel.

Předpoklady: admin klikl „Regenerate" v Synapse Admin → Integrations a předal ti:
  NEW_INBOUND_TOKEN = <nově vygenerovaný token, zobrazený jen jednou>

Kroky:
  1. Přečti OPENCLAW_CONFIG_PATH a najdi channels.synapse.inboundToken.
  2. Nahraď hodnotu NEW_INBOUND_TOKEN. Ostatní klíče nech beze změny.
  3. Ulož a reloadni OpenClaw (`systemctl reload openclaw` pokud je podporovaný, jinak restart).
  4. Požádej admina, aby poslal testovací zprávu ze Synapse Admin → „Send test message".
     Očekávej HTTP 200/202. Pokud 401/403, vrať původní hodnotu a nahlas.

Nikdy nelogguj NEW_INBOUND_TOKEN.

Prompt C — Ověř inbound dostupnost z OpenClaw → Synapse

Jsi na OpenClaw hostu. Ověř, že tento host dosáhne na Synapse pro odpovědi.

Inputy:
  SYNAPSE_INBOUND_URL   = <https://<vaše-synapse>/api/ai/inbound>
  SYNAPSE_INBOUND_TOKEN = <stejné jako v channels.synapse.inboundToken>

Spusť:
  curl -sS -o /tmp/out -w '%{http_code}\n' -X POST "$SYNAPSE_INBOUND_URL" \
       -H 'Content-Type: application/json' \
       --data '{
         "user_id": "00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000",
         "text":    "[inbound-probe]",
         "token":   "'"$SYNAPSE_INBOUND_TOKEN"'"
       }'

Interpretace:
  401 = inbound token je špatný — oprav channels.synapse.inboundToken.
  404 = Synapse URL je špatná nebo backend neexponuje /api/ai/inbound.
  Jakékoli 5xx = chyba Synapse backendu — sdílej body z /tmp/out.
  200  = Synapse přijal probe. Cesta plugin → Synapse je funkční.

Nahlas status code a jednořádkovou diagnózu.

8. Skripty

8.1 — Jednorázový plugin installer

Uložte jako install-synapse-plugin.sh na OpenClaw hostu, doplňte tři proměnné nahoře a spusťte.

#!/usr/bin/env bash
set -euo pipefail

# ─── doplňte ───────────────────────────────────────────────────
SYNAPSE_GATEWAY_TOKEN="${SYNAPSE_GATEWAY_TOKEN:?set me}"
SYNAPSE_INBOUND_URL="${SYNAPSE_INBOUND_URL:?set me}"
SYNAPSE_INBOUND_TOKEN="${SYNAPSE_INBOUND_TOKEN:?set me}"
PLUGIN_TARBALL="${PLUGIN_TARBALL:-/tmp/openclaw-synapse-plugin.tgz}"
OPENCLAW_CONFIG="${OPENCLAW_CONFIG:-/etc/openclaw/openclaw.config.yaml}"
PLUGIN_DIR="${PLUGIN_DIR:-/opt/openclaw/plugins/synapse}"
# ───────────────────────────────────────────────────────────────

echo "→ instalace pluginu do $PLUGIN_DIR"
sudo mkdir -p "$PLUGIN_DIR"
sudo tar xzf "$PLUGIN_TARBALL" -C "$PLUGIN_DIR"
(cd "$PLUGIN_DIR" && sudo npm install --omit=dev)

echo "→ úprava $OPENCLAW_CONFIG"
if ! command -v yq >/dev/null; then
  echo "yq je vyžadovaný (https://github.com/mikefarah/yq). Konec." >&2
  exit 1
fi
sudo cp "$OPENCLAW_CONFIG" "$OPENCLAW_CONFIG.bak.$(date +%s)"
sudo yq -i "
  .channels.synapse.token        = strenv(SYNAPSE_GATEWAY_TOKEN) |
  .channels.synapse.incomingUrl  = strenv(SYNAPSE_INBOUND_URL)   |
  .channels.synapse.inboundToken = strenv(SYNAPSE_INBOUND_TOKEN) |
  .channels.synapse.dmPolicy     = \"open\"
" "$OPENCLAW_CONFIG"

echo "→ restart OpenClaw"
if systemctl list-units --type=service | grep -q '^openclaw'; then
  sudo systemctl restart openclaw
elif docker ps --format '{{.Names}}' | grep -q '^openclaw$'; then
  docker restart openclaw
else
  echo "Neznámý service manager — restartujte OpenClaw ručně." >&2
  exit 1
fi

echo "→ smoke test"
sleep 5
curl -sS -o /tmp/synapse-plugin-probe -w 'HTTP %{http_code}\n' -X POST \
  http://localhost:18789/webhook/synapse \
  -H 'Content-Type: application/json' \
  --data "{\"text\":\"[probe]\",\"user_id\":\"00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000\",\"token\":\"$SYNAPSE_GATEWAY_TOKEN\"}"
echo "Response body:"
cat /tmp/synapse-plugin-probe
echo

8.2 — Healthcheck pluginu

#!/usr/bin/env bash
set -euo pipefail

GATEWAY="${GATEWAY:-http://localhost:18789}"
TOKEN="${SYNAPSE_GATEWAY_TOKEN:?set me}"

status=$(curl -sS -o /tmp/out -w '%{http_code}' -X POST \
  "$GATEWAY/webhook/synapse" \
  -H 'Content-Type: application/json' \
  --data "{\"text\":\"[healthcheck]\",\"user_id\":\"00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000\",\"token\":\"$TOKEN\"}")

case "$status" in
  200|202) echo "OK — $status"; exit 0 ;;
  401|403) echo "AUTH FAIL — neshoda tokenu"; exit 2 ;;
  404)     echo "PLUGIN MISSING — route není registrovaná"; exit 3 ;;
  *)       echo "UNEXPECTED — HTTP $status"; cat /tmp/out; exit 4 ;;
esac

9. API reference

User endpointy (vyžadují JWT)

Admin endpointy (vyžadují CompanyAdmin policy)

OpenClaw → Synapse inbound webhook

10. Troubleshooting

11. Bezpečnostní poznámky

• •Není E2E šifrované. Zprávy k agentovi jsou plaintext na obou stranách — v Synapse backendu i v OpenClaw. Zacházejte s tím jako s jakoukoliv jinou integrací a uživatele o tom informujte.
• •Per-user allowlist je povinný. I po konfiguraci gateway nemůže žádný uživatel psát agentovi, dokud ho admin explicitně nepovolí. Tím se omezí riziko neúmyslné expozice dat.
• •Rotujte Inbound Token při vyřazení plugin deploymentu nebo při změně vlastníka sdíleného prostředí. Starý token je zneplatněn okamžitě po regeneraci.
• •Udržujte gateway trafic TLS-terminovaný end-to-end. I uvnitř VPC preferujte HTTPS mezi Synapse a gateway, aby tokeny nebyly viditelné v packet captures.