xwclaw

xwclaw is an OpenClaw plugin that bridges OpenClaw and the Python-side business service.

Install

openclaw plugins install @xw-ai/xwclaw@latest

For local development, you can also load the plugin from a local path.

What It Does

The plugin is responsible for:

• reading local plugin config
• forwarding legacy debug chat requests to Python
• calling the Python bind API
• dispatching inbound business messages into OpenClaw
• forwarding OpenClaw callback results back to Python

Business orchestration still stays on the Python side.

Config

The plugin reads config from local config.json.

• baseUrl: Python service base URL
• token: plugin 调用 Python 接口时使用的令牌；绑定成功后会自动写入本地配置
• instanceId: internal OpenClaw node instance id
• pluginLobsterCallbackPath: callback route exposed by the plugin on the OpenClaw side
• pythonLobsterCallbackPath: callback route on the Python side
• timeout: HTTP timeout in milliseconds
• headers: extra request headers

If internalBaseUrl, externalBaseUrl, and routeMode are configured, the plugin picks the effective baseUrl according to the routing mode.

Config Priority

Current priority is:

1. environment variables
2. pluginConfig injected by OpenClaw
3. local config.json

Supported environment variables include:

• XW_CLAW_BASE_URL
• XW_CLAW_ACCESS_TOKEN
• XW_CLAW_INSTANCE_ID
• XW_CLAW_INTERNAL_BASE_URL
• XW_CLAW_EXTERNAL_BASE_URL
• XW_CLAW_ROUTE_MODE

CLI Usage

Recommended setup flow:

openclaw xwclaw --base-url http://127.0.0.1:8080 --token <binding-token>
openclaw xwclaw show

You can also keep using the explicit bind command:

openclaw xwclaw bind --token <binding-token>

The root command supports direct config write too:

openclaw xwclaw --base-url http://127.0.0.1:8080
openclaw xwclaw --token demo-token
openclaw xwclaw --base-url http://127.0.0.1:8080 --token demo-token

Compatibility flags are also supported:

openclaw xwclaw config --base-url http://127.0.0.1:8080 --token demo-token
openclaw xwclaw --baseUrl http://127.0.0.1:8080 --accessToken demo-token

instanceId is treated as an internal field and is not exposed as a customer-facing CLI option.

Chat Command Compatibility

For development compatibility, the plugin still keeps chat-side commands:

• /xwclaw <message>: call the legacy Python debug chat API
• /xwclawconfig <baseUrl> <token> [instanceId]: write local dev config
• /xwclawbind <token>: call the bind API

For terminal-based setup, prefer openclaw xwclaw ....

Message Flow

1. PC calls Python /api/xw-claw/sendMsg
2. Python calls OpenClaw xwclaw.chat
3. xwclaw dispatches the message into the OpenClaw session flow
4. The result is forwarded back to Python through POST {baseUrl}{pythonLobsterCallbackPath}
5. Python continues business handling based on taskId

Example Config

{
  "baseUrl": "http://127.0.0.1:8080",
  "token": "demo-token",
  "pluginLobsterCallbackPath": "/plugins/xwclaw/callback/lobster-message",
  "pythonLobsterCallbackPath": "/api/xw-claw/callback/lobster-message",
  "instanceId": "openclaw-local-001",
  "timeout": 10000,
  "headers": {
    "x-openclaw-source": "local-debug"
  }
}

HTTP Endpoints

Legacy debug chat endpoint:

POST {baseUrl}/api/chat

Bind endpoint:

POST {baseUrl}/api/openclaw/plugin/bind

Callback endpoint forwarded to Python:

POST {baseUrl}{pythonLobsterCallbackPath}

Example Legacy Chat Payload

{
  "taskId": "task-id",
  "requestId": "request-id",
  "message": "hello",
  "sessionId": "session-id",
  "userId": "user-id",
  "instanceId": "openclaw-instance-id",
  "accessToken": "access-token",
  "metadata": {}
}

Example Callback Payload

{
  "taskId": "task-id",
  "lobsterAccount": "test0001",
  "reply": "processed result",
  "messageContent": "processed result"
}