Common HoshinoBot Deployment Issues with OneBot and gocqhttp: Complete Troubleshooting Guide

Most HoshinoBot deployment failures stem from mismatched OneBot protocol versions, incorrect reverse WebSocket URLs, or missing authentication tokens between the bot and go-cqhttp client.

HoshinoBot operates as a reverse WebSocket server that requires a OneBot v11-compatible client like go-cqhttp to handle QQ protocol communication. When configuring ice9coffee/hoshinobot, administrators must align network settings, resource paths, and authentication tokens across both the bot configuration and the client config.yml. Below are the critical failure points and their fixes based on the actual source implementation.

OneBot Protocol Version Compatibility

HoshinoBot strictly implements the OneBot v11 specification. Using older go-cqhttp releases (< v1.0.0) that implement the legacy OneBot v10 API causes immediate connection failures or silent message drops.

Verify your client supports protocol version 11 by checking the protocol_version field in your go-cqhttp configuration. According to the repository README, any standard OneBot v11 client—including go-cqhttp, CQHTTP-Mirai, or similar implementations—can connect to HoshinoBot successfully.

Reverse WebSocket Configuration Errors

The most frequent deployment blocker involves misaligned WebSocket endpoints. HoshinoBot listens on HOST and PORT defined in hoshino/config_example/__bot__.py (defaulting to 127.0.0.1:8080), while go-cqhttp must connect to this endpoint via the reverse WebSocket universal URL.

In hoshino/config_example/__bot__.py, verify these lines:

PORT = 8080
HOST = '127.0.0.1'

Then ensure your go-cqhttp config.yml contains the matching universal endpoint:

servers:
  - ws-reverse:
      universal: ws://127.0.0.1:8080/ws/
      reconnect-interval: 5000

Test connectivity using nc -zv 127.0.0.1 8080 on Linux or telnet 127.0.0.1 8080 on Windows. If the connection fails, check that the bot process has started successfully via run.py and that no other service occupies port 8080.

Access Token Authentication Failures

When access-token is configured, both sides must share the identical secret. If the bot specifies a token in __bot__.py while go-cqhttp sends a different value (or empty), the handshake fails silently.

Set the token in __bot__.py to match go-cqhttp's default-middlewares section:

# In hoshino/config_example/__bot__.py

# TOKEN = 'your-secret-token'  # Or leave empty for no auth

# In go-cqhttp config.yml

default-middlewares: &default
  access-token: 'your-secret-token'  # Must match exactly or both empty

Resource Path and Image Sending Failures

Modules like flac or setu fail when RES_DIR points to a non-existent directory or when RES_PROTOCOL is misconfigured. The bot expects a writable resource directory at the path specified in __bot__.py.

Configure resource handling according to your deployment architecture:

RES_PROTOCOL = 'file'  # Use 'file' for same-machine deployment

RES_DIR = r'./res/'    # Absolute path recommended for production

RES_URL = 'http://127.0.0.1:5000/static/'  # Only for HTTP mode

When RES_PROTOCOL is set to http, you must run a static file server (e.g., python -m http.server 5000 --directory ./res) and ensure RES_URL is reachable from the client machine.

Missing API Keys for External Services

Services like Princess Connect Re:Dive arena lookup (pcrdfans), Mikan RSS, and Twitter integration require API keys stored in dedicated config modules. The bot reads these from hoshino/config/priconne.py, hoshino/config/mikan.py, and hoshino/config/twitter.py respectively.

If these modules are enabled but keys are missing, external API calls return authentication errors without crashing the bot. Verify each config file contains valid credentials and restart HoshinoBot after editing any configuration file in the hoshino/config/ directory.

Network and Firewall Restrictions

Linux distributions with UFW or SELinux enabled often block the WebSocket port by default. Symptoms include connection timeouts where nc commands fail despite the bot process running.

Resolve this by opening the specific port:

sudo ufw allow 8080/tcp

For SELinux enforcing mode, you may need to adjust policies or temporarily set permissive mode to test connectivity.

Python Environment and Dependency Issues

HoshinoBot requires Python 3.8 or higher. Missing packages such as nonebot, aiohttp, or quart cause import errors during startup.

Reinstall dependencies ensuring correct versions:

python3 -m pip install -r requirements.txt

Check requirements.txt in the repository root for the exact dependency specifications. Version conflicts typically manifest as ImportError or AttributeError in the console output.

Debugging Hidden Errors

By default, HoshinoBot writes error tracebacks to log/error.log as defined in hoshino/log.py. If the bot appears unresponsive but shows no console errors, examine this file for detailed stack traces.

Enable verbose debugging temporarily by setting DEBUG = True in __bot__.py:

DEBUG = True  # Increases logging verbosity for troubleshooting

Step-by-Step Troubleshooting Checklist

1. Confirm OneBot v11 compatibility – upgrade go-cqhttp to v1.0.0+
2. Match WebSocket URLs – verify HOST:PORT in __bot__.py matches ws-reverse.universal in go-cqhttp
3. Validate access-token – ensure identical values or both empty
4. Check resource directories – confirm RES_DIR exists and permissions allow writing
5. Supply required API keys – fill in priconne.py, mikan.py, and twitter.py configs
6. Open firewall ports – allow traffic on port 8080 or your custom port
7. Review error logs – check log/error.log for suppressed tracebacks
8. Restart both services – apply configuration changes by restarting bot and client

Configuration Reference

Complete working configuration examples for both sides of the connection:

Bot configuration (hoshino/config_example/__bot__.py):

PORT = 8080
HOST = '127.0.0.1'
DEBUG = False

RES_PROTOCOL = 'file'
RES_DIR = r'./res/'
RES_URL = 'http://127.0.0.1:5000/static/'

MODULES_ON = {
    'flac',
    'setu',
    # Add other required modules

}

Client configuration (go-cqhttp/config.yml):

account:
  uin: 123456789
  password: ''
  
default-middlewares: &default
  access-token: ''

servers:
  - ws-reverse:
      universal: ws://127.0.0.1:8080/ws/
      reconnect-interval: 5000
      middlewares:
        <<: *default

Summary

• Use OneBot v11 exclusively – older protocol versions cause silent failures
• Align reverse WebSocket settings – match HOST:PORT in __bot__.py with the client's ws-reverse.universal URL
• Synchronize access tokens – identical values required on both bot and client
• Configure resource paths – ensure RES_DIR exists and choose file or http protocol appropriately
• Check log/error.log – primary location for debugging information when console output appears normal

Frequently Asked Questions

What OneBot version does HoshinoBot require?

HoshinoBot requires OneBot v11 protocol support. Older versions like OneBot v10, found in go-cqhttp releases prior to v1.0.0, are incompatible and will cause connection failures or message handling errors.

Why does go-cqhttp fail to connect to HoshinoBot?

The client cannot reach the bot's reverse WebSocket server. Verify that HOST and PORT in hoshino/config_example/__bot__.py match the ws-reverse.universal URL in go-cqhttp's config.yml. Ensure no firewall blocks the connection and that the bot process is actively listening using nc or telnet tests.

How do I fix image sending failures in HoshinoBot?

Check RES_PROTOCOL and RES_DIR settings in __bot__.py. For local deployments, use RES_PROTOCOL = 'file' and ensure RES_DIR points to an existing, writable directory. For remote clients, use http mode and verify the static file server specified in RES_URL is accessible.

Where are HoshinoBot error logs stored?

Error logs are written to log/error.log in the project root, as implemented in hoshino/log.py. If the bot behaves unexpectedly but shows no console errors, examine this file for Python tracebacks and API error responses.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}