# How to Configure Switchyard for OpenClaw Launcher Integration

> Easily integrate OpenClaw with Switchyard using the built-in launcher. Auto-generates workspaces and routes LLM traffic through Switchyard's proxy seamlessly. Get started now.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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:

```bash

# 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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launchers/openclaw_launcher.py):

```python
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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/openclaw_launcher.py) | [`switchyard/cli/launchers/openclaw_launcher.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launchers/openclaw_launcher.py) | Core integration: workspace creation, env setup, process supervision |
| [`native_server.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/native_server.py) | [`switchyard/cli/launchers/native_server.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launchers/native_server.py) | Rust server launcher from TOML; exposes `port` and `stats` |
| [`launch_command.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/launch_command.py) | [`switchyard/cli/launch_command.py`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard/cli/launch_command.py) | Top-level `switchyard launch` dispatcher |
| [`cli_reference.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/cli_reference.md) | [`docs/cli_reference.md`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/cli_reference.md) | Official CLI documentation |
| [`config.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/config.toml) (example) | [`dev-server/config.toml`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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.