> ## Documentation Index
> Fetch the complete documentation index at: https://www.stratus.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw Integration

> Bring Stratus X1 world model prediction into OpenClaw — composable, autonomous, zero fluff.

<img src="https://stratus.run/og-hackathon.jpg" alt="Stratus X1 × OpenClaw" style={{ width: '100%', borderRadius: '12px', marginBottom: '24px' }} />

[OpenClaw](https://openclaw.ai) is a developer-native autonomous agent framework built on UNIX principles — composable tools, explicit config, clean interfaces, no magic. It runs SIGBART, its agent runtime, across TUI, Telegram, and Discord with a plugin system that actually respects your boundaries.

This is the official Stratus X1 plugin for OpenClaw. One install drops the full model catalog, semantic state embeddings, and multi-step rollout planning directly into your SIGBART agent. No postinstall scripts. No automatic rewrites to your config. You opt in, you run the wizard, you're done.

<CardGroup cols={3}>
  <Card title="Full Model Catalog" icon="layer-group" color="#22d3ee">
    Every X1-AC model across GPT-4o, Claude 4.x/3.x, and more — fetched live from the API at gateway start.
  </Card>

  <Card title="Native Tools" icon="wrench" color="#c084fc">
    `stratus_embeddings` for 768-dim semantic state vectors. `stratus_rollout` for multi-step action planning.
  </Card>

  <Card title="Zero Config" icon="wand-magic-sparkles" color="#34d399">
    `/stratus setup` in any OpenClaw chat interface handles everything. No manual JSON editing required. 🧈
  </Card>
</CardGroup>

<Note>
  **Plugin Status:** Public Beta — [`@formthefog/stratus`](https://github.com/formthefog/openclaw-stratus-x1-plugin) · Version `2026.2.24`
</Note>

***

## Installation

The recommended method is the OpenClaw plugin registry:

```bash theme={null}
openclaw plugins install @formthefog/stratus
```

Or install directly:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @formthefog/stratus
  ```

  ```bash GitHub URL theme={null}
  npm install https://github.com/formthefog/openclaw-stratus-x1-plugin
  ```

  ```bash pnpm theme={null}
  pnpm add https://github.com/formthefog/openclaw-stratus-x1-plugin
  ```
</CodeGroup>

<Warning>
  **No auto-setup.** The plugin does not run a postinstall script — consistent with OpenClaw's philosophy that tools are opt-in. Run the setup wizard manually after installation.
</Warning>

***

## Setup

<Tabs>
  <Tab title="Interactive Wizard (Recommended)">
    **Step 1 — Set your API key in the environment first.** The wizard reads it from there; it does not prompt interactively.

    ```bash theme={null}
    export STRATUS_API_KEY=stratus_sk_live_your_key_here
    ```

    To persist across sessions:

    ```bash theme={null}
    echo 'export STRATUS_API_KEY=stratus_sk_live_your_key_here' >> ~/.zshrc
    source ~/.zshrc
    ```

    **Step 2 — Run the wizard** from any OpenClaw chat interface (TUI, Telegram, Discord):

    ```bash theme={null}
    /stratus setup
    ```

    The wizard will:

    1. ✅ Read `STRATUS_API_KEY` from your environment
    2. ✅ Back up your existing `~/.openclaw/openclaw.json`
    3. ✅ Add the Stratus provider to your OpenClaw config
    4. ✅ Create your auth profile in `~/.openclaw/agents/main/agent/auth-profiles.json`

    **Step 3 — Restart the gateway:**

    ```bash theme={null}
    openclaw gateway stop && openclaw gateway install
    ```

    **Step 4 — Verify:**

    ```bash theme={null}
    /stratus verify
    ```
  </Tab>

  <Tab title="Manual Script">
    ```bash theme={null}
    cd ~/.openclaw/plugins/stratus
    ./install.sh
    openclaw gateway restart
    ```

    The `install.sh` script will interactively prompt for your API key if `STRATUS_API_KEY` isn't set, and optionally add it to your shell config and macOS LaunchAgent.
  </Tab>

  <Tab title="OpenClaw Onboard">
    ```bash theme={null}
    openclaw onboard
    ```

    Select **Stratus** as a provider and enter your API key when prompted.
  </Tab>
</Tabs>

### What Gets Configured

Two files are updated during setup:

**`~/.openclaw/openclaw.json`** — registers Stratus as a model provider:

```json theme={null}
{
  "models": {
    "providers": {
      "stratus": {
        "baseUrl": "https://api.stratus.run/v1",
        "api": "openai-completions",
        "models": [
          {
            "id": "stratus-x1ac-base-claude-sonnet-4-5",
            "name": "Stratus X1AC Base (Claude 4.5 Sonnet)",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
```

At gateway start, the plugin fetches the live model list from `GET /v1/models` and overwrites this `models` array with the full current catalog.

**`~/.openclaw/agents/main/agent/auth-profiles.json`** — stores your API key:

```json theme={null}
{
  "version": 1,
  "profiles": {
    "stratus:default": {
      "type": "api_key",
      "provider": "stratus",
      "key": "stratus_sk_live_..."
    }
  },
  "lastGood": {
    "stratus": "stratus:default"
  }
}
```

<Warning>
  **These two files do not sync automatically.** Updating `openclaw.json` does NOT update the auth cache. The gateway uses the auth cache. This is the #1 cause of 401 errors — if you update your key, you must update both files or re-run `/stratus setup`.
</Warning>

***

## Slash Commands

| Command           | Description                                            |
| ----------------- | ------------------------------------------------------ |
| `/stratus`        | Show plugin help                                       |
| `/stratus setup`  | Run the configuration wizard                           |
| `/stratus verify` | Verify the plugin is correctly configured              |
| `/stratus models` | Fetch the live model list from the API and sync config |
| `/model stratus`  | Switch the active model to the Stratus alias           |

***

## Using Stratus in OpenClaw

### Switching Models

```bash theme={null}
# Use the alias
/model stratus

# Or specify the full model name
openclaw agent 'Plan the steps to deploy a web app' \
  --model stratus/stratus-x1ac-base-claude-sonnet-4-5
```

### Available Models

The plugin fetches the live model list at gateway start — run `/stratus models` to refresh. Models follow the format `stratus-x1ac-{size}-{llm}` across five size tiers: `small` · `base` · `large` · `xl` · `huge`.

**Native LLM backends:**

| Provider       | Models                                                                                         |
| -------------- | ---------------------------------------------------------------------------------------------- |
| **OpenAI**     | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `gpt-4`, `gpt-3.5-turbo`                               |
| **Claude 4.x** | `claude-sonnet-4-5`, `claude-opus-4-5`, `claude-haiku-4-5`, `claude-sonnet-4`, `claude-opus-4` |
| **Claude 4.x** | `claude-sonnet-4-5`, `claude-sonnet-4-20250514`, `claude-opus-4-20250514`                      |
| **Claude 3.x** | `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-opus`, `claude-3-sonnet`, `claude-3-haiku` |

**Recommended picks:**

| Use Case         | Model                                 |
| ---------------- | ------------------------------------- |
| Best overall     | `stratus-x1ac-base-claude-sonnet-4-5` |
| Fast & reliable  | `stratus-x1ac-base-gpt-4o`            |
| High performance | `stratus-x1ac-large-claude-opus-4-5`  |
| Dev/testing      | `stratus-x1ac-small-gpt-4o-mini`      |

See [Models](/docs/api-reference/models) for the complete list.

### Native Tools

The plugin ships two tools for agent workflows. OpenClaw's security model requires explicit allowlisting — nothing runs without your say-so.

<Tabs>
  <Tab title="stratus_embeddings">
    Generate 768-dimensional semantic state vectors for similarity search, memory indexing, and context clustering.

    ```bash theme={null}
    # Enable the tool
    openclaw config set agents.defaults.tools.allow '["stratus_embeddings"]'
    openclaw gateway restart

    # Use in an agent session
    openclaw agent --model stratus << 'EOF'
    Generate embeddings for: ['idle', 'working', 'completed', 'error']
    Which states are semantically similar?
    EOF
    ```

    **Tool schema:**

    ```typescript theme={null}
    {
      input: string | string[],           // Text(s) to embed
      model?: string,                     // Default: "stratus-x1ac-base"
      encoding_format?: 'float' | 'base64' // Default: "float"
    }
    ```

    Returns 768-dimensional float vectors per input.
  </Tab>

  <Tab title="stratus_rollout">
    Multi-step action sequence planning. Give it a goal and an optional starting state — returns a sequence of predicted actions with intermediate states.

    ```bash theme={null}
    # Enable the tool
    openclaw config set agents.defaults.tools.allow '["stratus_rollout"]'
    openclaw gateway restart

    # Use in an agent session
    openclaw agent --model stratus << 'EOF'
    I need to deploy a web application to production.
    Plan the deployment steps: build, test, staging, smoke tests, prod.
    EOF
    ```

    **Tool schema:**

    ```typescript theme={null}
    {
      goal: string,                       // Target state to achieve
      initial_state?: string,             // Starting state (optional)
      max_steps?: number,                 // Min 1, max 50, default 10
      return_intermediate?: boolean       // Default: true
    }
    ```
  </Tab>
</Tabs>

**Enable both tools:**

```bash theme={null}
openclaw config set agents.defaults.tools.allow \
  '["stratus_embeddings", "stratus_rollout"]'
openclaw gateway restart
```

***

## Advanced Configuration

### Custom Model Aliases

```json theme={null}
{
  "agents": {
    "defaults": {
      "models": {
        "stratus/stratus-x1ac-large-claude-opus-4-5": {
          "alias": "stratus-large"
        },
        "stratus/stratus-x1ac-small-gpt-4o-mini": {
          "alias": "stratus-fast"
        }
      }
    }
  }
}
```

<Warning>
  Adding entries to `agents.defaults.models` activates OpenClaw's model allowlist, which blocks all models not explicitly listed. Only add aliases here if you intend to restrict available models.
</Warning>

```bash theme={null}
/model stratus-large   # → X1AC Large + Claude Opus 4.5
/model stratus-fast    # → X1AC Small + GPT-4o-mini
```

### Environment Variables

```bash theme={null}
export STRATUS_API_KEY=stratus_sk_live_your_key_here
export STRATUS_BASE_URL=https://api.stratus.run/v1
```

### macOS LaunchAgent (Persistent Gateway)

```bash theme={null}
vim ~/Library/LaunchAgents/ai.openclaw.gateway.plist
# Add under EnvironmentVariables:
# <key>STRATUS_API_KEY</key>
# <string>stratus_sk_live_your_key_here</string>

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
```

***

## Troubleshooting

### "Stratus API key not configured"

Key not found in environment or config.

```bash theme={null}
export STRATUS_API_KEY=stratus_sk_live_...
openclaw gateway restart
# or re-run the wizard
/stratus setup
```

### "Invalid Stratus API key format"

Key doesn't start with `stratus_sk_`. Get a fresh key from [stratus.run/dashboard](https://stratus.run/dashboard?tab=overview) and re-run `/stratus setup`.

### 401 Unauthorized / Stale Auth Cache

The config file and the auth cache don't sync automatically. Update both:

```bash theme={null}
rm ~/.openclaw/agents/main/agent/auth-profiles.json
openclaw config patch '{"plugins":{"entries":{"stratus":{"apiKey":"stratus_sk_live_new_key"}}}}'
/stratus setup
openclaw gateway restart
```

### 429 Rate Limit

Wait and retry, or purchase additional credits from the [dashboard](https://stratus.run/dashboard).

### Silent Fallback to Anthropic (SIGBART Ignoring Stratus)

**Symptoms:** `/model stratus` appears to work but SIGBART announces "NOW RUNNING: Anthropic" and Stratus metadata is absent from responses.

**Cause:** The auth cache (`auth-profiles.json`) is stale. The gateway uses the cache, not the config file.

```bash theme={null}
# Nuclear fix
rm ~/.openclaw/agents/main/agent/auth-profiles.json
openclaw gateway stop
openclaw gateway install
/stratus setup
```

Then manually verify the API key works:

```bash theme={null}
curl https://api.stratus.run/v1/chat/completions \
  -H "Authorization: Bearer $STRATUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"stratus-x1ac-base-claude-sonnet-4-5","messages":[{"role":"user","content":"Test"}],"max_tokens":10}'
```

See the [full troubleshooting guide](https://github.com/formthefog/openclaw-stratus-x1-plugin/blob/main/TROUBLESHOOTING.md) for detailed debugging steps.

### "Tool not available"

```bash theme={null}
openclaw config set agents.defaults.tools.allow \
  '["stratus_embeddings", "stratus_rollout"]'
openclaw gateway restart
```

### "Model not found"

Use the Stratus-prefixed model name, not the raw provider name:

```bash theme={null}
# ❌
openclaw agent 'test' --model claude-sonnet-4-5

# ✅
openclaw agent 'test' --model stratus/stratus-x1ac-base-claude-sonnet-4-5

# ✅ alias
openclaw agent 'test' --model stratus
```

***

## Uninstall

```bash theme={null}
# Disable plugin, remove provider and model references
openclaw config patch '{"plugins":{"entries":{"stratus":{"enabled":false}},"installs":{"stratus":null}},"models":{"providers":{"stratus":null}},"agents":{"defaults":{"models":{"stratus/stratus-x1ac-base-claude-sonnet-4-5":null,"stratus/stratus-x1ac-base-gpt-4o":null}}}}'

# Switch back to default model
openclaw config patch '{"agents":{"defaults":{"model":{"primary":"anthropic/claude-sonnet-4-5"}}}}'

# Clear auth cache
rm ~/.openclaw/agents/main/agent/auth-profiles.json

# Restart
openclaw gateway restart
```

<Note>
  OpenClaw doesn't support plugin lifecycle hooks, so cleanup is always manual. After uninstall, `oc models` may still show Stratus models until the config patch above removes the aliases.
</Note>

See the [full uninstallation guide](https://github.com/formthefog/openclaw-stratus-x1-plugin/blob/main/README.md#uninstallation) for complete cleanup including plugin files and environment variables.

***

## Resources

* **Plugin repo:** [openclaw-stratus-x1-plugin](https://github.com/formthefog/openclaw-stratus-x1-plugin)
* **OpenClaw:** [openclaw.ai](https://openclaw.ai) · [docs.openclaw.ai](https://docs.openclaw.ai)
* **Troubleshooting:** [TROUBLESHOOTING.md](https://github.com/formthefog/openclaw-stratus-x1-plugin/blob/main/TROUBLESHOOTING.md)
* **Issues:** [GitHub Issues](https://github.com/formthefog/openclaw-stratus-x1-plugin/issues)
* **Model list:** [Available Models](/docs/api-reference/models)
* **API Reference:** [API Docs](/docs/api-reference/introduction)

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" color="#22d3ee" href="/docs/quickstart">
    New to Stratus? Start here.
  </Card>

  <Card title="Models" icon="cpu" color="#c084fc" href="/docs/api-reference/models">
    Browse all available models.
  </Card>

  <Card title="API Reference" icon="code" color="#34d399" href="/docs/api-reference/introduction">
    Full endpoint docs and parameters.
  </Card>
</CardGroup>