How to Configure Switchyard for OpenClaw Launcher Integration

Switchyard's built-in OpenClaw launcher auto-generates a temporary workspace that binds the OpenClaw UI to a native Switchyard server, routing all LLM traffic through Switchyard's proxy with zero manual configuration.

Configuring Switchyard for OpenClaw launcher integration lets you run the OpenClaw terminal UI directly against Switchyard's orchestration layer. This setup—in NVIDIA-NeMo/Switchyard—creates a transient OpenClaw configuration that points to your local Switchyard proxy, handling environment setup and cleanup automatically.

Prerequisites for OpenClaw Launcher Configuration

Before running the integration, verify two dependencies:

• OpenClaw binary installed globally: npm install -g openclaw@latest
• Switchyard TOML deployment file: defines your routing rules and model providers

The launcher searches for the OpenClaw binary using shutil.which, then falls back to common installation paths under ~/.npm-global, ~/.local, and NVM directories. If the binary cannot be found, the launcher aborts with exit code 127 per openclaw_launcher.py::_find_openclaw_binary (lines 43-60).

How the Integration Works

The OpenClaw launcher in switchyard/cli/launchers/openclaw_launcher.py orchestrates seven distinct steps:

1. Binary Discovery

The _find_openclaw_binary helper locates the OpenClaw executable. It checks system PATH first, then iterates through Node.js installation directories.

2. Transient Config Generation

_build_openclaw_config (lines 78-115) constructs a JSON file describing Switchyard-provided models. The generated openclaw.json contains:

• A providers block with baseUrl set to http://127.0.0.1:<port>/v1
• An API key placeholder (SWITCHYARD_API_KEY)

3. Workspace Isolation

_write_openclaw_workspace (lines 19-33) creates a temporary directory via tempfile.mkdtemp and writes the configuration there.

4. Native Server Startup

_start_native_server (lines 76-79) launches the Rust-based Switchyard server using your supplied TOML deployment. The NativeServer class in switchyard/cli/launchers/native_server.py returns the bound port and a stats object for live monitoring.

5. Health Check Polling

_wait_ready (lines 63-66) calls wait_for_proxy_ready, which probes GET /health until HTTP 200 or timeout.

6. OpenClaw Execution

_run_openclaw_with_switchyard (lines 81-125) launches the UI. In interactive terminals, it uses ShellTUI for full-screen display. Non-interactive mode runs the binary as a supervised background process.

7. Automatic Cleanup

_remove_openclaw_workspace (lines 37-41) triggers after UI exit: session summary printed, native server shut down, temporary directory deleted.

CLI Configuration for OpenClaw Launcher

The fastest way to configure Switchyard for OpenClaw launcher integration is the switchyard launch openclaw command:

# Install OpenClaw globally

npm install -g openclaw@latest

# Launch with Switchyard routing

switchyard launch openclaw \
    --config my_route.toml \
    --model gpt-4o-mini \
    -- --no-history

Flag reference:

Flag	Purpose
--config	Path to TOML deployment file (e.g., dev-server/config.toml)
--model	Fully-qualified model ID; switchyard/ provider prefix auto-prepended
--	Separator; all subsequent arguments passed directly to OpenClaw binary

Programmatic OpenClaw Launcher Configuration

For custom model catalogs or batch automation, call the Python API directly from switchyard/cli/launchers/openclaw_launcher.py:

from pathlib import Path
from switchyard.cli.launchers.openclaw_launcher import launch_openclaw_config

# Path to TOML deployment

config_path = Path("dev-server/config.toml")

# Execute with specific model and OpenClaw args

exit_code = launch_openclaw_config(
    config=config_path,
    model="gpt-4o-mini",
    openclaw_args=["--no-history", "--theme", "dark"]
)

print(f"OpenClaw exited with code {exit_code}")

The launch_openclaw_config function handles all seven integration steps internally: binary discovery, workspace creation, server startup, health polling, UI launch, and cleanup.

Environment Variables Injected by the Launcher

The launcher sets three environment variables before spawning OpenClaw:

• OPENCLAW_STATE_DIR → temporary workspace root
• OPENCLAW_HOME → temporary workspace root
• OPENCLAW_CONFIG_PATH → path to generated openclaw.json

These overrides ensure OpenClaw loads Switchyard's generated configuration instead of any user defaults.

Key Source Files for Reference

File	Location	Role
openclaw_launcher.py	switchyard/cli/launchers/openclaw_launcher.py	Core integration: workspace creation, env setup, process supervision
native_server.py	switchyard/cli/launchers/native_server.py	Rust server launcher from TOML; exposes port and stats
launch_command.py	switchyard/cli/launch_command.py	Top-level switchyard launch dispatcher
cli_reference.md	docs/cli_reference.md	Official CLI documentation
config.toml (example)	dev-server/config.toml	Sample deployment configuration

Summary

• Install prerequisite: OpenClaw binary must be available via npm install -g openclaw@latest
• Provide deployment: TOML config file defines Switchyard routing rules
• Use CLI shortcut: switchyard launch openclaw --config <file> --model <id>
• Leverage Python API: launch_openclaw_config() for programmatic control
• Trust auto-cleanup: temporary workspaces and server processes terminate automatically post-session

Frequently Asked Questions

What happens if OpenClaw is not installed?

The launcher aborts with exit code 127 after exhausting search paths in _find_openclaw_binary. Install with npm install -g openclaw@latest and verify with which openclaw.

Can I use multiple models with OpenClaw through Switchyard?

Yes. The _build_openclaw_config function generates a providers block that can enumerate multiple Switchyard models. Pass any model ID from your TOML deployment via the --model CLI flag or model parameter in the Python API.

How do I pass custom arguments to the OpenClaw binary?

Place them after the -- separator in CLI mode, or include them in the openclaw_args list when calling launch_openclaw_config() programmatically.

Does the integration work in CI/non-interactive environments?

Yes. The launcher detects terminal interactivity and falls back to background process supervision when stdin.isatty() returns False. Session statistics are still collected and printed on exit.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}