Best practices for using ACP as a remote node to connect to my OpenClaw gateway?

[minor parcel]

Hi folks, I’m trying to set up a remote workflow and want to confirm the recommended pattern for ACP.

My setup

• Gateway host (Claw): runs OpenClaw gateway
• Remote compute host (Vast): where I want to run ACP/Codex workloads
• Gateway is kept on bind: loopback (for security)
• I connect Vast -> Claw via SSH tunnel

What I’m doing

On Vast, I create a tunnel:

ssh -N -L 18789:127.0.0.1:18789 <claw_host>

Then I start ACP:

openclaw acp --url ws://127.0.0.1:18789 --token <gateway_token>

I can see logs like:

• [acp] ready
• [acp] gateway reconnected

But:

• openclaw nodes list shows Paired: 0
• If I bind to a Discord session key (e.g. agent:main:discord:channel:...), I get:
  ACP_SESSION_INIT_FAILED: Session is not ACP-enabled

Questions

1. Is it expected that nodes list stays 0 when using openclaw acp bridge mode?
2. What is the correct way to create/use an ACP-enabled session (vs normal Discord session)?
3. Should I always use /acp spawn first, then pass that session key to openclaw acp --session <key>?
4. Any recommended production pattern for persistent ACP on remote hosts (tmux/systemd/autoreconnect)?

Would appreciate a minimal “known-good” flow. Thanks!

[daring anvil]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[tough sun]

1. Yes — openclaw nodes list staying at 0 is expected.
   openclaw nodes … is for paired nodes (iOS/macOS/headless “node mode”) that connect to the gateway with role:"node" and expose things like canvas/camera/system.*. The openclaw acp command is an IDE ACP bridge over stdio, not a node, so it will never show up in nodes list.
   Docs: https://docs.openclaw.ai/nodes and https://docs.openclaw.ai/cli/acp

---

2. An “ACP-enabled session” is not your Discord channel session key.
   A Discord session key like agent:main:discord:channel:... is a normal chat/requester session. The /acp … command family (and the ACP runtime control plane) expects an actual ACP runtime session (key shape like agent:<agentId>:acp:<uuid>). If you point ACP controls at a normal Discord session, you’ll get exactly what you saw: “Session is not ACP-enabled”.
   Docs: https://docs.openclaw.ai/tools/acp-agents (see “ACP versus sub-agents” + session key table)

How to create one:

• From chat (Discord): /acp spawn codex --mode persistent --thread auto
  This creates an ACP session and (optionally) binds the thread so follow-ups route correctly.
• From tool calls (inside OpenClaw): sessions_spawn({ runtime:"acp", agentId:"codex", thread:true, mode:"session" }) (shown in the docs above)

---

3. Do you need /acp spawn first? It depends what you’re trying to do.

• If your goal is “run Codex/Claude Code/etc as an ACP harness session” → yes, start with /acp spawn … (or sessions_spawn with runtime:"acp"), then interact via the bound thread (or target that ACP session key explicitly).
• If your goal is “use an IDE that speaks ACP to drive a normal OpenClaw gateway session” (the openclaw acp bridge use-case) → no, you can just run openclaw acp … --session agent:main:main (or let it default to an isolated acp:<uuid> key). That has nothing to do with nodes pairing.

---

4. Production-ish “persistent remote host” patterns
   There are two separate “remote host” stories:

A) Remote compute (run shell/tests/etc on Vast)

Use a node host, not openclaw acp. This is the thing that will show up in nodes list, and it’s the supported pattern with loopback + SSH tunnel:
Docs (includes the tunnel example): https://docs.openclaw.ai/nodes#remote-gateway-via-ssh-tunnel-loopback-bind

Minimal known-good:

# on Vast (terminal A): tunnel to gateway loopback

ssh -N -L 18790:127.0.0.1:18789 user@<claw_host>

# on Vast (terminal B): start node host through the tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway_token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Vast compute"

Then approve pairing on the gateway host (openclaw devices list/approve or openclaw nodes pending/approve depending on your flow), and then nodes list will show it.

For persistence: prefer openclaw node install + service restart, or systemd + autossh (if you want the tunnel managed).

B) Persistent ACP harness sessions (Codex/Claude Code)

That’s mainly supervised by the gateway + ACP backend plugin; the “persistence” is typically the ACP session store + thread binding, not a daemon you run on Vast.

---

If you confirm which of these you actually want:

• “I want tool/exec to happen on Vast” (tests/builds/git, etc.)
  vs
• “I want Codex ACP harness to run on Vast” (not just be triggered from Vast)

…I can give you a single, minimal end-to-end flow for that exact goal. Also helpful: paste openclaw --version (ACP has been moving fast).

[minor parcel]

I want Codex ACP harness to run on Vast

[tough sun]

If you want the Codex ACP harness to actually run on Vast, the key constraint is:

ACP harnesses (via the acpx backend) run on the same machine that’s running the Gateway, because the ACP backend is a Gateway plugin service that shells out to acpx/codex locally. There isn’t a “remote ACP worker node” mode today.

