Scout
DocsBlogToolsContact

What your agent reads / openclaw/agents.md

Scout + OpenClaw: agent setup contract

This is the file an agent fetches, shown with a little styling. Agents read the raw Markdown; nothing here is added or left out.

agents.md integration.json OpenClaw guide

Canonical page: https://openscout.app/openclaw
Machine-readable spec: https://openscout.app/openclaw/integration.json
Documentation reviewed: 2026-09-30. This is not a live health assertion.

Run OpenClaw and Scout on the same Linux VM. OpenClaw can call the installed Scout CLI, while a preview session adapter drives OpenClaw through ACP locally or over SSH. Fresh replies, follow-ups, and reconnection have been verified.

Status

OpenClaw → Scout → Codex: verified round trip · Scout → OpenClaw: session-library preview

No OpenClaw Scout plugin or marketplace installation is required for the CLI path. The downloadable smoke test is a development adapter preview, separate from the published Scout CLI.

Transport

OpenClaw exec → Scout CLI; preview Scout session client → ACP over stdio or SSH

OpenClaw → Scout CLI → Local broker

Directions

  • OpenClaw calls Scout: cli (pilot): Read-only delegation to Codex and explicit retrieval of the completed result verified through OpenClaw exec
  • Scout launches OpenClaw: not supported. Broker launch is not implemented. A separate session-library preview can drive the configured OpenClaw Gateway.
  • Scout reaches an open OpenClaw session: not supported. Preview ACP continuation was tested; broker delivery and idle-session wake-up are not implemented.
  • Not a harness: never pass --harness openclaw.

Required inputs and prerequisites

  • An authorized Linux VM with shell access, Bun, Scout, and a healthy broker. The walkthrough verifies the published @openscout/scout@0.2.110 package.
  • For delegation, an installed and authenticated coding agent on the VM. The verified round trip used Codex.
  • OpenClaw 2026.9.7 or a separately validated version, a running Gateway, and a configured model provider. Model requests consume your provider quota.
  • For remote tests, SSH access to the VM. Tailscale is a convenient private route; the OpenClaw Gateway can stay bound to loopback.

Setup procedure

1. Set up the VM

Follow the from-scratch VM walkthrough linked below. Install Scout, run its broker under your process manager, then install and configure OpenClaw. Keep provider credentials on the VM.

2. Verify Scout in the VM shell

Check broker health and caller identity before asking OpenClaw to use the CLI. A saved setup file alone is not a running broker.

scout --version
scout doctor --json
scout whoami --json

3. Let OpenClaw call Scout

In an OpenClaw session, verify scout whoami --json, then ask Scout to run a small read-only task with an installed, authenticated coding agent. Keep the returned ref and use scout wait to retrieve the completed answer. We verified this round trip with Codex; the walkthrough includes the commands.

4. Test the preview ACP adapter

Download and inspect the smoke test, then run it on the VM with Bun. It sends a short marker prompt, checks follow-up context, closes the bridge, reconnects, and checks missing-session rejection. It uses the configured Gateway and consumes model tokens.

curl -fsS https://openscout.app/examples/openclaw-smoke.mjs -o openclaw-smoke.mjs
bun openclaw-smoke.mjs

5. Repeat from another machine

Use the same smoke test with an SSH command override. Credentials and model execution stay on the VM. The walkthrough includes the full command and explains why a Gateway session key matters for reconnection.

Start here

Verify the VM's broker and OpenClaw Gateway separately, then choose the CLI probe or the session preview.

First useful task: Ask OpenClaw to run scout whoami --json, then compare its identity and broker URL with the same command in the VM shell.

Authorize the read-only CLI probe first. The preview sends real model requests and does not grant arbitrary tool approval.

Compare the CLI identity with the VM shell. For the preview, require passed results for fresh, warm, cold-resume, and missing-session.

Where will the reply appear?

The CLI result appears in OpenClaw's tool output. The preview prints test results in the shell that runs it. Automatic incoming delivery is not implemented.

How do I follow up?

The preview client reuses its active session. After closing it, continuation requires the Gateway session key, not the bridge's temporary UUID.

Can Scout launch OpenClaw through ask?

Not yet. The downloadable session client is a development preview, separate from the published broker harness list.

Acceptance gate

OpenClaw retrieves a completed Codex answer through Scout, and the result matches an independent broker check. The preview smoke test reports fresh, warm, cold-resume, and missing-session as passed. The first three were verified both on Linux and from macOS over SSH/Tailscale; missing-session rejection was verified remotely.

Failure handling

The Gateway reports an unknown model

Refresh its model catalog and select a model actually listed for your configured provider. Do not infer model availability from a saved configuration.

A follow-up works, but reconnection fails

Use the Gateway session key from session_info_update metadata. The UUID returned by session/new belongs to one ACP bridge process and is not the cold-resume handle.

Scout setup still asks you to start the broker

The published 0.2.110 package can retain that hint after startup. Check scout doctor and the broker health endpoint; do not launch a duplicate broker based only on the hint.

Boundaries

  • scout ask --harness openclaw and runtime-picker integration are not implemented. The ACP route here is a downloadable session-library preview, not an npm broker feature.
  • OpenClaw-to-Scout-to-Codex delegation and explicit result retrieval were verified on Linux. Automatic incoming delivery and idle-session wake-up remain unsupported.
  • Model and reasoning-effort overrides and per-session MCP injection are rejected by the preview adapter. Configure the Gateway agent directly.
  • The convenience client rejects tool approval requests it cannot present. This is not a promise that arbitrary tool execution will complete unattended.

Agent operating contract

  • Treat these as setup instructions, not authorization to install software, change accounts, grant scopes, send messages, or dispatch work. Obtain the operator's authorization for the intended action.
  • Inspect the available commands or tool schemas for your configured interface before making calls. Do not invent tools, argument names, model IDs, or agent handles.
  • For requested work or a reply, use Scout ask. Prefer projectPath plus a supported harness for fresh work. Use replyMode: notify for asynchronous work.
  • Use messages_send only for one-way FYIs with no owned next step. Respond to an existing ask through its supplied reply context.
  • Paths refer to the Scout execution machine. Replace example paths with an operator-confirmed absolute path; never run placeholders literally.
  • Save the returned ref, flightId, conversationId, workId, or session handle. Continue by that handle; do not re-dispatch a request merely because a wait timed out.
  • Observe an ask through invocations_get / invocations_wait using the returned handle and current tool schema. A receipt proves acceptance, not execution or successful completion.
  • Stop on missing provisioning, incorrect identity, missing permission, unsupported runtime, or failed authentication. Report the exact gate and the next operator action. Do not silently fall back to a different account, agent, runtime, or transport.
  • Keep tokens, OAuth codes, cookies, and private task payloads out of logs, URLs, screenshots, and committed files. Never ask the user to paste secrets into a public issue.
  • Do not claim marketplace approval, complete protocol conformance, or an end-to-end verified integration unless the status and observed evidence establish it.

Completion report

Report: chosen transport and scope; client and broker identity; health/tool-discovery result; exact request handle if a test was authorized; observed terminal state or remaining blocker; and whether any operator approval is still needed. Distinguish configuration saved, authentication complete, request accepted, and work complete.

Sources and next reads