Skip to main content

​
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

{
  "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

Build docs developers (and LLMs) love

Get started for freeTalk to us