Stratus X1-AC Plugin for OpenClaw

Integrate Stratus V3 (X1-AC), a state-of-the-art action-conditioned JEPA (Joint-Embedding Predictive Architecture), into OpenClaw for autonomous agent planning and semantic state understanding.

Features

• Zero-Config: Works out of the box with Formation pooled keys — no API key needed
• 2050+ Models: Dynamic discovery via OpenRouter — OpenAI, Anthropic, Google, and more
• Model Provider: Use Stratus models for agent conversations with predictive planning
• Embeddings Tool: Generate 768-dimensional semantic state embeddings
• Rollout Tool: Multi-step task planning via Policy Head v3 (94.4% accuracy)
• BYOK Support: Bring your own provider keys (openai_key, anthropic_key, gemini_key) for zero-markup usage
• Opt-in Tools: Tools are optional and require explicit allowlisting

See SECURITY.md for a full accounting of credentials accessed, network calls made, and files written.

Support

• Documentation: https://stratus.run/docs
• Issues: https://github.com/formthefog/openclaw-stratus-x1-plugin/issues
• API Key: https://stratus.run

Installation

Quick Start (2 Steps) ✨

Note: This plugin does NOT have an automatic postinstall script. You must run setup manually.

# 1. Install the plugin
openclaw plugins install @formthefog/stratus

# 2. Run setup (in any OpenClaw chat interface)
/stratus setup

# 3. Verify everything works
/stratus verify

That's it! No API key required — Formation pooled keys give you instant access to all 2050+ models.

The /stratus setup command handles:

• ✅ Zero-config auth via Formation pool (or BYOK if you have a key)
• ✅ OpenClaw config updates
• ✅ Auth profile creation
• ✅ Dynamic model registration
• ✅ Gateway restart prompt

No manual config editing required! 🧈

Optional — BYOK (no markup): Set STRATUS_API_KEY to bypass the Formation pool:

export STRATUS_API_KEY=stratus_sk_your_key_here

Then re-run /stratus setup.

Tip: Once installed, you can also access Stratus models with /model stratus in chat.

Available Commands

Use these slash commands in any OpenClaw chat (TUI, Telegram, Discord, etc.):

| Command | Description | |---------|-------------| | /stratus | Show help | | /stratus setup | Interactive configuration wizard | | /stratus verify | Verify plugin is configured correctly | | /stratus models | List all available models (live from API) |

What /stratus setup Does

The interactive setup command will:

1. ✅ Detect auth mode (BYOK if STRATUS_API_KEY is set, Formation pool otherwise)
2. ✅ Update OpenClaw configuration
3. ✅ Configure authentication profiles
4. ✅ Dynamically register all available models from the API
5. ✅ Report auth mode and markup status

Testing Your Installation

After setup, verify everything works:

# In chat:
/stratus verify

# Then try the model:
/model stratus
Hello from Stratus!

Alternative Installation Methods

Via OpenClaw (Recommended)

openclaw plugins install @formthefog/stratus

Via npm (for development or testing)

npm install -g @formthefog/stratus

Note: When installing via npm, you'll still need to manually configure OpenClaw. The openclaw plugins install method is recommended as it handles setup automatically.

From OpenClaw Monorepo

If you're developing in the OpenClaw monorepo, the plugin is already available:

cd /path/to/openclaw
pnpm install

Configuration

1. Get Your API Key

Sign up at stratus.run to get your API key (format: stratus_sk_...).

2. Set Environment Variable

export STRATUS_API_KEY=stratus_sk_live_your_key_here

Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export STRATUS_API_KEY=stratus_sk_live_your_key_here' >> ~/.zshrc

3. Configure OpenClaw

Run the onboarding wizard:

openclaw onboard

Select "Stratus" as a provider and enter your API key when prompted.

Manual Configuration (alternative):

Edit ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "stratus": {
        "enabled": true,
        "config": {
          "apiKey": "${STRATUS_API_KEY}",
          "baseUrl": "https://api.stratus.run",
          "inlineKeys": {
            "openai_key": "${OPENAI_API_KEY}",
            "anthropic_key": "${ANTHROPIC_API_KEY}",
            "gemini_key": "${GOOGLE_API_KEY}"
          },
          "provider": {
            "enabled": true,
            "defaultModel": "stratus-x1ac-base-claude-sonnet-4-5"
          },
          "tools": {
            "embeddings": { "enabled": true },
            "rollout": { "enabled": true }
          }
        }
      }
    }
  }
}

