Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add steipete/agent-scripts --skill openclaw-relay -a claude-code
Open on GitHub

What 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, and show
  • Resolve a session alias before sending a real payload to verify the route
  • Run a transport health check with doctor before a relay job

Example prompts for the agent

  • Relay this message to the maintainers session using openclaw-relay
  • Run openclaw_relay.py doctor with ssh transport and report the result
  • Send the contents of report.txt to the main session over SSH

How to install openclaw-relay

1Skills CLI (Vercel)

npx skills add steipete/agent-scripts --skill openclaw-relay -a claude-code

2Manually: put the files in place

~/.claude/skills/openclaw-relay/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/openclaw-relay/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set20

The whole set →
instruments-profiling The instruments-profiling skill guides macOS and iOS profiling with Instruments and xctrace, from trace capture to stack export. Use it when a native app has a slow path. CX Codex +1 242installs ssh-doctor ssh-doctor troubleshoots macOS SSH failures, including pre-auth disconnections, stale sshd sessions, and Remote Login misconfigurations. CX Codex +1 239installs domain-dns-ops The domain-dns-ops skill guides domain, Cloudflare zone, and redirect work. Use it when setting up a domain and checking DNS or HTTPS behavior. CX Codex +1 192installs discord-clawd discord-clawd — a skill to send questions to a Discord-backed agent via OpenClaw relay. Not for archive search—use it to communicate directly with a live session. CX Codex +1 122installs mac-maintenance mac-maintenance automates macOS maintenance by upgrading Homebrew packages, pulling clean git repositories, and emptying the Trash. CX Codex +1 117installs cloudflare-registrar A skill to check domain availability in Cloudflare Registrar, retrieve pricing, and register domains from your code editor. Use it when you register domains regularly and want to skip the dashboard. CX Codex +1 108installs codex-debugging codex-debugging guides debugging across the codex-rs repository. Essential when investigating runtime bugs, CLI behavior, or config parsing issues. CX Codex +1 108installs github-project-triage The github-project-triage Claude Code skill reviews open GitHub issues and pull requests when prompted with “triage.” It surfaces blockers, checks, risks, and a next action for each item. CX Codex +1 105installs

Project sponsors

Companies that keep this analytics open