Network Adapters

Configure HTTP, WebSocket, and reverse connection adapters for OneBot 11 protocol

Overview

NapCat supports multiple network adapter types for flexible integration with your applications. You can configure servers (where your app connects to NapCat) or clients (where NapCat connects to your app).

Adapter Types

HTTP Server

HTTP server adapter that receives OneBot 11 API requests via HTTP POST.

name · string · default: "http-server" · required

Unique identifier for this adapter instance.

enable · boolean · default: false · required

Enable or disable this adapter.

port · number · default: 3000

Port number to listen on.

host · string · default: "127.0.0.1"

Host address to bind to. Use 0.0.0.0 to listen on all interfaces.

enableCors · boolean · default: true

Enable Cross-Origin Resource Sharing (CORS) for web-based clients.

enableWebsocket · boolean · default: false

Enable WebSocket upgrade support on this HTTP server.

messagePostFormat · string · default: "array"

Message format: array (CQ code format) or string.

token · string · default: ""

Authentication token. Clients must include this in the Authorization header or access_token query parameter.

debug · boolean · default: false

Enable debug logging for this adapter.

HTTP SSE Server

HTTP Server-Sent Events adapter for real-time event streaming.

name · string · default: "http-sse-server" · required

Unique identifier for this adapter instance.

enable · boolean · default: false · required

Enable or disable this adapter.

port · number · default: 3000

Port number to listen on.

host · string · default: "127.0.0.1"

Host address to bind to.

enableCors · boolean · default: true

Enable CORS support.

messagePostFormat · string · default: "array"

Message format: array or string.

token · string · default: ""

Authentication token.

reportSelfMessage · boolean · default: false

Report messages sent by the bot itself.

debug · boolean · default: false

Enable debug logging.

WebSocket Server

WebSocket server adapter for bidirectional real-time communication.

name · string · default: "websocket-server" · required

Unique identifier for this adapter instance.

enable · boolean · default: false · required

Enable or disable this adapter.

host · string · default: "127.0.0.1"

Host address to bind to.

port · number · default: 3001

Port number to listen on.

messagePostFormat · string · default: "array"

Message format: array or string.

reportSelfMessage · boolean · default: false

Report messages sent by the bot itself.

token · string · default: ""

Authentication token.

enableForcePushEvent · boolean · default: true

Force push events even if the client is not ready.

debug · boolean · default: false

Enable debug logging.

heartInterval · number · default: 30000

Heartbeat interval in milliseconds.

HTTP Client (Reverse Connection)

HTTP client adapter that posts events to your server.

name · string · default: "http-client" · required

Unique identifier for this adapter instance.

enable · boolean · default: false · required

Enable or disable this adapter.

url · string · default: "http://localhost:8080" · required

Target URL where events will be posted.

messagePostFormat · string · default: "array"

Message format: array or string.

reportSelfMessage · boolean · default: false

Report messages sent by the bot itself.

token · string · default: ""

Authentication token sent in the Authorization header.

debug · boolean · default: false

Enable debug logging.

WebSocket Client (Reverse Connection)

WebSocket client adapter that connects to your WebSocket server.

name · string · default: "websocket-client" · required

Unique identifier for this adapter instance.

enable · boolean · default: false · required

Enable or disable this adapter.

url · string · default: "ws://localhost:8082" · required

Target WebSocket URL to connect to.

messagePostFormat · string · default: "array"

Message format: array or string.

reportSelfMessage · boolean · default: false

Report messages sent by the bot itself.

reconnectInterval · number · default: 5000

Reconnection interval in milliseconds when connection is lost.

token · string · default: ""

Authentication token.

debug · boolean · default: false

Enable debug logging.

heartInterval · number · default: 30000

Heartbeat interval in milliseconds.

Plugin Adapter

Plugin adapter for custom integrations and extensions.

name · string · default: "plugin" · required

Unique identifier for this plugin adapter.

enable · boolean · default: false · required

Enable or disable this adapter.

messagePostFormat · string · default: "array"

Message format: array or string.

reportSelfMessage · boolean · default: false

Report messages sent by the bot itself.

debug · boolean · default: false

Enable debug logging.

Configuration Examples

HTTP Server

{
  "network": {
    "httpServers": [
      {
        "name": "main-http",
        "enable": true,
        "port": 3000,
        "host": "127.0.0.1",
        "enableCors": true,
        "enableWebsocket": false,
        "messagePostFormat": "array",
        "token": "your-secret-token",
        "debug": false
      }
    ]
  }
}

Authentication

All adapters support token-based authentication:

For Server Adapters (HTTP/WebSocket Servers):

• Include token in Authorization header: Authorization: Bearer your-token
• Or include as query parameter: ?access_token=your-token

For Client Adapters (HTTP/WebSocket Clients):

• NapCat includes the token in the Authorization header when connecting to your server

Common Use Cases

Single Application

Use HTTP or WebSocket server:

{
  "network": {
    "httpServers": [
      {
        "name": "api",
        "enable": true,
        "port": 3000
      }
    ]
  }
}

Multiple Applications

Enable multiple adapters:

{
  "network": {
    "httpServers": [
      { "name": "app1", "enable": true, "port": 3000 },
      { "name": "app2", "enable": true, "port": 3001 }
    ]
  }
}

Reverse Connection (NAT/Firewall)

Use client adapters when NapCat can’t accept incoming connections:

{
  "network": {
    "websocketClients": [
      {
        "name": "reverse",
        "enable": true,
        "url": "ws://your-server.com:8080"
      }
    ]
  }
}

Notes

• Each adapter can be individually enabled/disabled
• Multiple adapters of the same type can run simultaneously
• Adapter names must be unique across all adapter types
• Debug mode increases log verbosity for troubleshooting
• Heart interval controls keep-alive ping frequency for WebSocket connections