Skip to main content
The plugin registers these gateway RPC methods for runtime diagnostics, one-time invite and SimpleX address automation, runtime user visibility, verification, contact-request review, group-link lifecycle, moderation, file transfer controls, and operator-controlled SimpleX link onboarding.
For day-to-day one-time invite and SimpleX address workflows, prefer the plugin CLI commands in Example Commands. Use these gateway methods when another system needs programmatic access to runtime status, runtime users, verification, contact-request review, group-link lifecycle, moderation, file controls, or link onboarding.

​
Prerequisites and behavior

  • The target SimpleX account must be enabled and configured under channels.openclaw-simplex.
  • The simplex-chat WebSocket runtime must be reachable for that account.
  • If accountId is omitted or blank, the plugin uses the channel’s default account.
  • If the channel is not running, these methods ask OpenClaw to start openclaw-simplex for the target account and retry the SimpleX command.

​
simplex.invite.create

Create a one-time connect link or return/create the account’s reusable SimpleX address. Request params: 
{
  "mode": "connect",
  "accountId": "default"
}
mode supports:
  • connect -> creates a one-time invitation link
  • address -> returns or creates the account’s reusable SimpleX address
Response highlights:
  • link: the generated SimpleX link
  • qrDataUrl: PNG QR image as a data: URL for the same link
Example response shape: 
{
  "accountId": "default",
  "operation": "create-link",
  "mode": "connect",
  "link": "simplex:/contact#...",
  "qrDataUrl": "data:image/png;base64,..."
}

​
simplex.invite.list

List the current SimpleX address and related contact state through the SimpleX runtime APIs. Request params: 
{
  "accountId": "default"
}
Response highlights:
  • addressLink: current SimpleX address link if available
  • links: extracted SimpleX address links seen in the responses
  • pendingHints: pending contact hints, if exposed by the runtime
  • addressQrDataUrl: PNG QR image as a data: URL for addressLink
Example response shape: 
{
  "accountId": "default",
  "addressLink": "simplex:/contact#...",
  "links": ["simplex:/contact#..."],
  "pendingHints": [],
  "addressQrDataUrl": "data:image/png;base64,..."
}

​
simplex.invite.revoke

Revoke the active SimpleX address through the SimpleX runtime API. Request params: 
{
  "accountId": "default"
}
Example response shape: 
{
  "accountId": "default",
  "revoked": true
}

​
simplex.runtime.status

Return runtime and account state for automation and Control UI surfaces. Response highlights:
  • activeUser: active SimpleX user profile, if available
  • address: current SimpleX address metadata, if available
  • counts: contact, group, and user counts
  • capabilities: advisory runtime probe states for active user visibility, users, contacts, groups, live messages, TTL, moderation, verification, file controls, and experimental channel posture
  • filePolicy: configured file auto-accept and size policy visibility
  • security: WebSocket endpoint warnings and blocking posture
  • runtime: active client, connection state, and latest runtime error
  • runtimeVersion: SimpleX runtime version when the runtime exposes it through a probe response
  • wsUrl: configured WebSocket URL
Example response shape: 
{
  "accountId": "default",
  "configured": true,
  "mode": "external",
  "wsUrl": "ws://127.0.0.1:5225",
  "runtimeVersion": null,
  "runtime": {
    "activeClient": true,
    "connected": true,
    "lastError": null
  },
  "counts": {
    "contacts": 1,
    "groups": 0,
    "users": 1
  },
  "capabilities": {
    "version": {
      "state": "unknown",
      "command": "/version",
      "detail": "Runtime accepted /version but did not expose a version field.",
      "runtimeVersion": null,
      "value": null
    },
    "activeUser": {
      "state": "supported",
      "command": "/user",
      "runtimeVersion": null,
      "value": {
        "userId": 1
      }
    },
    "users": {
      "state": "supported",
      "command": "/users",
      "runtimeVersion": null,
      "count": 1
    },
    "contacts": {
      "state": "supported",
      "command": "/_contacts 1",
      "runtimeVersion": null,
      "count": 1
    },
    "groups": {
      "state": "supported",
      "command": "/_groups 1",
      "runtimeVersion": null,
      "count": 0
    },
    "liveMessages": {
      "state": "unknown",
      "detail": "Live replies are disabled in account config.",
      "runtimeVersion": null
    },
    "ttl": {
      "state": "unknown",
      "detail": "Message TTL is not configured.",
      "runtimeVersion": null
    },
    "moderation": {
      "state": "unknown",
      "detail": "Moderation support requires a real group/member target, so the advisory probe did not run it.",
      "runtimeVersion": null
    },
    "verification": {
      "state": "unknown",
      "detail": "Verification support requires a real contact target, so the advisory probe did not run it.",
      "runtimeVersion": null
    }
  }
}

