openclaw-omelink

Omelink channel plugin for OpenClaw.

For Chinese documentation, see README.zh-CN.md.

Configuration

Config path: channels.omelink

{
  "channels": {
    "omelink": {
      "enabled": true,
      "callbackUrl": "<full-webhook-url-for-outbound-messages>",
      "apiKey": "<api-key-for-outbound-messages>"
    }
  }
}

Field Reference

• enabled: Enable channel, default true.
• defaultAccountId: Default account ID, default default.
• callbackUrl: Required. The FULL URL where OpenClaw will send outbound messages (e.g., http://example.com/api/callback).
• apiKey: Required. The API key used in the x-api-key header when OpenClaw calls callbackUrl.
• webhookPort: Local listener port for inbound webhook and config webhook, default 17321.

Internal Fixed Paths:

• Inbound Webhook: /omelink/events
• Config Webhook: /omelink/config/set

Integration Contract

1) Inbound Webhook (Omelink Services -> OpenClaw)

• URL: http://<openclaw-host>:<webhookPort>/omelink/events
• Method: POST
• Headers:
  • Content-Type: application/json
• Body:
  • userId (required): Unique identifier for the user in Omelink.
  • text (required): Message content.
  • messageId (required): Unique message ID for deduplication.
  • conversationId (optional): Conversation identifier. If not provided, defaults to "default". New conversationId creates a new chat session.

Request Example:

{
  "userId": "u1001",
  "text": "Who are you?",
  "messageId": "msg-001",
  "conversationId": "conv-001"
}

2) Outbound Delivery (OpenClaw -> Omelink Services)

• URL: <callbackUrl> (Configured by user)
• Method: POST
• Headers:
  • Content-Type: application/json
  • x-api-key: <apiKey>
• Body:
  • userId: The recipient's user ID.
  • text: Message content.
  • messageId (optional): Original message ID from inbound (for replies).
  • conversationId (optional): Conversation ID from inbound.
  • provider: Fixed as omelink.

Request Example:

{
  "userId": "u1001",
  "text": "Hi there!",
  "messageId": "msg-001",
  "conversationId": "conv-001",
  "provider": "omelink"
}

Expected Response:

{
  "messageId": "out-123"
}

3) Config Webhook (Optional)

Allows dynamic configuration updates.

• URL: http://<openclaw-host>:<webhookPort>/omelink/config/set
• Method: POST
• Headers:
  • Content-Type: application/json
• Body:
  • Supported fields: enabled, callbackUrl, apiKey, webhookPort.
  • Fields can be at the top level or nested under config.

Request Example:

{
  "config": {
    "callbackUrl": "http://new-service.com/api/callback",
    "apiKey": "new-api-key"
  }
}

Response Example:

{
  "ok": true,
  "updatedFields": ["callbackUrl", "apiKey"]
}

Constraints

• Direct Messages Only: Currently supports 1-on-1 chats.
• Idempotency: messageId must be unique. Duplicate IDs will be ignored.
• Session Isolation: Sessions are isolated by userId + conversationId. To start a fresh context, use a new conversationId.

Local Debugging

Installation

pnpm install

# Install locally (no build required)
openclaw plugins install -l $(pwd)

Testing Inbound Webhook

curl -X POST "http://127.0.0.1:17321/omelink/events" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "test-user",
    "text": "Hello OpenClaw",
    "messageId": "msg-test-001",
    "conversationId": "dev-test"
  }'

Note: Change messageId for subsequent requests to avoid deduplication.

Uninstall

openclaw plugins uninstall @sj-distributor/openclaw-omelink
rm -rf ~/.openclaw/extensions/openclaw-omelink