How to Connect OpenClaw to Codex with Scout on a Linux VM

Here’s how we use OpenClaw, Scout, and Codex agents together on our VMs.

We gave OpenClaw a throwaway Linux VM that already ran Scout, connected a small session adapter, and asked it to remember a marker. The first reply worked. The follow-up worked. Closing the connection and starting another did not.

That last check found the interesting part: OpenClaw has a session identifier for the bridge process and a separate key for the conversation behind it. Once Scout preserved the right one, the conversation survived reconnection—from the VM itself and from a Mac over Tailscale.

This guide turns that experiment into a setup you can repeat. We also installed the published Scout package in an isolated Linux environment to check the installation path rather than relying on the VM's existing service.

For the short version, use the OpenClaw integration page.

What you will have

There are two connections to keep distinct:

• OpenClaw calls Scout. OpenClaw's exec tool runs the installed Scout CLI on the VM. We verified CLI identity, a delegated read-only Codex task, and retrieval of its completed answer.
• A Scout session client drives OpenClaw. A downloadable preview uses OpenClaw's ACP bridge to send prompts, follow up, and reconnect. It works locally or through SSH.

The preview is not a new broker runtime. scout ask --harness openclaw, a runtime-picker entry, and automatic delivery into an idle OpenClaw session are not implemented. The published Scout CLI and the downloadable preview are separate artifacts.

1. Start with a VM you control

We used an exe.dev Ubuntu VM with two CPUs and about eight gigabytes of memory. That is the tested environment, not a minimum sizing claim. Any comparable Linux VM with SSH, outbound HTTPS, and an operator account with sudo is a reasonable place to repeat the exercise.

The commands below run in Bash on the VM unless a section says otherwise. They assume a new test account without an existing Scout or OpenClaw configuration. Keep an existing installation's service and credentials intact rather than pasting these over it.

Install the small system prerequisites:

You will also need a model-provider account. The model calls in this walkthrough consume its quota. The example uses an OpenAI API key; a ChatGPT login alone does not supply that key.

2. Install the published Scout CLI

Install Bun↗, then the exact Scout version used in this check:

Setup writes configuration. On Linux, the foreground broker needs a process manager if you want it to survive logout and reboot. Create a systemd service for your current account:

After the service starts, verify the broker rather than just the package:

The health response should report ok: true and startup readiness. Check that whoami names your intended project and broker. Doctor can also report coding runtimes that you have not installed; the broker check is the relevant one at this stage.

A release detail: Scout 0.2.110 passed the isolated Linux foreground-startup and doctor checks. Its setup output can still print a request to start the broker after that broker is healthy. Use the health response and doctor result to distinguish that stale hint from a real startup failure. Do not start a second broker merely because the hint remains.

3. Install OpenClaw separately

The OpenClaw CLI installer↗ can install its own Node runtime without changing the system Node installation:

We tested OpenClaw 2026.9.7 with its installed Node 24.21.0 runtime. Pinning the version makes the experiment easier to compare; validate changes before moving this setup to another version.

4. Configure credentials and the Gateway

On this fresh test account, create OpenClaw's environment file with private permissions. The prompt below reads the key without echoing it or placing it in the command history:

Use OpenClaw's noninteractive setup to configure a local Gateway and an environment-backed provider credential. The risk acknowledgement is explicit because OpenClaw agents can execute tools on this machine. These commands belong on the VM you authorized for that purpose.

Heartbeat and scheduled jobs are disabled for this test. We want explicit test turns, not background activity. The Gateway remains authenticated and bound to loopback; the later remote test will use SSH.

5. Run the Gateway and choose a listed model

Create a second service. It runs as your operator account, with its normal OpenClaw configuration and credential file:

Choose a model that appears in that list and is available to your account. Our run used:

Do not substitute a familiar model name without checking. Our first attempt saved a model that was not in OpenClaw's current catalog. The Gateway accepted the request, then failed before producing a reply. Configuration saved and inference working are different checkpoints.

6. Let OpenClaw call Scout

Start an OpenClaw conversation using your normal OpenClaw client. Ask it to run this read-only command through its exec tool:

Compare its result with the command you ran in the VM shell. The actor and broker should match. Honor any tool approval that OpenClaw presents; changing a prompt does not change the tool policy.

In our test, OpenClaw ran a small wrapper that saved the CLI result. We read that file independently and confirmed the identity and local broker URL. That verifies actual CLI execution, rather than relying only on the agent saying it connected.

Next, authenticate a coding agent on the VM. OpenClaw's provider configuration does not automatically log that agent in. We used Codex with an API key supplied privately through its supported login flow.

Create a small input file in the test workspace:

Ask OpenClaw to run the following through its exec tool. It should delegate the task, not calculate the answer itself:

Keep the returned reference. Ask OpenClaw to retrieve that same task, replacing RETURNED_REF below:

Our round trip completed: OpenClaw submitted the ask, Scout launched Codex, Codex returned SUM=873, and OpenClaw retrieved that answer. We independently checked the broker's completed result against the input file. A queued receipt alone is not completion; require the completed state and worker output. If a wait times out, observe the same reference instead of submitting the work again.

This proves explicit delegation and result retrieval. It does not prove automatic delivery into an idle OpenClaw conversation.

7. Exercise the preview session adapter on the VM

The preview smoke test bundles Scout's development session client. It requires Bun and the configured OpenClaw executable, but no checkout of the Scout repository. It is not part of the npm broker's supported harness list.

Download it, inspect it, then run it:

It prints a result for each check:

1. Fresh: the agent returns a newly generated marker.
2. Warm: a follow-up recalls the marker without being told it again.
3. Cold resume: a new bridge reconnects and recalls the same marker.
4. Missing session: an unknown continuation fails instead of starting a replacement conversation.

The first three checks passed on the VM and across machines. Missing-session rejection was also verified on the remote route. The script closes the bridge processes it opens; the shared Gateway remains running.

8. Repeat from your Mac or another machine

Join both machines to your Tailscale network using its normal authentication flow, or use an existing authorized SSH route. Confirm SSH access before trying ACP. Replace the account, host, and executable path below with your VM's values.

On the client machine, install Bun, download the same smoke test, and run:

SSH starts the OpenClaw bridge on the VM and carries ACP over stdin and stdout. Model credentials stay on the VM. There is no need to expose the Gateway port publicly or install OpenClaw on the client machine.

The working directory on your Mac is not a path on the VM. --no-prefix-cwd prevents the bridge from adding that local path to its prompts. The OpenClaw agent uses its configured VM workspace.

Why reconnection needed a fix

OpenClaw's ACP bridge returns a UUID when it creates a session. That identifier works for subsequent requests handled by the same bridge process. It is not sufficient to find the conversation after that process closes.

The durable Gateway key arrives separately in session_info_update._meta.sessionKey. Scout's preview now retains that key as the native continuation handle. If it is missing, the client does not offer the temporary UUID as a usable substitute.

The regression test now gives those two identifiers different values. The live test also checks remembered content after reconnecting. Matching identifiers alone would not prove that the conversation survived.

Keep the useful boundary

We now have a small, repeatable environment: Scout's broker and OpenClaw's Gateway on one VM, a verified OpenClaw-to-Codex round trip through Scout, and a session preview that works across machines.

It is a useful base for the next tests: broker routing into OpenClaw, interactive approval handling, and automatic delivery back into an existing session. Those capabilities should earn their own verification before the integration page claims them.

When you are finished with a VM created for this guide, stop its two services with sudo systemctl disable --now openclaw-guide.service scout-guide.service. Remove the test credential through your provider's normal account controls if you no longer need it. On a shared VM, stop only the services you created.