Openclaw Relay

Defaults

The script avoids baked-in personal paths. Override with env or flags when needed.

• transport: local
• local repo cwd: current working directory
• local acpx repo: <cwd>/extensions/acpx
• ssh host: mac-studio
• remote repo cwd: <remote-home>/clawdbot
• remote acpx repo: <remote-home>/Projects/oss/acpx
• gateway token file: <home>/.openclaw/gateway.token
• control session name: codex-bridge
• target aliases file: config/session_aliases.json

Useful env vars:

• OPENCLAW_RELAY_TRANSPORT
• OPENCLAW_RELAY_HOST
• OPENCLAW_RELAY_CWD
• OPENCLAW_RELAY_ACPX_REPO
• OPENCLAW_RELAY_GATEWAY_URL
• OPENCLAW_RELAY_GATEWAY_TOKEN_FILE
• OPENCLAW_RELAY_SESSION
• OPENCLAW_RELAY_TARGETS_FILE

Quick Start

Health check:

python3 scripts/openclaw_relay.py doctor

List known target aliases:

python3 scripts/openclaw_relay.py targets

Resolve a target alias:

python3 scripts/openclaw_relay.py resolve --target maintainers

Ask a target session a question privately:

python3 scripts/openclaw_relay.py ask \
  --target maintainers \
  --message "Summarize the current vibe in this channel."

Force-send text to the resolved target:

python3 scripts/openclaw_relay.py force-send \
  --target maintainers \
  --text "Deploy is done."

Use the persistent control session:

python3 scripts/openclaw_relay.py ensure
python3 scripts/openclaw_relay.py send --message "Reply with exactly OK."
python3 scripts/openclaw_relay.py show

Remote host example:

python3 scripts/openclaw_relay.py doctor --transport ssh --host mac-studio
python3 scripts/openclaw_relay.py send \
  --transport ssh \
  --host mac-studio \
  --message "Reply with exactly OK."

Async Workflow

Queue work and poll the same control session:

python3 scripts/openclaw_relay.py start --message "Work on X and reply when done."
python3 scripts/openclaw_relay.py wait --after-seq <last-seq>
python3 scripts/openclaw_relay.py show

Target Aliases

config/session_aliases.json ships with placeholders. Replace them with real values for your setup.

Example shape:

{
  "main": "agent:<agentId>:main",
  "maintainers": "agent:<agentId>:discord:channel:<channelId>"
}

Session Rules

Use these rules when choosing a command:

• Want a private reply from a specific session: ask
• Want the target session to decide whether to post: publish
• Want a guaranteed direct post: force-send
• Want blocking continuity with the control brain: send
• Want fire-and-forget async: start, then wait and show
• Want to stop queued work: cancel

Failure Handling

If relay work fails:

1. Run doctor.
2. Run status.
3. Run show.
4. If the control session is wedged, run cancel, then ensure, then retry.

If route discovery is uncertain:

1. Resolve the target first.
2. Prefer alias or exact session key.
3. Use a tiny probe ask before sending the real payload.

Output Relay

Return the actual assistant text or delivery result, not shell noise.

For relay tasks, report:

• transport used
• target session key
• whether the route probe/resolve succeeded
• final posted or returned result