Skip to main content
Last updated on
Tags:
Options
Open in ChatGPTAsk ChatGPT about this pageOpen in ClaudeAsk Claude about this page

Getting Started

This guide walks you through integrating OpenBox with your OpenClaw agent. By the end, every tool call and LLM inference your agent makes will be evaluated against your OpenBox policies before execution.

Prerequisites​

  • Node.js 22+
  • OpenClaw installed and running
  • OpenBox account — sign up at openbox.ai to get your API key

You will need two values from your OpenBox account:

ValueFormatWhere to find it
OpenBox URLhttps://core.openbox.aiYour OpenBox Core instance URL
API Keyobx_live_* or obx_test_*Settings > API Keys in the OpenBox dashboard

Installation​

1. Build the plugin​

cd /path/to/openbox-openclaw-plugin
npm install
npm run build

2. Install the plugin into OpenClaw​

openclaw plugins install .

3. Configure the plugin​

Add your OpenBox credentials to your .env file in OpenClaw:

OPENBOX_URL=https://core.openbox.ai
OPENBOX_API_KEY=obx_live_your_key_here
OPENAI_API_KEY=sk-your_openai_key_here  # your existing LLM API key in OpenClaw

Then add the plugin config to your openclaw.json:

{
  "plugins": {
    "entries": {
      "openbox": {
        "enabled": true,
        "config": {
          "openboxUrl": "${OPENBOX_URL}",
          "openboxApiKey": "${OPENBOX_API_KEY}",
          "llmBaseUrl": "https://api.openai.com/v1",
          "llmApiKey": "${OPENAI_API_KEY}",
          "gatewayPort": 18919
        }
      }
    }
  }
}

You can also configure these values from the OpenClaw web control UI instead of editing files directly.

4. Point your LLM provider to the gateway​

To enable LLM guardrails (PII detection, content policy), route your model provider through the OpenBox gateway. In your openclaw.json, update the model provider's baseUrl:

{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "http://127.0.0.1:18919/v1",
        "apiKey": "${OPENAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          {
            "id": "openai/gpt-5-mini",
            "name": "openai/gpt-5-mini"
          }
        ]
      }
    }
  }
}

The model choice is flexible — any OpenAI-compatible model and provider will work.

Important: If you skip this step, tool governance still works but LLM guardrails (PII redaction, content filtering) will not be applied to LLM requests.

5. Restart the gateway​

openclaw gateway restart

The gateway must be restarted after any plugin or configuration change for changes to take effect.

Verify your setup​

See Verifying Your Setup for step-by-step instructions to confirm the plugin is loaded and governance is active.

Next steps​