Configuration File Documentation
Note
L1 Core Must-Read — One of the five core documents in the homepage "Reading Path", essential for module development.
This document explains the framework's own configuration file
config/config.toml: what each section manages, which settings support hot reload, and how to override them with environment variables. For third-party module configuration items, please refer to the module's own documentation.
ErisPulse uses a TOML-formatted configuration file config/config.toml to manage project configurations.
Configuration File Location
The configuration file is located in the config/ folder at the project root:
project/
├── config/
│ └── config.toml
├── main.py
Multi-Instance Warning and Lock File
When the framework starts, it creates a config.lock lock file in the project root's runtime status directory .erispulse/ and holds it until the process exits (used to detect multiple instances sharing the configuration directory; in versions 2.10 and earlier, the .erispulse_config.lock in the config/ directory would be automatically cleared after upgrade and first startup). If the log shows a warning like "Detected that the configuration file may be in use by another ErisPulse instance," it means there are two or more ErisPulse processes writing to the same configuration file (typical scenario: multiple containers mounting the same host config/ directory) — concurrent writes will overwrite each other. Please use a separate configuration directory for each instance.
Sensitive Configuration Not in Repository
The configuration file contains tokens (token/API key) and other sensitive information: the framework initialization and epsdk init automatically generate a .gitignore in the config/ directory (with only one line * — all files in the directory are not included in version control, including the ignore file itself). Existing .gitignore files will not be overwritten. The .erispulse/ runtime status directory (instance lock, CLI runtime status files) is considered local machine state, and the project template's .gitignore already defaults to ignoring it.
Configuration Loading Error Handling
When the framework loads config.toml, it distinguishes three error states and provides actionable diagnostic information instead of silently reverting to default configuration:
| Error State | Trigger Condition | Framework Behavior |
|---|---|---|
| File Missing | config.toml does not exist |
On normal first startup, silently uses empty configuration (no warning) |
| TOML Syntax Error | File exists but format is invalid (e.g., missing quotes, un-closed brackets) | Outputs line/column number and reason for error, and retains last valid configuration to continue running (this file modification does not take effect) |
| Permission/Other Error | No read permission, IO error, etc. | Outputs clear reason, and retains last valid configuration to continue running |
Note "last valid configuration" ≠ default configuration: When the file is damaged, the framework uses the last successfully parsed configuration before this startup (if a running hot update modifies the file badly, it uses the old value), rather than resetting all configuration items to factory defaults. When troubleshooting, do not assume "configuration has been reset."
For example, if you accidentally write the configuration as port = 8000 (missing quotes for a string), the log will output something like:
[ERROR] [Config] Configuration file config/config.toml has a syntax error (line 3, column 1): ...
[WARNING] [Config] Failed to read configuration file. Continuing to run using the last valid configuration, this file modification did not take effect — please fix and reload or restart
This allows you to immediately locate the issue at the default INFO level instead of being confused "why my modified configuration did not take effect."
Modified configuration file while running? If you manually edit
config.tomlduring robot operation and introduce a syntax error, the framework will output "Configuration file has been damaged (syntax error, line X), cannot merge and write — please fix the configuration file and restart" when it next writes (merges configuration), rather than a confusing "write failed." The configuration items to be written will be retained and not lost.
Comment Preservation and Minimal Disk Write
The comments and key order in config.toml are fully preserved after the framework writes: whether through code setConfig(), CLI configuration wizard save, or adapter/module first-generation configuration template, the framework only modifies the involved keys, your written comments and organized order will not be erased or rearranged (based on tomlclass's lossless TOML engine, untouched content is preserved byte-for-byte, and the file's original CRLF/LF line endings are not changed).
The framework keeps disk writes minimal:
- Framework default configuration is not automatically written to disk:
gc,scope,transcriptand other built-in default values only reside in memory,config.tomlonly contains keys you explicitly set, keeping it minimal. For a complete list of configurable items, refer toconfig/config.full.examplein the project, copy and modify as needed (unconfigured items always use built-in defaults, behavior unchanged) config.full.exampleis automatically maintained: Regardless of whetherepsdk inithas been executed, as long as the framework is started (epsdk run/main.py),config/config.full.examplewill be automatically generated if missing; the first line of the file is a framework-maintained marker, generator content updates (such as new configuration items, newly installed components) will refresh once on startup, deleting/modifying the first line switches to manual takeover, and the framework will no longer overwrite- Adapter/Module Configuration Templates: First initialization saves templates with comments (field descriptions are comments); fields marked as
exampleare not written to disk, only recorded inconfig.full.examplefor reference - Declarative Comments Readback: Comments in the configuration file are documentation itself —
ep doctorand configuration validation failure messages will reference the original comment text of the field in the file (even if you manually modified the comment, the message follows the current file state), no need to refer to the documentation to find the field meaning when reporting errors
Environment Variable Override
The framework supports overriding ErisPulse.* configuration items with environment variables (suitable for Docker/containerization/CI deployment, no need to modify config.toml).
Naming rule: Change the dot-separated path ErisPulse.<section>.<key> to all uppercase, replace . with _, and add the ERISPULSE_ prefix:
| Configuration Item | Environment Variable | Example Value |
|---|---|---|
ErisPulse.server.port |
ERISPULSE_SERVER_PORT |
9000 |
ErisPulse.server.host |
ERISPULSE_SERVER_HOST |
0.0.0.0 |
ErisPulse.logger.level |
ERISPULSE_LOGGER_LEVEL |
DEBUG |
ErisPulse.framework.strict_mode |
ERISPULSE_FRAMEWORK_STRICT_MODE |
2 |
Behavior description:
- Highest Priority: Environment variables override "configuration file" and "default values," automatically converting to the original value type (bool/int/float/comma-separated list/string)
- Not Persistent: Override only takes effect during runtime and is not written back to
config.toml - Support Hot Reload: After modifying environment variables during runtime, configuration listening reload can take effect
# Docker deployment example: no need to modify config.toml, directly override port
ERISPULSE_SERVER_PORT=9000 docker compose up -d
Note:
ErisPulse.server.portand other framework configurations accessed throughget_server_config()and similar APIs are affected by environment variable overrides.
Module Configuration Environment Variable Binding (2.9.0+)
Modules' own declarative configurations (ConfigClass) support field-level environment variable binding — declare env in field(metadata=...):
@dataclass
class MyConfig(BaseConfig):
api_key: str = field(default="", metadata={
"description": "API key",
"env": "MYMODULE_API_KEY", # Environment variable binding
})
retries: int = field(default=3, metadata={"env": "MYMODULE_RETRIES"})
Behavior description:
- Priority: Environment variable >
config.toml> declared default value (configuration file hot update still maintains this priority) - Type Conversion: Environment variable values are automatically converted according to field annotations —
stras original,int/float/bool(true/1/yes/on) automatically converted,list/dictparsed via JSON; if conversion fails, ignore the override (fallback to configuration file/default value) and output a warning - Declare Once, Apply Everywhere: Configuration reading, hot update, and validation use the same pipeline; configuration panel Schema will mark
envnames, andconfig.tomltemplate comments will also prompt available environment variables (template does not write actual values of environment variables to avoid leakage) - Fully Compatible: Fields without
envdeclaration behave unchanged; directly instantiating ConfigClass (without framework configuration pipeline) is not affected by environment variables
# Docker deployment example: no need to modify config.toml, directly inject module key
MYMODULE_API_KEY=sk-xxx docker compose up -d
Configuration Class vs Model Field When to Use Which? Configuration class manages "how the module runs" (behavior parameters, hot reload), ORM's
Field()manages "what data the user generates" (database table, query). Both share the same constraint vocabulary and validator engine; see the comparison table at Data Model Layer · When to Use Which Declaration.
Configuration Hot Reload
Starting from version 2.7.0, the framework provides systematic support for configuration hot reload. After external modification of config.toml (background watcher checks every 5 seconds), or code calls setConfig(), each component automatically responds:
| Component | Configuration Supporting Hot Reload | Behavior |
|---|---|---|
| Logger | logger.level / log_files / log_dir (including segmentation parameters) / memory_limit / format / exclude_levels |
Automatically reapplies (with change detection) |
| Command System | event.command.prefix / case_sensitive / allow_space_prefix / must_at_bot |
Takes effect on the next message |
| Adapter Concurrency | framework.handler_max_concurrency |
Invalidates cached semaphore, rebuilds with new value |
| Proactive GC | framework.proactive_gc_* |
Config change immediately restarts GC task, supports runtime adjustment/disable/re-enable |
| Master System | master.users |
Each is_master() check reads in real time, no restart needed |
| Module/Adapter Configuration | Their own configuration items | Triggers on_config_update(old, new) callback |
Configuration that Requires Restart (cannot be safely hot switched, warning is output when changed "requires restart of process to take effect"):
| Configuration | Reason |
|---|---|
router.cors.* / router.security.* |
Middleware is written into FastAPI at service startup, cannot be safely hot switched at runtime |
storage.use_global_db |
SQLite file handle is already open at runtime, switching path is unsafe |
Error during mid-edit save? If a transient syntax error occurs while editing
config.toml, the framework will retain the last valid configuration and output diagnostic logs, and will not broadcast an empty configuration to each component (to avoidon_config_updatereceiving empty values and mistakenly reverting to defaults).
Internal Breakdown of Hot Reload Chain
"How do components know when the configuration is changed?" — Behind the scenes is a detection → reload → broadcast chain:
flowchart TD
A["External edit config.toml"] --> B{"Who first detects it?"}
B -->|"Background watcher thread<br/>Polls mtime every 5 seconds"| C["_check_file_change determines change"]
B -->|"When reading configuration<br/>Cache exceeds 60 seconds"| C
C --> D["_load_config re-parses TOML"]
D --> E{"Parsing successful?"}
E -->|"No (syntax error)"| F["Retain last valid configuration<br/>Do not broadcast, output diagnostic log"]
E -->|"Yes"| G["lifecycle.emit config.updated<br/>Carries old_config / new_config"]
G --> H["Each component listener responds<br/>(logger / scope / command / GC ... )"]
Two Detection Paths (either one is sufficient, both can serve as a fallback):
| Path | Mechanism | Trigger Timing |
|---|---|---|
| Background watcher | Daemon thread config-watcher polls file mtime every 5 seconds in wait |
At most 5 seconds after external file modification |
| Lazy Detection | Any getConfig() read, if cache exceeds 60 seconds, first checks file |
Next time configuration is read |
Framework will not hurt itself: When
setConfig()writes to disk, it records the "mtime written by itself," and the watcher excludes it when comparing, recognizing only external edits as changes.
Two Types of Configuration Change Events:
| Event | Trigger | Data | Typical Scenario |
|---|---|---|---|
config.set |
Code / Dashboard calls setConfig() |
{key, old_value, new_value} |
Single key write (template generation, status recording, runtime config change) |
config.updated |
External edit after watcher/lazy detection captures | {old_config, new_config, config_file} |
Manually editing config.toml |
setConfig()defaults to delayed write to disk (merges multiple writes),immediate=Truewrites immediately. After the watcher detects an external modification, it only updates the in-memory cache and does not write the external change back to the file.
List of Automatic Response Parties (both event types usually subscribe, response content is consistent):
| Component | Listener | Response |
|---|---|---|
| Logger | config.set + config.updated |
Level/file/directory segmentation/memory limit/format/exclude level reapply (with change detection, no change does not move) |
| Scope | config.updated |
Scope binding cache rebuild |
| Command System | config.updated |
Prefix/case sensitivity/space prefix/must_at_bot parse parameter refresh, takes effect on next message |
| Adapter Concurrency | config.set + config.updated |
handler_max_concurrency invalidates and rebuilds semaphore |
| Proactive GC | config.set + config.updated |
proactive_gc_* immediately restarts GC background task |
| Adapter | Route to on_config_update |
Each adapter's on_config_update(old, new) callback |
| Module | Route to on_config_update |
Each module's on_config_update(old, new) callback |
| Storage | config.updated |
use_global_db change only warns (requires restart) |
| Router | config.updated |
cors.* / security.* change only warns (requires restart) |
Configuration Reading and Deletion API
getAllConfig: Full Configuration Snapshot
Instead of directly reading private _cache (external reading of private attributes is not protected by version compatibility):
config = sdk.config.getAllConfig() # Deep copy snapshot, in-place modification does not affect framework state
config["ErisPulse"]["server"]["port"]
The view口径 is consistent with getConfig: setConfig / delete that have not been written to disk are already reflected, and the content strictly matches the file after delayed write.
delConfig: Delete Configuration Key
setConfig(key, None) only sets it to empty, the key remains in the file; delConfig will remove the key from the file:
sdk.config.delConfig("ErisPulse.modules.status.OldModule") # Delayed write
sdk.config.delConfig("OneBot.deprecated_key", immediate=True) # Write immediately
- Supports dot-separated paths; returns
Falseif the key does not exist - Writes follow the comment preservation path, the rest of the file content and order are unaffected
- Reuses
config.setevent broadcast (withnew_value=None): existing listeners for adapters/modules zero changes can perceive deletion
Complete Configuration Example
[ErisPulse.server]
host = "0.0.0.0"
port = 8000
auto_start = true
ssl_certfile = ""
ssl_keyfile = ""
[ErisPulse.master]
# users support two writing methods (choose one):
# Global master (effective for all platforms): users = ["123456", "789012"]
# Specify master per platform: users = { yunhu = ["123456"], telegram = ["789012"] }
users = {}
[ErisPulse.logger]
level = "INFO"
format = "rich"
log_files = []
log_dir = ""
log_rotation = "size"
log_max_size_mb = 10
log_backup_count = 5
log_rotation_when = "midnight"
memory_limit = 1000
exclude_levels = []
[ErisPulse.framework]
enable_lazy_loading = true
uninit_timeout = 30
strict_mode = 0
[ErisPulse.framework.strict_mode_exceptions]
modules = []
adapters = []
[ErisPulse.storage]
backend = "sqlite"
use_global_db = false
[ErisPulse.event.command]
prefix = "/"
case_sensitive = true
allow_space_prefix = false
must_at_bot = false
[ErisPulse.event.message]
ignore_self = true
[ErisPulse.i18n]
language = "auto"
Server Configuration
[ErisPulse.server]
host = "0.0.0.0"
port = 8000
auto_start = true
ssl_certfile = "/path/to/cert.pem"
ssl_keyfile = "/path/to/key.pem"
# For container / no file mounting scenarios, PEM content can be inlined (prioritized over certfile/keyfile path)
# ssl_cert = """-----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----"""
# ssl_key = """-----BEGIN PRIVATE KEY-----
# ...
# -----END PRIVATE KEY-----"""
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| host | string | 0.0.0.0 | Listening address, 0.0.0.0 means all interfaces |
| port | integer | 8000 | Listening port number |
| auto_start | boolean | true | Whether to automatically start the routing server at sdk.init(). Set to false to skip routing server startup (pure event/no WebUI scenario) |
| ssl_certfile | string | empty | SSL certificate file path |
| ssl_keyfile | string | empty | SSL private key file path |
| ssl_cert | string | empty | Inlined PEM certificate content (not a path). When used together with ssl_key, it takes precedence over ssl_certfile/ssl_keyfile paths; the framework temporarily writes and builds the SSL context, then immediately deletes the temporary file |
| ssl_key | string | empty | Inlined PEM private key content (not a path), same semantics as above |
Port occupancy is not a fatal error: If the framework detects that the
portis already occupied at startup, it will skip starting the routing server and issue a warning, adapters and modules will still run normally (only HTTP/WS/SSE routing and WebUI are unavailable). When troubleshooting "the robot can run but the WebUI cannot open," first confirm the port.
Master System Configuration
The master system is used to identify the "master" account of the framework (such as the bot administrator). master.users supports three writing methods:
[ErisPulse.master]
# Writing method one: global master (effective for all platforms, including newly added platforms)
users = ["123456", "789012"]
# Writing method two: specify master only per platform (dict)
# users = { yunhu = ["123456"], telegram = ["789012"] }
# Writing method three: global + platform-specific coexistence — the global key in dict is the global master bucket
# users = { global = ["123456"], yunhu = ["789012"] }
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| users | array / object | empty | List of master account IDs. list form is global master (effective for all platforms); dict form specifies per platform (key is platform name, global key is the global master bucket), value is the list of master account IDs for that platform |
Regarding new platforms: Both
listform andglobalbucket indictare "defined once, effective for all platforms," no need to modify the configuration when new platforms are added later; platform-specific entries only take effect for platforms with the same name (including prefix/wildcard tolerance).master.add(None, uid)persists to theglobalbucket, existing platform entries are unaffected.
In code, check using master.is_master(event) or master.is_master(platform, user_id), each call reads the configuration in real time (supports hot reload, no restart needed):
from ErisPulse.Core import master
if master.is_master(event):
await event.reply("Hello, Master")
Determination Chain and Runtime Add/Delete
The master determination chain is configuration master → runtime record → provider chain:
from ErisPulse.Core import master
master.is_master(event) # Determine from event
master.is_master("yunhu", "123") # Explicit determination
master.add("yunhu", "123") # Add at runtime (default persists; persist=False only in-memory)
master.remove("yunhu", "123") # Remove (default persists)
master.list() # Aggregate: {"global": [...], "<platform>": [...]}
Custom Identity Source (provider)
In addition to configuration, custom identity sources can be registered: fn(platform, user_id) -> bool, built-in identity sources (configuration + runtime record) are not matched, they are tried in sequence, and any provider that allows is recognized as the master. Suitable for connecting adapter administrator interfaces, database roles, and other external identity systems.
The registration entry master.provider supports both decorator and function-style writing, and unregistration is done through the unregistration function on the registered function:
from ErisPulse.Core import master
# Method one: decorator (recommended for persistent identity source)
@master.provider
def admin_provider(platform, user_id):
return user_id in {"999"} # Custom determination logic
master.is_master("yunhu", "999") # True
admin_provider.unregister() # Unregister when no longer needed
# Method two: function-style (register during module loading / unregister during unloading)
fn = master.provider(admin_provider)
fn.unregister()
Provider exceptions are caught and skipped, not blocking the identity determination chain. Binding instance methods cannot attach
unregister, for scenarios requiring paired registration/unregistration, use module-level functions.
User Priority: Master Effect Range is Ultimately Decided by the User
The master=True of a command is only a developer default: the user can override or tighten or loosen it in
ErisPulse.event.overrides.command.<module>.<cmd>.master = true/false (see Unified Event Override Configuration, user explicit configuration takes effect).
Logging Configuration
[ErisPulse.logger]
level = "INFO"
log_files = [] # Explicit list of log files (mutually exclusive with log_dir, higher priority)
log_dir = "" # Log directory (automatic segment rotation enabled)
log_rotation = "size" # Segmenting method: "size" / "date" / "none"
log_max_size_mb = 10 # Maximum size per file in size mode (MB)
log_backup_count = 5 # Number of historical log files to retain
log_rotation_when = "midnight" # Rotation cycle in date mode: S/M/H/D/midnight
memory_limit = 1000 # Maximum number of log entries per module in memory (0 = disable memory log copy)
total_memory_limit = 5000 # Total number of log entries across all modules in memory (0 = unlimited)
exclude_levels = ["EVENT"]
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| level | string | INFO | Log level: TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL (TRACE is the lowest level, outputs detailed internal debugging information) |
| format | string | rich | Log output format: rich (colored, default), plain (plain text without color, suitable for log collection/pipeline redirection), json (JSON structured, suitable for ELK, etc.) |
| log_files | array | empty | List of explicit log file paths (no segmentation) |
| log_dir | string | empty | Log output directory (automatically created). When set, logs are written into erispulse.log in the directory and segmented automatically based on log_rotation; mutually exclusive with log_files, log_files takes precedence |
| log_rotation | string | size | Segmentation method: size (by size) / date (by time) / none (no segmentation) |
| log_max_size_mb | float | 10 | Maximum file size in size mode (MB); when exceeded, the file rotates to .1/.2 backups |
| log_backup_count | integer | 5 | Number of historical log files to retain; oldest backups beyond this limit are automatically deleted |
| log_rotation_when | string | midnight | Rotation cycle in date mode: S/M/H/D/midnight (default is midnight each day) |
| memory_limit | integer | 1000 | Number of log entries saved in memory per module; 0 means disable memory log copy (no new entries are written to memory, but existing records are retained) |
| total_memory_limit | integer | 5000 | Total number of log entries across all modules in memory; 0 means unlimited. When exceeded, the oldest records are discarded according to the rotation policy (prioritizing modules with the most entries), independent of the single-module memory_limit |
| exclude_levels | array | empty | Levels to exclude. Logs of excluded levels are completely discarded (not written to memory, not pushed to Dashboard or other subscribers, not printed, not written to files). Supports hot update |
You can also dynamically switch in code:
from ErisPulse.Core import logger
# Segment by size: single file 10MB, retain 5 copies
logger.set_output_dir("logs", rotation="size", max_size_mb=10, backup_count=5)
# Segment by time: rotate at midnight daily, retain 7 copies
logger.set_output_dir("logs", rotation="date", backup_count=7)
Note
log_dir and related segmentation configurations require ErisPulse 2.8.0+.
Privacy Protection: Message send/receive content is logged at the EVENT level (value 21). Setting
exclude_levels = ["EVENT"]ensures that backend components (such as the Dashboard log panel) cannot see message content from groups or private chats, while not affecting logs of other levels.
In addition to configuration files (supporting hot updates), you can also switch at runtime using code—no need to write configuration when making management commands like /privacy on|off:
from ErisPulse import logger
logger.exclude_level("EVENT") # Temporarily exclude a log level at runtime (same semantics as exclude_levels configuration)
logger.allow_level("EVENT") # Restore this level
logger.list_excluded_levels() # View currently excluded levels
logger.set_format("json") # Switch output to JSON line protocol (same effect as format configuration key)
Note
The exclude_levels feature requires ErisPulse 2.8.0+.
Framework Configuration
[ErisPulse.framework]
enable_lazy_loading = true
uninit_timeout = 30
strict_mode = 0
[ErisPulse.framework.strict_mode_exceptions]
modules = []
adapters = []
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| enable_lazy_loading | boolean | true | Whether to enable module lazy loading |
| uninit_timeout | integer | 30 | Graceful shutdown total timeout (seconds), force termination after exceeding. 0 means no timeout set |
| strict_mode | integer | 0 | Strict mode level, see below "Strict Mode" explanation |
| handler_max_concurrency | integer | 64 | Maximum concurrent Task count for event handler, set larger to increase throughput but increase memory usage |
| handler_queue_max_pending | integer | 4096 | Event surge backpressure: maximum pending handler Task count per platform, new event Task is discarded and WARNING is recorded when exceeded (discard count can be checked in troubleshoot); 0 means unlimited |
| offline_bot_expiry | integer | 3600 | Automatic expiration time (seconds) for offline Bot records, 0 means never expire |
| plugins_dir | string / list | "plugins" | Local plugin folder (relative to project root); new/removed/modified plugin files are automatically discovered by hot reload watcher |
| watch_ignore_dirs | list | built-in list | Directories ignored by hot reload file monitoring (.venv/.git/__pycache__ etc.); non-empty list replaces built-in list, [] means ignore no directories |
| watch_include_plugin_dirs | boolean | true | Whether epsdk run --reload hands plugin directories over to plugin hot reload watcher for precise handling (single module reload), and excludes from full monitoring |
| event_dedupe | boolean | true | Event idempotent deduplication: duplicate event id only distributes once (repeated delivery from connection layer/retransmission from gateway) |
| cross_account_policy | string | "off" | Cross-account duplicate handling policy: when the same physical message is received by multiple accounts in sequence, the processing — off does not associate (events are distributed as usual); mark injects the top-level multi_receipt field (pointing to the first accepted event) after distribution, modules read this field to decide themselves; drop drops the copy at the distribution entrance (framework-level deduplication, modules are unaware) |
Proactive GC Configuration
After SDK initialization, a proactive GC background task is started, periodically executing Python GC and internal resource cleanup (offline Bot cleanup, etc.). All parameters support hot reload, and the task is restarted immediately when changed.
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| proactive_gc_interval | number | 300 | Recycling interval (seconds), supports decimal. 0 means disable proactive GC |
| proactive_gc_generation | integer | 0 | Regular round recycling generation (0/1/2, clamped to 0..2). Note gc.collect(2) is equivalent to full recycling, default 0 keeps lightweight; deep recycling is triggered periodically by proactive_gc_full_every |
| proactive_gc_full_every | integer | 20 | Full recycling every N rounds, 0 means disable periodic full recycling. Full recycling is constrained by the proactive_gc_memory_growth_mb threshold |
| proactive_gc_memory_growth_mb | integer | 32 | Full recycling memory growth threshold (MB): compared with the last full recycling's memory baseline (prioritizing tracemalloc, then RSS), full recycling is only executed when the growth reaches this value. 0 means no threshold |
| proactive_gc_idle_only | boolean | false | When enabled, Python GC is skipped in event surges (there are unfinished pending handlers), avoiding pauses and message processing competition; internal resource recycling is unaffected |
| proactive_gc_gen0_min | integer | 500 | Lower bound of garbage quantity for regular round recycling: gc.get_count()[0] below this value directly skips (empty round is almost zero overhead). 0 means always recycle |
2.7.1 Change: The default
proactive_gc_generationis adjusted from2to0, and the defaultproactive_gc_full_everyis adjusted from0to20. Previously,generation=2meant full recycling every round; the new default keeps recycling coverage while significantly reducing idle round overhead. Explicitly configured old values still take literal semantics.
Strict Mode
The strict mode controls the handling strategy for modules/adapters when they are not compliant or fail during the loading phase. Modern modules/adapters should inherit corresponding base classes (BaseModule/BaseAdapter); components that do not inherit base classes affect the framework's context system and fallback cleanup, potentially causing resource leaks.
2.5.2 Change: The default level is adjusted from
1(skip) to0(lenient), to reduce loading issues for new users. Components that do not inherit base classes are still attempted to load with a WARNING, rather than being directly rejected. To restore the previous behavior, explicitly setstrict_mode = 1.
| Level | Name | Behavior |
|---|---|---|
| 0 | Lenient (default) | Violations are only warned, components that do not inherit base classes are still attempted to load (compatibility with old components) |
| 1 | Strict-Skip | Reject components that do not inherit base classes and skip them, other normal startup |
| 2 | Strict-Fatal | Collect all violations and report them uniformly, then terminate the entire startup |
Under all levels, component self-crashes during the loading/registration/initialization phase are always skipped; the difference is:
- 0 → 1: The only behavioral change is that "not inheriting base class" changes from "still loaded" to "skipped."
- 1 → 2: All violations (not inheriting base class, loading failure, registration failure, initialization failure, etc.) are upgraded to fatal, collected at the startup checkpoint and reported as a violation list before termination.
Exception List
If certain components temporarily cannot migrate (for example, dependent on old modules), they can be added to the exception list. Components listed will be treated as lenient mode and continue loading even if they are non-compliant:
[ErisPulse.framework.strict_mode_exceptions]
modules = ["SeTu", "SomeLegacyModule"]
adapters = ["OldAdapter"]
When a component is rejected by strict mode, the log will clearly prompt how to resume loading (add to the exception list or lower the level).
Integration with CLI
The epsdk run startup pre-check (config file parseability, component required configuration completeness) defaults to follow this configuration: if not 0, check failure will refuse startup, 0 will only warn and continue. You can also temporarily switch without changing the configuration: epsdk run --strict will enable self-check and strict level for this run (level only increases, propagated to the running process via ERISPULSE_FRAMEWORK_STRICT_MODE environment variable), --no-strict temporarily lowers to lenient and only warns.
Storage Configuration
Since version 2.8.0, the storage engine supports three asynchronous backends, with completely consistent APIs and one-click configuration switching:
| Backend | Driver | Installation | Characteristics |
|---|---|---|---|
| SQLite (default) | aiosqlite | Ready-to-use out of the box | Zero configuration, single file, WAL concurrency |
| MySQL / MariaDB | aiomysql | pip install ErisPulse[mysql] |
Existing MySQL infrastructure, multi-instance sharing |
| PostgreSQL | asyncpg | pip install ErisPulse[postgres] |
Strong transaction capability, high concurrency |
[ErisPulse.storage]
backend = "sqlite" # "sqlite" (default) / "mysql" / "postgres"
use_global_db = false # Only for SQLite: use the global database data/config.db inside the package
[ErisPulse.storage.mysql] #生效 when backend = "mysql"
host = "127.0.0.1"
port = 3306
user = "erispulse"
password = ""
database = "erispulse"
# charset = "utf8mb4"
# pool_min = 1
# pool_max = 10
[ErisPulse.storage.postgres] #生效 when backend = "postgres"
host = "127.0.0.1"
port = 5432
user = "erispulse"
password = ""
database = "erispulse"
# pool_min = 1
# pool_max = 10
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| backend | string | sqlite | Storage backend: sqlite / mysql / postgres, switch with zero code changes |
| use_global_db | boolean | false | Only for SQLite: whether to use the global database inside the package rather than the project-specific database |
| storage.mysql.* | table | see above | MySQL connection parameters (host / port / user / password / database / charset / pool) |
| storage.postgres.* | table | see above | PostgreSQL connection parameters (host / port / user / password / database / pool) |
Environment variables are also supported for overriding (Docker / 12-factor): ErisPulse.storage.postgres.host → ERISPULSE_STORAGE_POSTGRES_HOST.
Tip
- Connection parameter changes require a framework restart to take effect; transient connection pool creation failures will automatically retry with exponential backoff
- Before switching backends, use a verification script to self-check:
python tests/devs/test_storage_backend_verify.py --backend mysql - Transactions / dialect differences / custom backends, etc., complete explanations are available at Storage Backends
Event Configuration
Command Configuration
[ErisPulse.event.command]
prefix = "/"
case_sensitive = true
allow_space_prefix = false
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| prefix | string | / | Command prefix |
| case_sensitive | boolean | true | Whether to distinguish case (/Help and /help are different commands) |
| allow_space_prefix | boolean | false | Whether to allow space as prefix |
| must_at_bot | boolean | false | Whether to require @bot to trigger command (private chat is not restricted) |
Message Configuration
[ErisPulse.event.message]
ignore_self = true
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| ignore_self | boolean | true | Whether to ignore the robot's own messages |
Event deduplication has three layers, each handling a different type of duplicate:
event_dedupe(framework, duplicate event ID) →ignore_self(this section, robot's own message) →cross_account_policy(framework, content-level duplicates from multiple accounts). The layered responsibilities are detailed in Adapter Core Concepts.
Session Inbox Configuration (transcript)
[ErisPulse.transcript]
enabled = true
max_per_session = 50
ttl_hours = 168.0
self_echo = "bot"
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| enabled | boolean | true | Whether to automatically record incoming/outgoing messages (after disabling, history can still be queried) |
| max_per_session | int | 50 | Number of entries retained per session (0 = disable session trimming) |
| ttl_hours | float | 168.0 | Global retention duration (hours, 0 = never clean up) |
| self_echo | string | bot | Incoming bot echo (if self.user_id == user_id, such as OneBot report-self-message) handling: bot = record as bot and mark meta.self_echo; skip = do not record; user = record as user (old behavior) |
The risks and audits of retention policies are detailed in Session Inbox; attribution fields (
sender/meta) and outbound ownership (meta.module) are also detailed in that document.
Internationalization Configuration
[ErisPulse.i18n]
language = "auto"
| Configuration Item | Type | Default Value | Description |
|---|---|---|---|
| language | string | auto | The display language for framework-built-in text. Set to auto to automatically detect the system language, or set to a specific code: zh-CN, zh-TW, en, ja, ru |
Module Configuration
Each module can define its own configuration in the configuration file:
[MyModule]
api_url = "https://api.example.com"
timeout = 30
enabled = true
In the module, read and write configuration:
from ErisPulse import sdk
# Read configuration
config = sdk.config.getConfig("MyModule", {})
api_url = config.get("api_url", "https://default.api.com")
# Write configuration at runtime (delayed save)
sdk.config.setConfig("MyModule.timeout", 60)
# Save immediately to file
sdk.config.setConfig("MyModule.timeout", 60, immediate=True)
setConfigdefaults to delayed writing (about every 5 seconds batched to file), setimmediate=Trueto save immediately. Configuration changes trigger theconfig.setlifecycle event.
Scope Configuration (scope)
Note
This feature requires ErisPulse 2.8.0+.
Scope declares "within what range it takes effect" — which modules are available in a platform/Bot/session (① module dimension), which events are received by a user/group/Bot/adapter (② identity dimension), and which outbound calls a module can initiate (③ outbound dimension):
[ErisPulse.scope]
default_allow = true # Global default (false = implicit deny strict mode; does not affect outbound dimension)
cache_size = 1024 # LRU cache size
# ① Module dimension (priority: session > Bot > platform; entries support exact / glob / re: regex)
[ErisPulse.scope.platforms.onebot11]
modules = ["Chat", "Tool*"]
blocked = ["re:^Danger"]
# Sub-level binding with merge = true merges with lower priority entries (default is overall overwrite)
[ErisPulse.scope.bots.onebot11."123456"]
modules = ["Music"]
merge = true
# ② Identity dimension (priority: user > session > Bot > adapter; each level only allows or denies one)
[ErisPulse.scope.identity.adapters.onebot11]
deny = true # All events of this platform are discarded at the entry
[ErisPulse.scope.identity.users.onebot11]
allow = ["u_admin"] # User keys support glob / re: regex
deny = ["u_bad", "spam_*"]
# ③ Outbound dimension (default allows all; rules are inline tables, entries support exact / glob / re: regex)
[ErisPulse.scope.actions.MyModule]
send = { deny = true } # Deny all sending
api = { allow = ["get_*"] } # Allow only standard query APIs
request = { deny = true } # Deny request handling
| Configuration Item | Type | Description |
|---|---|---|
scope.default_allow |
boolean | Global default: allow/deny for modules/identity not matched by rules (true) |
scope.cache_size |
integer | LRU cache size (default 1024) |
scope.platforms / bots / sessions |
table | ① Module three-level binding: {modules=[...], blocked=[...], merge=bool?} |
scope.identity.adapters / bots / sessions / users |
table | ② Identity four-level binding: {allow=true} / {deny=true} |
scope.actions.<module>.<action> |
table | ③ Outbound rules: `{allow=[...], deny=true |
Detailed explanation and runtime API (dimensional
sdk.scope.set_module()/set_identity()/set_action(), determinationis_allowed()/is_identity_allowed()/is_action_allowed(), and dictionary-style fallbackget()/set()/delete()) are available in Scope (scope).
Unified Event Override Configuration (event.overrides)
Unified override system: Override behavior of any module processor by event type without modifying module code. OneBot12 standard types (meta / message / notice / request) and extended types (command) each have their own overridable parameters:
[ErisPulse.event.overrides]
# message: text trigger conditions (AND with code-level conditions)
[ErisPulse.event.overrides.message.ChatModule]
pattern = "闲聊*"
# notice / request / meta: detail_type whitelist (entries support exact / glob / re: regex)
[ErisPulse.event.overrides.notice.MyModule]
detail_types = ["group_increase"]
# command (extended type): implement parameter override (user priority; disable via acl deny)
[ErisPulse.event.overrides.command.MyModule.restart]
master = true # Override to only allow framework master (false opens developer's master restriction)
hidden = true # Hide in help list
aliases = ["rs"] # Effective alias
# acl (command exclusive): user whitelist/blacklist for commands (command names support glob / re: regex, exact keys take precedence)
[ErisPulse.event.overrides.acl."roll*"]
allow = ["onebot11:u_vip"] # User identifier "platform:user_id"
deny = ["onebot11:u_bad"]
# ACL default: allow (true) / strictly deny (false) commands without ACL configuration
acl_default_allow = true
| Configuration Item | Type | Description |
|---|---|---|
event.overrides.message.<module> |
table | Text condition: {pattern="...", regex="..."} |
event.overrides.notice / request.<module> |
table | {detail_types=[...], pattern, regex} |
event.overrides.meta.<module> |
table | {detail_types=[...]} |
event.overrides.command.<module> |
table | Module-level parameter override (scalar flags like hidden = true) |
event.overrides.command.<module>.<command> |
table | Command-level override (command-level takes precedence) |
event.overrides.acl.<command name> |
table | User whitelist/blacklist: {allow=[...], deny=[...]} |
event.overrides.acl_default_allow |
boolean | ACL default: allow commands without ACL configuration (true) / strictly deny (false) |
Runtime API (after
from ErisPulse.Core.Event import overrides, calloverrides.message.set()/overrides.command.set()/overrides.acl.set()by type sub-namespace, or access viasdk.Event.overrides) is available in Event Handling Introduction · Event Override.
Next Steps
- Continue following the L1 path: Next article Exception Handling, learn how to write error handling that does not crash the framework
- Don't want to write TOML manually: Use
epsdk configinteractive wizard to fill in declarative configuration items, see CLI Commands Reference · config - Don't want to modify configuration file during deployment: Use environment variables to override configuration items, combined with the Deployment Guide for Docker usage