Skip to content
Get packs

Guide · Agent skill

How to use the OpenClaw Session Relay agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The OpenClaw Session Relay skill (openclaw-relay) lets an AI agent send messages into existing OpenClaw assistant sessions, either on the same computer or on another machine reached over SSH. It is aimed at developers and maintainers who already run OpenClaw and want an agent to message a session or channel without copy-pasting between tools. After this guide you will know what the skill does, how to install it, how to phrase requests so the agent triggers it, and what safety settings to check first.

OpenClaw Session Relaysteipete/agent-scripts · MIT

Quick start

  1. 1Download and unzip. Download the openclaw-relay ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
  2. 2Check requirements. Confirm Python 3, an OpenClaw checkout with acpx, and the gateway token at ~/.openclaw/gateway.token (or your own path).
  3. 3Replace placeholder aliases. Edit config/session_aliases.json and replace the placeholder values with real session keys for your setup.
  4. 4Run doctor. Run python3 scripts/openclaw_relay.py doctor to confirm the health check passes, adding --transport ssh and --host for remote hosts.
  5. 5Resolve a target. Run resolve --target with your alias to confirm where a message will go before sending anything.
  6. 6Send a test ask. Use ask with a short message to probe the route before sending a real payload.

What is an agent skill, and what does openclaw-relay do?

An agent skill is a folder with a SKILL.md file that tells an AI agent when and how to perform a task, often with bundled scripts. The openclaw-relay skill covers relaying work into OpenClaw sessions through the acpx tool, using one bundled Python script, scripts/openclaw_relay.py.

The skill supports two transports. The local transport works from the current OpenClaw checkout and is the default, suited to quick relays or private questions. The ssh transport is for a target session that lives on another machine, and is also the choice when you want a persistent bridge session or async queue, wait and show flows.

  • ask: privately ask a target session a question
  • publish: let the target session decide whether to post
  • force-send: post text or media directly to the resolved target
  • send, start, wait, show, cancel: control-session and async work

Install the openclaw-relay skill

Download the skill ZIP from this page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

You can also upload the skill in the Claude apps: go to Settings, then Capabilities, then Skills, and upload the skill there.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills

Set up the requirements before first use

The skill needs Python 3 and an OpenClaw checkout that includes the acpx tool: extensions/acpx locally, or a remote acpx repo reached over SSH. For gateway access it needs a gateway token file, which defaults to ~/.openclaw/gateway.token. If you use the ssh transport, you need SSH access to the remote host.

Before relying on the skill, replace the placeholder values in config/session_aliases.json with real values for your setup. The file ships with placeholders, so relays will not reach your sessions until you do this.

  • Python 3
  • OpenClaw checkout with acpx (extensions/acpx locally, or a remote acpx repo over SSH)
  • Gateway token file, default ~/.openclaw/gateway.token
  • SSH access to the remote host for ssh transport
  • Real target values in config/session_aliases.json
python3 scripts/openclaw_relay.py doctor

Trigger the skill with natural requests

The skill is meant to be triggered by plain requests. The SKILL.md lists examples such as "talk to Molty", "relay this into an OpenClaw channel session", "use acpx", "send this through the gateway via acp" and "work through a remote OpenClaw bridge over SSH".

Say "use acpx" when you want the local transport explicitly. Mention a remote host or SSH bridge when the target lives on another machine. Do not use it for team.openclaw.ai: the SKILL.md says that server is handled by a different skill, team-handoff.

Examples of common commands

Check health, list aliases, then ask a target a private question. Use --text-file for multiline posts instead of shell-quoting the message. Keep the control session in mind for blocking or async work.

For a remote host, add --transport ssh and --host with the SSH address. The SKILL.md example uses steipete@steipete-macstudio.local; use your own host.

  • Ask privately: ask --target maintainers --message "..."
  • Force-send text: force-send --target maintainers --text "..."
  • Queue work: start --message "...", then wait --after-seq <last-seq>, then show
python3 scripts/openclaw_relay.py ask \ --target maintainers \ --message "Summarize the current vibe in this channel."

Safety notes: scripts and network access

This skill runs scripts and uses the network. The bundled script sends messages to real OpenClaw sessions and channels, so check the target before sending. The force-send command bypasses the target session's own decision about whether to post, so a mistake reaches the audience directly. Prefer publish when you want the session to decide, and test with a tiny ask first.

The skill also includes scripts/test_doctor_token.py and agents/openai.yaml. Review the files in the ZIP before installing, especially if you plan to run it against a remote gateway.

  • force-send skips the target session's review; use it only when a direct post is intended
  • Prefer publish or ask when unsure
  • Keep the gateway token file private
  • Use an exact session key or alias, and resolve it first

Troubleshooting and tips

If relay work fails, run doctor, then status, then show. If the control session is wedged, run cancel, then ensure, and retry. If route discovery is uncertain, resolve the target first and run a tiny probe ask before the real payload.

Avoid the mac-studio SSH alias for one-shot relay work, because the SKILL.md says it auto-attaches tmux. Use the full user@host address instead.

  • Run doctor first on every new setup
  • Use resolve to confirm the target
  • Report the transport, target session key and result

What people use it for

  • Asking a specific OpenClaw assistant session a private question from your current machine
  • Relaying announcements into a maintainers channel session
  • Posting a demo video or text to a channel when you explicitly want a direct post
  • Queuing a long task on a remote OpenClaw bridge and polling for the reply

Frequently asked questions

How do I install the openclaw-relay skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.

What are the requirements for the OpenClaw relay skill?

You need Python 3, an OpenClaw checkout with the acpx tool, and a gateway token file, which defaults to ~/.openclaw/gateway.token. For the ssh transport you also need SSH access to the remote host, and you must replace the placeholders in config/session_aliases.json.

Is the openclaw-relay skill free?

The skill is listed under the MIT licence in its source. The licence terms are what govern use and redistribution; check the repository's licence file for the full text.

Can it post to team.openclaw.ai?

No. The SKILL.md says the Team server is handled by a different skill, team-handoff, and this skill will not handle starting or inspecting sessions there.

Why does my relay fail or do nothing?

Run doctor, then status, then show. Check that the gateway token file exists, acpx is available, and the aliases file has real values rather than placeholders. If the control session is stuck, run cancel, then ensure, and retry.

What is the difference between ask, publish and force-send?

ask gets a private reply from a specific session. publish lets the target session decide whether to post. force-send posts directly to the resolved target and bypasses that decision, so use it only when you intend a direct post.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already run OpenClaw assistants or channel sessions and want an agent to message them locally or over SSH. Skip it if you have no OpenClaw installation or gateway, or if you need to manage sessions on team.openclaw.ai, which requires the separate team-handoff skill.

Download the skill