Handoff-Agents Setup für VPS

🇬🇧 English | 🇩🇪 Deutsch

🇬🇧 English

Handoff-Agents Setup for VPS (localhost-only)

This guide is for one VPS only.

WordPress and OpenClaw run on the same VPS.
WordPress talks to OpenClaw via localhost.
OpenClaw is not exposed to the internet.

This is a setup guide, not a story. Every value below is mapped to the exact place where it must be configured.

What you will build

OpenClaw Gateway (localhost-only)
a frontdoor agent (secretary) for the WordPress chat
a specialist agent (support) that gets tasks via handoff
optional extra specialists (sales, operations)
DigitalCompass-AgentHub (WordPress plugin) configured to call the frontdoor agent

What “handoff” means in OpenClaw

The WordPress plugin always calls one model (example: openclaw/secretary).
The frontdoor agent decides whether to answer itself or to delegate.
Delegation is done by calling the OpenClaw tool sessions_spawn.
OpenClaw then runs the specialist as a sub-agent in a separate session.

Important:

OpenClaw does not “handoff automatically” by configuration alone.
The frontdoor agent delegates because of the rules you wrote in its AGENTS.md.

Example roles (examples only)

These names are examples.

secretary = first contact, decides when to delegate
support = technical help
sales = offers and pre-sales
operations = internal work and admin

1. Prerequisites

You need:

a VPS
WordPress installed on the VPS
DigitalCompass-AgentHub installed in WordPress
OpenClaw installed on the VPS

2. Install OpenClaw

Run on the VPS:

npm install -g openclaw
openclaw --version

3. OpenClaw config file location

OpenClaw is configured here:

~/.openclaw/openclaw.json

4. Configure OpenClaw Gateway (localhost-only)

Minimal gateway settings (must be in ~/.openclaw/openclaw.json):

{
  gateway: {
    auth: {
      mode: "token",
      token: "YOUR_STRONG_TOKEN_HERE"
    },
    http: {
      endpoints: {
        chatCompletions: { enabled: true }
      }
    },
    mode: "local",
    port: 18789,
    bind: "loopback"
  }
}

Restart after changes:

openclaw gateway restart

Verify it listens on localhost only:

ss -tlnp | grep 18789

Expected: 127.0.0.1:18789 (not 0.0.0.0:18789).

5. Create agent workspaces (folders)

Create one workspace folder per agent:

~/.openclaw/workspace/
├── secretary/
│   └── AGENTS.md
├── support/
│   └── AGENTS.md
├── sales/
│   └── AGENTS.md
└── operations/
    └── AGENTS.md

Where OpenClaw stores per-agent state and sessions:

~/.openclaw/agents/<agentId>/agent/
~/.openclaw/agents/<agentId>/sessions/

Note: you normally do not create these ~/.openclaw/agents/... folders by hand. OpenClaw creates them when the agent runs.

6. Write the `AGENTS.md` files (handoff rules)

You do not “talk to” the agent. You define the rules in text files.

6.1 Frontdoor agent rules (secretary)

File:

~/.openclaw/workspace/secretary/AGENTS.md

Your secretary must contain:

what it answers directly
when it delegates
which specialist it should delegate to
what the delegation summary must contain

Example rule set (simple):

answer simple questions directly
if the message is a technical issue → delegate to support
if the message asks for pricing/offer → delegate to sales
if the message is internal/admin work → delegate to operations
when delegating: send a short summary + a clear task

6.2 Specialist rules (support)

File:

~/.openclaw/workspace/support/AGENTS.md

Example rules:

only handle technical support tasks
answer short and direct
if it is not a technical issue, say so

7. Configure multiple agents in OpenClaw

Add the agent configuration into the same file ~/.openclaw/openclaw.json. Example (gateway + agents in one file):

{
  gateway: {
    auth: { mode: "token", token: "YOUR_STRONG_TOKEN_HERE" },
    http: { endpoints: { chatCompletions: { enabled: true } } },
    mode: "local",
    port: 18789,
    bind: "loopback"
  },

  agents: {
    list: [
      {
        id: "secretary",
        default: true,
        workspace: "~/.openclaw/workspace/secretary"
      },
      {
        id: "support",
        workspace: "~/.openclaw/workspace/support"
      },
      {
        id: "sales",
        workspace: "~/.openclaw/workspace/sales"
      },
      {
        id: "operations",
        workspace: "~/.openclaw/workspace/operations"
      }
    ]
  }
}