Note: All keys are optional. Without any keys, Formation pooled keys are used automatically (25% markup). Inline provider keys (openai_key, anthropic_key, gemini_key) let you BYOK for specific providers while using the pool for others.

Important: OpenClaw's plugin config schema requires plugin-specific settings to be nested under a config key within plugins.entries.<id>. Only enabled and config are valid top-level keys per entry. Placing keys like apiKey or tools at the top level will cause a config validation error and prevent the gateway from starting.

## Usage

### 1. Use Stratus as a Model Provider

Use Stratus models for agent conversations:

```bash
# Use Claude Sonnet 4.5 backend (recommended)
openclaw agent --model stratus/stratus-x1ac-base-claude-sonnet-4-5 \
  "Explain action-conditioned state prediction"

# Use GPT-4o backend
openclaw agent --model stratus/stratus-x1ac-base-gpt-4o \
  "Help me plan a complex task"

# Use smaller model for faster responses
openclaw agent --model stratus/stratus-x1ac-small-claude-haiku-4-5 \
  "Quick question: what is JEPA?"

Available Models: Dynamic (2050+ models)

Models are fetched live from the Stratus API on startup via OpenRouter dynamic discovery and refreshed automatically. Run /stratus models to see the current full list. The plugin supports all models returned by the API.

Model Format: stratus-x1ac-{size}-{llm}

Sizes: small, base, large, xl, huge

OpenAI LLMs:

• gpt-4o - GPT-4 Optimized (latest)
• gpt-4o-mini - Smaller, faster GPT-4o
• gpt-4-turbo - GPT-4 Turbo
• gpt-4 - GPT-4 base
• gpt-3.5-turbo - GPT-3.5 Turbo

Anthropic LLMs (Claude 4.x):

• claude-sonnet-4-6 - Claude 4.6 Sonnet (latest)
• claude-opus-4-6 - Claude 4.6 Opus (latest, high performance)
• claude-sonnet-4-5 - Claude 4.5 Sonnet (recommended)
• claude-opus-4-5 - Claude 4.5 Opus
• claude-haiku-4-5 - Claude 4.5 Haiku (fast)
• claude-opus-4-1 - Claude 4.1 Opus
• claude-sonnet-4 - Claude 4 Sonnet
• claude-opus-4 - Claude 4 Opus

Anthropic LLMs (Claude 3.x - Legacy):

• claude-3-7-sonnet, claude-3-5-sonnet, claude-3-opus, claude-3-sonnet, claude-3-haiku

Google LLMs:

• gemini-2.0-flash - Gemini 2.0 Flash (1M context)
• gemini-1.5-pro - Gemini 1.5 Pro (2M context)
• gemini-1.5-flash - Gemini 1.5 Flash (1M context)
• gemini-pro - Gemini Pro

Examples:

• stratus/stratus-x1ac-base-claude-sonnet-4-5 (recommended)
• stratus/stratus-x1ac-base-claude-sonnet-4-6 (latest Claude)
• stratus/stratus-x1ac-base-gpt-4o
• stratus/stratus-x1ac-base-gemini-2.0-flash (1M context window)
• stratus/stratus-x1ac-large-claude-opus-4-6 (high performance)
• stratus/stratus-x1ac-small-gpt-4o-mini (development/testing)

2. Use Stratus Tools

Enable Tools (Allowlist)

Tools are opt-in for security. Enable them in your config:

# Enable both tools
openclaw config set agents.defaults.tools.allow '["stratus_embeddings", "stratus_rollout"]'

# Or enable only specific tools
openclaw config set agents.defaults.tools.allow '["stratus_rollout"]'

Embeddings Tool

Generate semantic embeddings for state understanding:

openclaw agent "Generate embeddings for these states: ['idle', 'working', 'completed']"

The agent will invoke:

{
  "tool": "stratus_embeddings",
  "input": ["idle", "working", "completed"]
}

Use Cases:

• Semantic search over states
• State similarity comparison
• Memory indexing
• Context clustering

Rollout Tool

Plan multi-step action sequences:

openclaw agent "Plan the steps to book a hotel room"

The agent will invoke:

{
  "tool": "stratus_rollout",
  "goal": "hotel room booked",
  "max_steps": 10
}

Use Cases:

• Task decomposition
• Action planning
• Goal-oriented reasoning
• Multi-step workflows

3. Combined Usage

Use Stratus models WITH tools for maximum capability:

Config:

{
  "agent": {
    "model": "stratus/stratus-x1ac-base-claude-sonnet-4-5"
  },
  "agents": {
    "defaults": {
      "tools": {
        "allow": ["stratus_embeddings", "stratus_rollout"]
      }
    }
  }
}

Example Conversation:

openclaw agent
> I need to plan a trip to Paris. First, analyze the semantic similarity
> of these activities: ['visit Eiffel Tower', 'Seine river cruise', 'Louvre museum'].
> Then, create a step-by-step plan to book everything.

# Agent uses:
# 1. stratus_embeddings() to analyze activity similarity
# 2. stratus_rollout() to generate booking plan
# 3. Stratus X1AC model for reasoning and response

Tool Reference

stratus_embeddings

Generate 768-dimensional semantic embeddings.

Parameters:

• input (string | string[]): Text(s) to embed
• model (string, optional): Model to use (default: stratus-x1ac-base)
• encoding_format (string, optional): float or base64 (default: float)

Returns:

{
  "content": [{ "type": "text", "text": "Generated 3 embeddings (768 dimensions each)" }],
  "details": {
    "data": [
      { "embedding": [0.1, 0.2, ...], "index": 0 },
      ...
    ],
    "usage": { "prompt_tokens": 10, "total_tokens": 10 }
  }
}

stratus_rollout

Multi-step rollout planning.

Parameters:

• goal (string): Target state to achieve
• initial_state (string, optional): Starting state
• max_steps (number, optional): Max steps (default: 10, max: 50)
• return_intermediate (boolean, optional): Return intermediate states (default: true)

Returns:

{
  "content": [{
    "type": "text",
    "text": "Successfully planned 5 steps\nGoal: book hotel\n\nSteps:\n1. Search hotels\n2. ..."
  }],
  "details": {
    "goal": "book hotel",
    "steps": [
      { "action": "search_hotels", "description": "Search for hotels" },
      ...
    ],
    "success": true
  }
}

Security

API Key Protection

• Storage: Store in STRATUS_API_KEY environment variable (not in config files)
• Validation: Automatically validates stratus_sk_* format
• Redaction: Keys are redacted in logs ([REDACTED])

Tool Access Control

Tools are opt-in only:

• Registered with { optional: true }
• Must be explicitly added to agents.defaults.tools.allow
• Not available unless allowlisted

Input Validation

• All tool parameters validated via TypeBox schemas
• API responses validated before processing
• Error handling prevents information leakage

Troubleshooting

Quick Fixes

"Invalid Stratus API key format"

Solution: If you set STRATUS_API_KEY, verify it starts with stratus_sk_. Or remove it entirely to use Formation pool (zero-config).

"Tool not available"

Solution:

openclaw config set agents.defaults.tools.allow '["stratus_embeddings", "stratus_rollout"]'

"Stratus API error (401)"

Solution: Get a new API key from stratus.run and update both config files:

• ~/.openclaw/openclaw.json
• ~/.openclaw/agents/main/agent/auth-profiles.json

Then restart: openclaw gateway restart

Silent Fallback to Anthropic

If SIGBART ignores your Stratus config, see TROUBLESHOOTING.md for the auth cache fix.

Full Troubleshooting Guide

For detailed debugging steps and solutions to common issues, see TROUBLESHOOTING.md.

Architecture

Hybrid Plugin Design

Stratus has dual capabilities:

1. Provider (standard LLM API):

   • /v1/chat/completions
   • /v1/messages
   • Registered via api.registerProvider()

2. Tools (specialized capabilities):

   • /v1/embeddings → stratus_embeddings
   • /v1/rollout → stratus_rollout
   • Registered via api.registerTool()

This follows UNIX philosophy: clean separation, composable interfaces, transparent behavior.

Configuration Schema

OpenClaw plugin entries use { enabled, config } at the top level. The config object holds all plugin-specific settings:

// What OpenClaw stores in plugins.entries.stratus
interface PluginEntryConfig {
  enabled?: boolean;
  config?: StratusPluginConfig;
}

// Plugin-specific config (nested under "config" key)
interface StratusPluginConfig {
  apiKey?: string;   // API key (optional — Formation pool used as fallback)
  baseUrl?: string;  // API base URL
  inlineKeys?: {     // BYOK keys passed per-request
    openai_key?: string;
    anthropic_key?: string;
    gemini_key?: string;  // Also sent as X-Google-Key header
  };
  provider?: {
    enabled?: boolean;     // Enable provider registration
    defaultModel?: string; // Default model
  };
  tools?: {
    embeddings?: { enabled?: boolean };
    rollout?: { enabled?: boolean };
  };
}

Examples

Semantic State Search

openclaw agent --model stratus/stratus-x1ac-base-claude-sonnet-4-5 << 'EOF'
I have these system states: ['initializing', 'loading', 'ready', 'processing', 'error'].
Use embeddings to find which states are semantically similar.
EOF

Task Planning Workflow

openclaw agent --model stratus/stratus-x1ac-base-claude-sonnet-4-5 << 'EOF'
I need to deploy a web application. Use rollout planning to generate the steps,
considering: code push, build, test, deploy, verify.
EOF

Combined Planning + Embeddings

openclaw agent --model stratus/stratus-x1ac-base-claude-sonnet-4-5 << 'EOF'
I want to organize a conference. First, generate embeddings for these tasks:
['venue booking', 'speaker invitations', 'catering', 'registration system'].
Then use rollout to plan the optimal sequence.
EOF

Development

File Structure

extensions/stratus/
├── index.ts              # Plugin entry point
├── package.json          # Package metadata
├── tsconfig.json         # TypeScript config
├── README.md             # This file
└── src/
    ├── client.ts         # Stratus API client
    ├── config.ts         # Config schema
    └── types.ts          # TypeScript types

Adding New Endpoints

To add a new Stratus endpoint:

1. Add types to src/types.ts
2. Add client method to src/client.ts
3. Register tool in index.ts
4. Update README with usage

Uninstallation

To completely remove the Stratus plugin from OpenClaw:

Quick Uninstall (Automated)

# 1. Disable the plugin via config
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}}}}'

# 2. If your primary model was Stratus, switch back to Anthropic:
openclaw config patch '{"agents":{"defaults":{"model":{"primary":"anthropic/claude-sonnet-4-5"}}}}'

# 3. Restart gateway
openclaw gateway restart

# 4. (Optional) Clean up auth cache
rm ~/.openclaw/agents/main/agent/auth-profiles.json
openclaw gateway restart

Manual Uninstall (Step-by-Step)

1. Disable plugin in config:

Edit ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "stratus": {
        "enabled": false
      }
    }
  }
}

2. Remove provider and model references:

{
  "models": {
    "providers": {
      // Remove entire "stratus" section
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-5"  // Switch back to default
      },
      "models": {
        // Remove stratus model aliases
      }
    }
  }
}

3. Clean auth cache:

OpenClaw caches API keys in ~/.openclaw/agents/main/agent/auth-profiles.json. Remove the Stratus entry:

{
  "profiles": {
    "stratus:default": null  // Remove this entire entry
  },
  "lastGood": {
    "stratus": null  // Remove this
  }
}

Or delete the entire file and restart (OpenClaw will regenerate it):

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

4. Restart gateway:

openclaw gateway restart

5. (Optional) Remove plugin files:

If installed via ClawHub:

rm -rf ~/.openclaw/plugins/stratus

If installed from local path, the plugin files remain at their original location. Update your config to remove the path reference:

{
  "plugins": {
    "load": {
      "paths": [
        // Remove "/path/to/openclaw-stratus-x1-plugin"
      ]
    }
  }
}

6. (Optional) Remove environment variable:

If you added STRATUS_API_KEY to your shell profile:

# Edit ~/.zshrc or ~/.bashrc and remove:
# export STRATUS_API_KEY=stratus_sk_...

Verification

After uninstall, verify Stratus is gone:

# Should not show Stratus models
openclaw agent --help | grep stratus

# Should not show Stratus tools
openclaw tools list | grep stratus

Known Issues

Issue: After uninstall, oc models still shows Stratus

Cause: Model aliases are cached separately from provider config.

Fix: Use the config patch command above or manually remove from agents.defaults.models.

Note: OpenClaw doesn't currently support plugin lifecycle hooks (postuninstall), so cleanup must be done manually. We're tracking this as a feature request: openclaw#XXXX.

Contributing

Contributions welcome! Please:

1. Follow existing code style
2. Add tests for new features
3. Update documentation
4. Ensure TypeScript types are complete

License

MIT

Links

• Stratus Website
• OpenClaw Documentation
• API Documentation
• GitHub Issues

Support

• Bug reports: GitHub Issues
• Feature requests: GitHub Discussions
• Stratus API issues: [email protected]