How-To Hook Up OpenClaw to Crusoe Managed Inference

Introduction

OpenClaw connects to any OpenAI-compatible API through a custom provider entry in its config file. That makes Crusoe Managed Inference a drop-in target: you point OpenClaw's baseUrl at Crusoe's /v1 endpoint, declare the models you want, and OpenClaw's agent runs route to Crusoe instead of a hosted provider.

There are two execution paths and they behave differently, which matters for how you verify the setup. A one-shot local command resolves and calls a single provider directly. The Gateway — a persistent background process — runs full agent turns and is what channels, scheduled tasks, and other integrations actually use. Only the Gateway path exercises the fallback chain, so a local probe passing does not mean your fallback works.

This article covers generating a Crusoe API key, wiring it into OpenClaw's config, standing up the Gateway, and verifying both paths.

⚠️ Warning: OpenClaw stores the API key in plaintext in ~/.openclaw/openclaw.json. Treat that file as a secret — restrict its permissions, and do not commit it or include it in a support bundle.

Prerequisites

• OpenClaw Installed (npm install -g openclaw, or per the Official Install Guide)
• Crusoe Cloud Account With Access to Managed Inference
• Permission to Create Intelligence API Keys in the Crusoe Console

Instructions

Step 1: Generate a Crusoe API Key

1. Sign in to the Crusoe Cloud console.
2. Open the Security tab, then the Intelligence API Keys tab.
3. Click Create Intelligence API Key. Optionally set an alias and expiration date.
4. Click Create and save the key.

ℹ️ Note: The key is shown only once. Copy it before closing the dialog — if you lose it you will need to create a new key.

Step 2: Sanity-Check the Endpoint

Confirm the key works before configuring OpenClaw. Replace YOUR_CRUSOE_API_KEY with your actual key:

curl https://api.inference.crusoecloud.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_CRUSOE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "moonshotai/Kimi-K2.6", "messages": [{"role": "user", "content": "hello"}]}'

Replace the model ID with whichever model you plan to use. Check the current catalog in the Crusoe console for available IDs.

Step 3: Add Crusoe as a Custom Provider in OpenClaw

OpenClaw reads its configuration from ~/.openclaw/openclaw.json by default, in JSON5 format. If this file does not exist yet, running openclaw onboard creates it, or you can create it manually.

Open the file in a text editor, or use openclaw config set to write it through the CLI — the CLI route is recommended, since those writes are schema-validated. Add a providers entry under models, pointing baseUrl at Crusoe's OpenAI-compatible endpoint:

{
  models: {
    mode: "merge",
    providers: {
      crusoe: {
        baseUrl: "https://api.inference.crusoecloud.com/v1",
        apiKey: "YOUR_CRUSOE_API_KEY",
        api: "openai-completions",
        models: [
          {
            id: "moonshotai/Kimi-K2.6",
            name: "Kimi K2.6 (Crusoe)",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Field Reference

Step 4: Set Crusoe as the Primary Model

Open ~/.openclaw/openclaw.json and add or merge into the agents.defaults section:

{
 // ...your models block from Step 3...
 agents: {
   defaults: {
     model: { primary: "crusoe/moonshotai/Kimi-K2.6" },
     models: {
       "crusoe/moonshotai/Kimi-K2.6": { alias: "Crusoe" },
     },
   },
 },
}

The model reference format is provider/model-id, matching the provider key set in Step 3.

Step 5: Hosted Fallback (Optional)

To keep a hosted model as a fallback if Crusoe is unreachable:

{
 // ...your models block from Step 3...
 agents: {
   defaults: {
     model: {
       primary: "crusoe/moonshotai/Kimi-K2.6",
       fallbacks: ["anthropic/claude-sonnet-4-6"],
     },
   },
 },
}

Step 6: Quick Provider Check

Run a lightweight check that bypasses agent tooling entirely, useful for confirming the provider config and API key are wired correctly before testing full agent behavior:

openclaw infer model run --local --model crusoe/moonshotai/Kimi-K2.6 --prompt "Reply with exactly: pong" --json

If this returns pong, the provider and model config from Steps 3 and 4 are correct.

ℹ️ Note: This command is a direct one-shot provider probe. It does not start a chat-agent turn and does not exercise the fallback chain from Step 5. Use it only to isolate provider or authentication issues. To test the actual agent path, including fallback, continue to Step 8.

Step 7: Set Up the Gateway (Recommended for Ongoing Use)

Real usage — channels, scheduled tasks, and other integrations — runs through a persistent Gateway process rather than one-shot local commands. Set this up once so Crusoe is available the same way in production as in testing.

7a. Set Gateway Mode

The Gateway refuses to install or start unless gateway.mode is explicitly set to local:

openclaw config set gateway.mode "local"

7b. Set Gateway Authentication

Auth is required by default, even on loopback. Set a token:

openclaw config set gateway.auth.mode "token"
openclaw config set gateway.auth.token "REPLACE_WITH_A_LONG_RANDOM_SECRET"

Generate a genuinely random secret rather than a simple string, since this token grants full operator access to the Gateway.

⚠️ Warning: Passing the token as a command-line argument writes it into your shell history, and it is visible in the process list while the command runs. Prefer a shell that skips history for space-prefixed commands, or clear the relevant history entries afterwards.

7c. Install the Gateway as a Persistent Service

openclaw gateway install

This registers a LaunchAgent on macOS (or a systemd user unit on Linux/WSL2) so the Gateway starts automatically and keeps running in the background.

7d. Start and Verify the Gateway

openclaw gateway start
openclaw gateway status

Confirm the output shows:

• Service: LaunchAgent (loaded)
• Runtime: running (with a pid)
• Connectivity probe: ok

ℹ️ Note: The status command may show Capability: connected-no-operator-scope. This is a known cosmetic issue in the status probe path specifically and does not affect actual agent runs, chat, or fallback behavior.

To confirm the token itself has full access:

openclaw gateway call status --token REPLACE_WITH_A_LONG_RANDOM_SECRET

If this returns full JSON, the token is working correctly and the scope warning in openclaw gateway status can be ignored.

Step 8: Verify Through the Gateway

With the Gateway installed and running, verify the full agent path. This is the path that matters for real usage, since channels, scheduled tasks, and other integrations all route through the running Gateway rather than a one-shot local command:

openclaw agent --session-key "agent:main:crusoe-verify-01" --message "Reply with exactly: pong" --json

Check the response for:

"agentMeta": { "provider": "crusoe", "model": "moonshotai/Kimi-K2.6" }

and

"executionTrace": { "winnerProvider": "crusoe", "fallbackUsed": false }

This confirms the primary model resolves and responds correctly through the live Gateway.

Testing Locally Instead

If you do not want to install a persistent Gateway service — for a quick one-off check, or in a CI environment — add the --local flag to run the same command through OpenClaw's embedded runtime, without needing a running Gateway:

openclaw agent --session-key "agent:main:crusoe-verify-01" --message "Reply with exactly: pong" --local --json

This exercises a full agent turn, including fallback behavior, the same way the Gateway path does, just without a persistent background service. It is a good option for quick verification, but does not represent how the integration behaves under actual channel or scheduled-task usage.

Step 9: Test Fallback Behavior (Optional but Recommended)

Having a fallback configured in Step 5 does not by itself confirm it works. Test it by temporarily breaking the primary provider and confirming the agent still responds via the fallback:

openclaw config set models.providers.crusoe.apiKey "invalid-test-key"
openclaw agent --session-key "agent:main:crusoe-fallback-test" --message "Reply with exactly: pong" --json
openclaw config set models.providers.crusoe.apiKey "YOUR_CRUSOE_API_KEY"

⚠️ Warning: The first command overwrites your working API key. Have the real key to hand before you start — if the middle command hangs or you interrupt the sequence, the third command never runs and the provider stays broken until you restore it manually.

On the middle command, check the response for:

"executionTrace": {
  "winnerProvider": "anthropic",
  "fallbackUsed": true,
  "attempts": [
    { "provider": "crusoe", "result": "..." },
    { "provider": "anthropic", "result": "success" }
  ]
}

If fallbackUsed is true and the winning provider is your configured fallback, the failover chain is confirmed working. Restore the real API key immediately after this test.

ℹ️ Note: openclaw infer model run --local (Step 6) does not exercise this fallback path at all, since it resolves and calls a single provider directly rather than running a full agent turn. Use openclaw agent, with or without --local, to test fallback.

Example

A team running a coding agent in CI wants inference to stay on Crusoe for cost and data-residency reasons, but cannot afford a pipeline failure if the endpoint is briefly unreachable.

They add Crusoe as a provider with mode: "merge" so their existing Anthropic credentials stay loaded, set crusoe/moonshotai/Kimi-K2.6 as the primary, and list anthropic/claude-sonnet-4-6 as a fallback. Because CI runners are ephemeral, they skip the Gateway install and call openclaw agent with --local, which still runs a full agent turn and still honours the fallback chain.

Before rolling it out they run Step 9 once on a developer machine, confirm "fallbackUsed": true with anthropic as the winning provider, and restore the real key. Crusoe now serves every run, and an outage degrades to the hosted model instead of failing the build.

Additional Resources

• Local Models — OpenClaw Docs
• Getting Started with Managed Inference — Crusoe Cloud Docs
• How-To Use Your Crusoe Console Managed Inference API Keys to Access Your Model (BYOM)
• How-To Resolve '403 Forbidden' Returned by Crusoe Managed Inference
• How-To Fix 429 RateLimitError When Interacting With Crusoe Managed Inference Service
• How-To: Use Crusoe Managed Inference with OpenCode