Restart OpenClaw:

openclaw gateway restart

8. How the handoff is triggered (automatic vs keyword)

Automatic (recommended)

Handoff is “automatic” because the frontdoor agent rules decide it.

The user writes in the WordPress chat.
WordPress sends the message to openclaw/secretary.
The secretary reads the message and decides.
If needed, the secretary calls sessions_spawn(agentId: "support", task: "...").

Keyword-based

Keyword-based handoff is not a separate OpenClaw feature. It is just another rule you can write in secretary/AGENTS.md.

9. What `sessions_spawn` does (technical)

sessions_spawn performs a full session transfer to a specialist agent.

How it works

Secretary receives the question
Secretary calls sessions_spawn with target agent and task
Session is transferred completely to the specialist
Secretary’s session ends
Specialist takes over the conversation with the visitor
Chat continues with specialist only
Secretary is no longer part of this conversation

Important

The session transfer is permanent – not a sub-agent call that returns
Secretary does not receive the result back
Specialist has no access to secretary’s conversation history
Specialist owns the session until it ends naturally

Example spawn parameters

{
  task: "Customer has a technical problem with their account.",
  taskName: "support_session",
  agentId: "support",
  context: "isolated",
  runTimeoutSeconds: 900
}

Session key structure

Before spawn:  agent:secretary:main
After spawn:   agent:support:new-session-<uuid>
               ↑ Secretary session ends, new session starts with support

10. WordPress (DigitalCompass-AgentHub) configuration

WordPress Admin → Settings → AgentHub Setup

Use these values (Single VPS / localhost):

Field	Value
OpenClaw Endpoint	`http://127.0.0.1:18789/v1/chat/completions`
Gateway Token	token from `~/.openclaw/openclaw.json`
Model	`openclaw/secretary`
SSL Verification	✅ Enabled

Note: The endpoint uses http:// (localhost). SSL is for your WordPress site to visitors, not for the internal localhost hop.

11. Why there is no `channel` / `accountId` here

channel and accountId belong to OpenClaw channel adapters (Telegram, WhatsApp, Discord, Slack, …). They are used for inbound routing via bindings.

This WordPress setup does not use an OpenClaw channel adapter. It calls the HTTP API endpoint directly.

So in this guide:

no bindings
no channel
no accountId

12. Test the setup

12.1 Test OpenClaw directly (curl)

On the VPS:

curl -X POST http://127.0.0.1:18789/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_STRONG_TOKEN_HERE" \
  -d '{"model":"openclaw/secretary","messages":[{"role":"user","content":"Hello"}]}'

12.2 Test through WordPress

Open your WordPress site, open the chat, send a message.

13. Troubleshooting (minimum)

OpenClaw not reachable: ss -tlnp | grep 18789
Token error: WordPress token must match openclaw.json
Wrong agent: WordPress Model must be openclaw/secretary

🇩🇪 Deutsch

Handoff-Agenten Setup für VPS (nur localhost)

Diese Anleitung ist für einen einzelnen VPS gedacht.

WordPress und OpenClaw laufen auf demselben VPS.
WordPress kommuniziert über localhost mit OpenClaw.
OpenClaw ist nicht öffentlich aus dem Internet erreichbar.

Dies ist eine Einrichtungsanleitung, keine Beschreibung eines Szenarios. Jeder Wert ist der genauen Stelle zugeordnet, an der er konfiguriert werden muss.

Was aufgebaut wird

OpenClaw Gateway (nur localhost)
ein Frontdoor-Agent (secretary) für den WordPress-Chat
ein Spezialisten-Agent (support), der Aufgaben per Handoff übernimmt
optionale weitere Spezialisten (sales, operations)
DigitalCompass-AgentHub (WordPress-Plugin), das den Frontdoor-Agenten aufruft

Was „Handoff“ in OpenClaw bedeutet

