OpenClaw Integration Guide

Note: OpenClaw is an open-source, self-hosted AI assistant platform. It is useful for developers who want control over messaging channels, agent capabilities, and data ownership.

If you want OpenClaw to access models through Nbility, use the configuration below.

What Is OpenClaw?

Its core features include:

• Connects to Feishu, Discord, Slack, Teams, and other channels
• Supports voice interaction and a canvas-style interface
• Uses self-hosting, so data and context stay in your own environment
• Supports long-running tasks, scheduled tasks, multi-agent collaboration, and tool calls

Related resources:

• Website: https://openclaw.ai
• Docs: https://docs.openclaw.ai
• GitHub: https://github.com/openclaw/openclaw

Prerequisites

Before starting, prepare:

• OpenClaw is installed
• You have an active Nbility Token

You can get the token from /console/token.

Installation

If OpenClaw is not installed yet, choose one method:

curl -fsSL https://openclaw.ai/install.sh | bash

npm install -g openclaw@latest

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm run build
pnpm run openclaw onboard

Note: npm and git installation usually require Node.js 22 or later. The one-line installer handles more environment details for you.

After installation, run the onboarding wizard once:

openclaw onboard

Configuration File Location

OpenClaw uses ~/.openclaw/openclaw.json as the main configuration file by default.

Common paths:

• macOS: /Users/your-username/.openclaw/openclaw.json
• Linux: /home/your-username/.openclaw/openclaw.json
• Windows: C:\\Users\\your-username\\.openclaw\\openclaw.json

If the file does not exist, create it manually:

mkdir -p ~/.openclaw
touch ~/.openclaw/openclaw.json

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openclaw"
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.openclaw\openclaw.json"

Tip: If you have already run openclaw onboard, you usually do not need to create the file again. Edit the existing configuration instead.

Basic Structure

Configuration is usually split into models and agents:

{
  "models": {
    "mode": "merge",
    "providers": {}
  },
  "agents": {
    "defaults": {}
  }
}

Key fields:

• models.providers: defines model providers, credentials, and model lists
• models.mode: keep it as "merge" to avoid replacing all built-in configuration
• agents.defaults.model.primary: specifies the default model, usually in the form provider/model-id
• api: determines which protocol to use

Configure Claude Models

To use Claude models through Nbility, use a configuration like this:

{
  "models": {
    "mode": "merge",
    "providers": {
      "nbility-anthropic": {
        "baseUrl": "https://api.nbility.dev",
        "apiKey": "sk-your-NBility-Token",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": false
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "nbility-anthropic/claude-opus-4-6"
      }
    }
  }
}

Important: When using the Anthropic protocol, set baseUrl to https://api.nbility.dev without /v1; otherwise the SDK may duplicate the path.

Configure GPT Models

For OpenAI-series models, use openai-responses:

{
  "models": {
    "mode": "merge",
    "providers": {
      "nbility-openai": {
        "baseUrl": "https://api.nbility.dev/v1",
        "apiKey": "sk-your-NBility-Token",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5",
            "name": "GPT-5",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 16384,
            "reasoning": true
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "nbility-openai/gpt-5"
      }
    }
  }
}

Tip: OpenAI protocol configuration is different from Claude configuration. Here you should keep https://api.nbility.dev/v1.

Use Claude and GPT Together

If you want multiple providers and fallback models, use a structure like this:

{
  "models": {
    "mode": "merge",
    "providers": {
      "nbility-anthropic": {
        "baseUrl": "https://api.nbility.dev",
        "apiKey": "sk-your-NBility-Token",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": false
          },
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": false
          }
        ]
      },
      "nbility-openai": {
        "baseUrl": "https://api.nbility.dev/v1",
        "apiKey": "sk-your-NBility-Token",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5",
            "name": "GPT-5",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 16384,
            "reasoning": true
          },
          {
            "id": "gpt-5-codex",
            "name": "GPT-5 Codex",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 16384,
            "reasoning": true
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "nbility-anthropic/claude-opus-4-6",
        "fallbacks": [
          "nbility-anthropic/claude-sonnet-4-5-20250929",
          "nbility-openai/gpt-5"
        ]
      }
    }
  }
}

If you only want to switch the default model, usually you only need to change model.primary.

Field Reference

Verify Configuration

After configuration, run:

openclaw

If everything works, check model status:

openclaw models list

openclaw models status

openclaw doctor

Start the Service

To start the service:

openclaw start

If you need to restart the gateway:

openclaw gateway restart

Common Issues

Direct Requests Work, but OpenClaw Returns 403

This is usually not a key issue. Some CDNs or WAFs may block the User-Agent sent by the underlying SDK.

Add a headers field to the provider to override the UA:

{
  "nbility-anthropic": {
    "baseUrl": "https://api.nbility.dev",
    "apiKey": "your-api-key",
    "api": "anthropic-messages",
    "headers": {
      "User-Agent": "Mozilla/5.0"
    },
    "models": []
  }
}

Why Should Anthropic baseUrl Not Include /v1?

The Anthropic SDK appends the path automatically. If you manually include /v1, the final request may become /v1/v1/messages, causing a 404.

What Values Are Valid for api?

OpenClaw validates this field strictly. Common values include:

• anthropic-messages
• openai-completions
• openai-responses

When using Claude through Nbility, choose anthropic-messages. For GPT, choose openai-responses.

Why Is openai-completions Not Recommended?

In some cases the request succeeds but the interface shows an empty response. If you are using GPT models, openai-responses is usually more reliable.

Configuration Changes Did Not Take Effect

OpenClaw may also read another provider configuration location:

~/.openclaw/openclaw.json
~/.openclaw/agents/main/agent/models.json

If you edit only one location, the result may not appear immediately. After editing, run:

openclaw models status

Or restart directly:

openclaw gateway restart

How Do I Troubleshoot JSON Errors?

Common issues include:

• Extra trailing commas
• Missing commas between sibling fields
• Single quotes or smart quotes
• Unbalanced braces or brackets

Use this command to check formatting quickly:

python3 -m json.tool ~/.openclaw/openclaw.json

What Does reasoning Mean?

This field controls whether a model uses a stronger reasoning mode. Enabling it usually increases reasoning work and token usage. If you are not sure whether the model supports it, set it to false first.

Troubleshooting Commands Worth Remembering

Tip: During troubleshooting, first confirm that the Nbility API itself is available, then compare the actual path, protocol, and headers sent by OpenClaw.