Using OpenClaw with SoAI

OpenClaw can use SoAI through a custom OpenAI-compatible model provider and can connect separately to its MCP server.

Prepare the server

  1. In the SoAI WebUI, select the Settings button at the right of the header, choose Settings, and open OpenAI. This tab appears only to an Administrator with API key management (OPENAI_API_ADMIN). Select Create key and copy the key when it is shown. Open Models and copy the exact model ID; this requires Model read access (MODEL_READ).
  2. For MCP, select the Settings button at the right of the header, choose Settings, then open MCP > MCP tokens. The MCP tab appears only to an Administrator with MCP administration (MCP_ADMIN), and creating a token also requires MCP usage (MCP_USE). Changing the MCP runtime, server mode, or exposed capabilities under MCP configuration also requires Configuration changes (CONFIG_PATCH).

Connect OpenClaw to the SoAI model API in Control UI

  1. Start the OpenClaw Gateway and open its dashboard.
  2. Open Settings > Model Providers and add a custom provider.
  3. Set its base URL to https://SOAI_HOST:5090/v1, API protocol to OpenAI Completions, and enter the SoAI API key in the API key field.
  4. Add an exact model ID and its real context window, output limit, modalities, cost values, and verified compatibility capabilities.
  5. Use Test connection. Then select the provider/model in Default models and save.

Choose OpenAI Responses only for a model that advertises Responses support. OpenClaw sends model requests to the configured base URL, so use only a trusted server address.

Connect OpenClaw to SoAI MCP in Control UI

  1. Open Settings > MCP, also available at /settings/mcp.
  2. Use the scoped MCP editor to add a remote HTTP server with https://SOAI_HOST:5090/mcp and the bearer Authorization header.
  3. Select Save & Publish so the running Gateway applies the change, then use openclaw mcp doctor --probe for a live connection check.
  4. In Chat, select + > Connectors to enable soai for the current session. Apply narrow server and tool filters before approving calls.

Configuration equivalent

{
  "models": {
    "providers": {
      "soai": {
        "baseUrl": "https://SOAI_HOST:5090/v1",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "SOAI_OPENAI_API_KEY"
        },
        "api": "openai-completions",
        "models": [
          {
            "id": "YOUR_MODEL_ID",
            "name": "SoAI model",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 32768,
            "maxTokens": 4096
          }
        ]
      }
    }
  },
  "mcp": {
    "servers": {
      "soai": {
        "transport": "streamable-http",
        "url": "https://SOAI_HOST:5090/mcp",
        "headers": { "Authorization": "Bearer ${SOAI_MCP_TOKEN}" }
      }
    }
  }
}

Set both environment variables before starting OpenClaw. Replace the example limits and capabilities with values supported by the selected model; they are placeholders, not recommendations. Keep the SoAI API key and MCP token separate.

Related documentation