So with your current layout (Gateway on Claw), Codex ACP will run on Claw, not on Vast — even if you run openclaw acp on Vast. (openclaw acp is just an IDE stdio bridge to a gateway session; it doesn’t move the harness runtime.)

Minimal known-good flow to run Codex ACP on Vast

1. Run the OpenClaw Gateway on Vast (you can still keep gateway.bind: "loopback" and use SSH tunneling for operator/UI access).
   Remote access pattern: https://docs.openclaw.ai/gateway/remote

2. On Vast (the Gateway host) install/enable ACP backend:

• Install plugin + enable it (docs): https://docs.openclaw.ai/tools/acp-agents

  openclaw plugins install @openclaw/acpx
  openclaw config set plugins.entries.acpx.enabled true
  

• Ensure ACP is enabled in config (example from docs):

  {
    acp: {
      enabled: true,
      dispatch: { enabled: true },
      backend: "acpx",
      defaultAgent: "codex",
      allowedAgents: ["pi","claude","codex","opencode","gemini"]
    }
  }

• Restart the gateway after config/plugin changes.

3. In Discord, run:

• /acp doctor (should report backend healthy / actionable errors)
• /acp spawn codex --mode persistent --thread auto

Now the Codex harness session is running on Vast (because that’s where the Gateway + acpx plugin live), and the thread binding keeps follow-ups routed to that ACP session.

If you must keep the Gateway on Claw

Then you can’t run the Codex ACP harness on Vast (with current architecture). The closest alternative is: keep Gateway on Claw, and run a node host on Vast to offload exec/compute there — but that’s not the Codex ACP harness runtime.

If you paste openclaw --version (on the machine you want to be the Gateway), I can tailor the exact commands/service setup (systemd vs tmux) for a “stays up forever” Vast deployment.

[minor parcel]

2026.2.26

[tough sun]

On 2026.2.26: if your goal is “Codex ACP harness runs on Vast”, then the important bit is:

ACP harness sessions (Codex/Claude Code/etc) run where the Gateway runs, because the ACP backend (acpx) is a Gateway plugin service that shells out locally. Running openclaw acp … on Vast is only an IDE stdio bridge to a Gateway session; it does not relocate the harness runtime.

Docs to anchor this:

• ACP bridge (IDE stdio ↔ gateway): https://docs.openclaw.ai/cli/acp
• ACP harness sessions + acpx backend plugin: https://docs.openclaw.ai/tools/acp-agents
• Nodes (separate concept): https://docs.openclaw.ai/nodes

What that means for your current topology (Gateway on Claw)

• openclaw nodes list staying at 0 is expected: ACP bridge ≠ node.
• The “Session is not ACP-enabled” error happens when you target /acp … controls at a normal Discord session key. ACP runtime sessions have their own keys (like agent:<id>:acp:<uuid>), created via /acp spawn … (or sessions_spawn(runtime:"acp")).

“Known-good” way to run Codex ACP on Vast

You need the Gateway to run on Vast (even if you keep it loopback-only + SSH-tunneled for access).

On Vast (Gateway host):

1. Install/configure the gateway normally (bind loopback is fine).
2. Install + enable the ACP backend plugin:

   openclaw plugins install @openclaw/acpx
   openclaw config set plugins.entries.acpx.enabled true
   

3. Enable ACP in config (minimum; from docs):
   • acp.enabled=true
   • acp.dispatch.enabled=true
   • acp.backend="acpx"
   • allow codex in acp.allowedAgents
4. Restart the gateway.

In Discord:

• /acp doctor (should report backend ready / actionable errors)
• /acp spawn codex --mode persistent --thread auto

At that point, the Codex harness is executing on Vast, because that’s where the gateway+plugin live.

If you must keep the Gateway on Claw

Then today you can’t have the Codex ACP harness run on Vast (no “remote ACP worker” mode). The closest alternative is: keep Gateway on Claw, and run a node host on Vast for remote exec/compute (tests/builds) — but that’s not Codex ACP.

If you want, I can sketch a clean “prod-ish” Vast setup (systemd unit for openclaw gateway, plus autossh tunnel pattern for your operator machine), but the main architectural decision is: gateway location = ACP harness location.

[minor parcel]

If I run gateway on vast, does that mean I have to mv the full folder there?

[tough sun]

No — you don’t need to “mv the full OpenClaw folder/source repo” to Vast.

What you do need (if Vast becomes the Gateway host, and you want to keep your existing setup) is to migrate state + workspace, because the gateway host owns config/auth/sessions/workspace:

• State dir: $OPENCLAW_STATE_DIR (default ~/.openclaw)
  Includes openclaw.json, auth profiles, channel creds, session store, etc.
• Workspace dir: agents.defaults.workspace (default ~/.openclaw/workspace)
  Includes AGENTS.md, MEMORY.md, skills, etc.

Docs (exact paths + migration steps):
https://docs.openclaw.ai/help/faq#where-does-openclaw-store-its-data

Known-good migration shape:

1. Install OpenClaw on Vast
2. Stop the gateway on Claw (so files aren’t changing under you)
3. Copy ~/.openclaw and your workspace directory from Claw → Vast
4. On Vast: run openclaw doctor, then start/restart the gateway