openclaw-relay — Claude Code skill: what it does, how to install
openclaw-relay is a Claude Code skill that routes prompts and messages to OpenClaw sessions via local acpx or SSH, resolving targets from named aliases in config/session_aliases.json.
MIT 120 installs ★ 7,554 updated 2026-10-20
npx skills add steipete/agent-scripts --skill openclaw-relay -a claude-codeWhat openclaw-relay does
The skill wraps scripts/openclaw_relay.py, a Python script with two transports: local for direct relay from the current OpenClaw checkout, and ssh for reaching an agent session on another host. The transport is chosen with --transport or the OPENCLAW_RELAY_TRANSPORT env var.
Each command maps to a specific intent: ask gets a private reply from a session, force-send posts directly to a channel (and accepts --media for file attachments), send keeps a persistent control session open, and start / wait / show handle async queue workflows. For multiline content, --text-file <path> or --text-file - avoids shell-quoting issues.
The local transport defaults to looking for acpx at <cwd>/extensions/acpx; the SSH transport defaults to [email protected]. Both are overridable via env vars or flags. The gateway token is read from ~/.openclaw/gateway.token — without it, gateway-authenticated routes will fail.
What it helps with
- Relay a prompt to an OpenClaw session running on a remote machine over SSH
- Post a message with a media attachment to a Discord channel via
force-send - Queue async work and poll for the agent's reply using
start,wait, andshow - Resolve a session alias before sending a real payload to verify the route
- Run a transport health check with
doctorbefore a relay job
Example prompts for the agent
- Relay this message to the
maintainerssession using openclaw-relay - Run
openclaw_relay.py doctorwith ssh transport and report the result - Send the contents of
report.txtto themainsession over SSH
How to install openclaw-relay
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill openclaw-relay -a claude-code2Manually: put the files in place
~/.claude/skills/openclaw-relay/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/openclaw-relay/
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill openclaw-relay -a codex2Manually: put the files in place
.agents/skills/openclaw-relay/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill openclaw-relay -a cursor2Manually: put the files in place
.cursor/skills/openclaw-relay/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install steipete/agent-scripts skills/openclaw-relay2Manually: put the files in place
.github/skills/openclaw-relay/SKILL.md1Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill openclaw-relay -a gemini-cli2Platform CLI
gemini skills install https://github.com/steipete/agent-scripts --path skills/openclaw-relayManually: put the files in place
.devin/skills/openclaw-relay/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add steipete/agent-scripts --skill openclaw-relay -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about openclaw-relay
How do I install openclaw-relay in Claude Code?
Run npx skills add steipete/agent-scripts --skill openclaw-relay -a claude-code. The skill is then available at ~/.claude/skills/openclaw-relay/SKILL.md.
What does openclaw-relay do?
It routes prompts and messages into named OpenClaw sessions — either locally via acpx or over SSH to another machine. The skill resolves the target alias, picks the right transport, and returns the actual agent response rather than shell output.
What needs to be in place before the first run?
config/session_aliases.json ships with placeholders that must be replaced with real session identifiers. For SSH transport, the target host must be reachable, and the gateway token must exist at ~/.openclaw/gateway.token.
Source text
SKILL.md · MIT
--- name: openclaw-relay description: "OpenClaw session relay: prompts/posts via local/remote acpx over SSH." --- # OpenClaw Relay Use this when the job is: - "talk to Molty" - "relay this into an OpenClaw channel session" - "use acpx" - "send this through the gateway via acp" - "work through a remote OpenClaw bridge over SSH" Not for team.openclaw.ai: starting or inspecting Roboclaw sessions on the Team server is `$team-handoff` from openclaw/agent-skills (one Gateway request as Peter through Cloudflare Access; operator values live in `~/.config/openclaw/team-handoff.env`). One skill. Two transports: 1. `local` 2. `ssh` Default to `local` for direct telephone-game work from the current OpenClaw checkout. Use `ssh` when the target agent/session lives on another machine. For Peter's setup, Molty normally lives on the Mac Studio gateway, reached as `[email protected]`; avoid the `mac-studio` SSH alias for one-shot relay work because that alias auto-attaches tmux. Script path: `scripts/openclaw_relay.py` Target aliases file: `config/session_aliases.json` ## Mode Selection Choose `local` when: - the user explicitly says `acpx` - the target session is on the current machine - the goal is quick relay or private ask Choose `ssh` when: - the target agent/session lives on another host - you want a persistent bridge session - you need async queue/wait/show flows on a remote machine ## 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: `[email protected]` - 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: ```bash python3 scripts/openclaw_relay.py doctor ``` List known target aliases: ```bash python3 scripts/openclaw_relay.py targets ``` Resolve a target alias: ```bash python3 scripts/openclaw_relay.py resolve --target maintainers ``` Ask a target session a question privately: ```bash python3 scripts/openclaw_relay.py ask \ --target maintainers \ --message "Summarize the current vibe in this channel." ``` Force-send text to the resolved target: ```bash python3 scripts/openclaw_relay.py force-send \ --target maintainers \ --text "Deploy is done." ``` For multiline posts, use `--text-file <path>` or `--text-file -` instead of shell-quoting the message. Force-send media when the user explicitly wants a channel post: ```bash python3 scripts/openclaw_relay.py force-send \ --transport ssh \ --host [email protected] \ --target maintainers \ --text "Demo video." \ --media /tmp/demo.mp4 ``` Use the persistent control session: ```bash 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: ```bash python3 scripts/openclaw_relay.py doctor --transport ssh --host [email protected] python3 scripts/openclaw_relay.py send \ --transport ssh \ --host [email protected] \ --message "Reply with exactly OK." ``` ## Async Workflow Queue work and poll the same control session: ```bash 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: ```json { "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
© steipete · MIT · steipete/agent-scripts