​
simplex.runtime.doctor

Return the same runtime status plus ok and issues fields for operator diagnostics. Run openclaw simplex runtime doctor after enabling streaming.nativeTransport or message TTL. Capability probes are advisory WebSocket checks; they do not spawn, supervise, or manage the simplex-chat process, and they avoid destructive sends/deletes unless a caller explicitly supplies a real target through a higher-level operation.

​
simplex.runtime.users

List SimpleX runtime users for the selected account. Request params: 
{
  "accountId": "default"
}
Response shape: 
{
  "accountId": "default",
  "users": []
}

​
simplex.runtime.activeUser

Return the active SimpleX runtime user for the selected account.

​
simplex.verification.*

Expose contact verification commands when the connected simplex-chat runtime supports them. Older runtimes can return an unsupported response with the runtime error text.
  • simplex.verification.show: show verification metadata for contactId
  • simplex.verification.check: check verification metadata or a provided code for contactId
Example request: 
{
  "accountId": "default",
  "contactId": 123,
  "code": "optional-code"
}

​
simplex.requests.*

Manage pending SimpleX contact requests observed from runtime events.
  • simplex.requests.list: list stored pending requests for an account
  • simplex.requests.accept: accept a request by contactRequestId
  • simplex.requests.reject: reject a request by contactRequestId
Example request: 
{
  "accountId": "default",
  "contactRequestId": 123
}

​
simplex.groups.*

Create SimpleX groups and manage group invite links through the configured SimpleX WebSocket runtime.
  • simplex.groups.create: create a group from displayName, optional fullName, and optional description
  • simplex.groups.link.create: create a group link for groupId and optional role
  • simplex.groups.link.list: return the current group link plus QR data URL
  • simplex.groups.link.revoke: delete the current group link
  • simplex.groups.member.block: block or remove a member when the runtime supports it
  • simplex.groups.member.deleteMessages: remove a member’s group messages when the runtime supports it
Example group link request: 
{
  "accountId": "default",
  "groupId": 42,
  "role": "member"
}
Example response shape: 
{
  "accountId": "default",
  "groupId": 42,
  "role": "member",
  "link": "https://smp18.simplex.im/g#...",
  "qrDataUrl": "data:image/png;base64,..."
}
Example moderation request: 
{
  "accountId": "default",
  "groupId": 42,
  "memberId": 77
}

​
simplex.files.*

Control SimpleX file transfers through the active WebSocket runtime.
  • simplex.files.receive: receive a pending file by fileId
  • simplex.files.cancel: cancel a pending or active file transfer by fileId
Example request: 
{
  "accountId": "default",
  "fileId": 123
}

​
simplex.connect.*

Let an operator connect the SimpleX runtime identity to a SimpleX contact/address/group link.
  • simplex.connect.plan: inspect what connecting to link would do
  • simplex.connect: connect the active SimpleX user to link
link may be a native SimpleX link such as simplex:/contact#... or a short web link such as https://smp18.simplex.im/g#.... Example request: 
{
  "accountId": "default",
  "link": "https://smp18.simplex.im/g#..."
}
Example response shape: 
{
  "accountId": "default",
  "connected": true,
  "result": {
    "type": "sentConfirmation"
  }
}

​
Errors

CodeMeaning
INVALID_REQUESTThe request params are invalid. For example, simplex.invite.create received an unsupported mode.
UNAVAILABLEThe account is disabled/unconfigured, the channel runtime is unavailable, or the underlying SimpleX runtime API call failed. The response message includes the failure reason.
The plugin also exposes these agent/tool-surface operations. They are not gateway RPC methods, but they cover the same invite and group administration flows from inside an agent run.
  • simplex_invite_create
  • simplex_invite_list
  • simplex_invite_revoke
  • simplex_group_add_participant
  • simplex_group_remove_participant
  • simplex_group_leave
These destructive tools require approval before execution:
  • simplex_invite_revoke
  • simplex_group_remove_participant
  • simplex_group_leave