Das WordPress-Plugin spricht immer genau ein Modell an (z. B. openclaw/secretary).
Der Frontdoor-Agent entscheidet selbst, ob er antwortet oder delegiert.
Delegiert wird über das OpenClaw-Tool sessions_spawn.
OpenClaw startet den Spezialisten anschließend in einer separaten Sitzung.

Wichtig:

OpenClaw führt kein automatisches Handoff allein durch Konfiguration aus.
Der Frontdoor-Agent delegiert aufgrund der Regeln in seiner AGENTS.md.

Beispielrollen

secretary = erster Ansprechpartner, entscheidet über Delegationen
support = technischer Support
sales = Vertrieb und Angebote
operations = interne Aufgaben und Administration

1. Voraussetzungen

Benötigt werden:

ein VPS
WordPress auf dem VPS
DigitalCompass-AgentHub in WordPress
OpenClaw auf dem VPS

2. OpenClaw installieren

npm install -g openclaw
openclaw --version

3. Speicherort der OpenClaw-Konfiguration

~/.openclaw/openclaw.json

4. OpenClaw Gateway konfigurieren (nur localhost)

Verwende die Konfiguration aus dem englischen Abschnitt unverändert.

Nach Änderungen:

openclaw gateway restart

Prüfen:

ss -tlnp | grep 18789

Erwartet wird 127.0.0.1:18789 und nicht 0.0.0.0:18789.

5. Agenten-Workspaces anlegen

Für jeden Agenten wird ein eigener Workspace angelegt:

~/.openclaw/workspace/
├── secretary/
│   └── AGENTS.md
├── support/
│   └── AGENTS.md
├── sales/
│   └── AGENTS.md
└── operations/
    └── AGENTS.md

6. AGENTS.md-Dateien erstellen

Hier werden die Regeln der Agenten definiert.

Frontdoor-Agent (`secretary`)

Definiert:

welche Anfragen direkt beantwortet werden
wann delegiert wird
an welchen Spezialisten delegiert wird
welche Informationen bei der Übergabe mitgegeben werden

Spezialist (`support`)

Beispiel:

bearbeitet ausschließlich technische Anfragen
antwortet kurz und präzise
weist auf falsche Zuordnungen hin

7. Mehrere Agenten konfigurieren

Die Agentenkonfiguration wird gemeinsam mit dem Gateway in der Datei ~/.openclaw/openclaw.json eingetragen.

Danach:

openclaw gateway restart

8. Wie ein Handoff ausgelöst wird

Automatisch (empfohlen)

Benutzer schreibt im WordPress-Chat.
WordPress sendet an openclaw/secretary.
Der Secretary analysiert die Anfrage.
Falls notwendig, ruft er sessions_spawn() auf.

Schlüsselwortbasiert

Dies ist keine separate OpenClaw-Funktion, sondern lediglich eine zusätzliche Regel in der AGENTS.md.

9. Was `sessions_spawn` technisch macht

sessions_spawn führt eine vollständige Sitzungsübergabe an einen anderen Agenten durch.

Ablauf:

Secretary erhält die Anfrage.
Secretary startet sessions_spawn.
Die Sitzung wird an den Zielagenten übertragen.
Die ursprüngliche Secretary-Sitzung endet.
Der Spezialist übernimmt die Unterhaltung.
Die Kommunikation läuft nur noch über den Spezialisten.

10. WordPress-Konfiguration

WordPress → Einstellungen → AgentHub Setup

Feld	Wert
OpenClaw Endpoint	`http://127.0.0.1:18789/v1/chat/completions`
Gateway Token	Token aus `openclaw.json`
Model	`openclaw/secretary`
SSL Verification	Aktiviert

11. Warum es hier kein `channel` oder `accountId` gibt

Diese Werte werden nur bei OpenClaw-Channel-Adaptern wie Telegram, Discord oder WhatsApp benötigt.

Das WordPress-Plugin kommuniziert direkt über die HTTP-API.

12. Setup testen

Direkt mit curl

curl -X POST http://127.0.0.1:18789/v1/chat/completions

Über WordPress

Website öffnen
Chat öffnen
Testnachricht senden

13. Fehlerbehebung

OpenClaw nicht erreichbar: ss -tlnp | grep 18789
Tokenfehler: Token in WordPress und openclaw.json vergleichen
Falscher Agent: Modell muss openclaw/secretary sein