Errbot 6.2.1 配置参数详解

目标：逐项讲清 Errbot 6.2.1 主配置文件 config.py 的全部参数（默认值、取值、改动影响），并给出生产可用配置模板。本文参数清单以安装包内官方 config-template.py（402 行）为取证依据，关键改动均在 Ubuntu 22.04 + Python 3.10.12 + Errbot 6.2.1 环境实测验证。

一、环境信息

操作系统：Ubuntu 22.04 LTS（Jammy）
Python 版本：3.10.12
Errbot 版本：6.2.1（pip 安装于虚拟环境 /opt/errbot/venv）
机器人工作目录：/opt/errbot/bot（含 config.py、data/、plugins/、backend-plugins/）
官方完整配置模板：/opt/errbot/venv/lib/python3.10/site-packages/errbot/config-template.py（实测 402 行）

二、前置条件

已完成 Errbot 安装与初始化（errbot --init /opt/errbot/bot），安装全流程见《Ubuntu 22.04 安装 Errbot 6.2.1 指南》。
以下命令均在机器人停止运行或修改后重启的前提下执行；Errbot 只在启动时读取一次 config.py，运行中改配置不会生效。

三、参数查看与修改方式

3.1 config.py 是什么

Errbot 的全部配置集中在一个普通 Python 文件 config.py 中：参数即模块级变量，可以用 Python 语法做变量复用与运算（例如 BOT_LOG_FILE = BOT_DATA_DIR + "/err.log"）。这也意味着：

字符串、元组、字典必须遵循 Python 语法；
多项参数（如 BOT_ADMINS）必须是元组，单元素时尾随逗号不可省：("@admin",) 合法，("@admin") 是字符串会报错。

3.2 找到并复制官方完整模板

errbot --init 生成的 config.py 只有 7 行核心配置（最小可用）。完整参数清单在安装包内的 config-template.py：

执行命令：

find /opt/errbot/venv -name "config-template.py"
wc -l /opt/errbot/venv/lib/python3.10/site-packages/errbot/config-template.py

执行结果：

/opt/errbot/venv/lib/python3.10/site-packages/errbot/config-template.py
402 /opt/errbot/venv/lib/python3.10/site-packages/errbot/config-template.py

需要某组参数时，从该模板中复制对应段落到自己的 config.py 再改值即可，不要整文件覆盖（模板中 BOT_DATA_DIR = "/var/lib/err" 等默认值需要按实际改）。

3.3 指定其他配置文件路径

默认 errbot 读取当前工作目录下的 config.py，可用 -c 指定其他路径：

errbot -c /opt/errbot/bot/config.py

⚠️ 注意：在没有 config.py 的目录直接执行 errbot 会报错 I cannot find the config file //config.py. You can change this path with the -c parameter see --help——先 cd 到机器人目录或用 -c 显式指定。

3.4 修改后重启并验证生效

修改 config.py 后必须重启 errbot 进程（systemctl restart errbot 或重新前台执行）。验证方式以 BOT_PREFIX 为例：把前缀从默认 ! 改为 ? 后启动 Text 会话，实测 ?echo bbb 正常回显、!echo aaa 不再有响应：

[@CHANGE_ME ➡ @errbot] >>> bbb        ← ?echo bbb 的回复
[@CHANGE_ME ➡ @errbot] >>>            ← !echo aaa 无回复（前缀已换）

✅ 验证通过：配置改动在重启后生效，命令前缀由 ! 切换为 ?。

四、参数总览

官方 config-template.py 共 402 行，参数按功能分九组，总览如下：

参数组	代表参数	作用域
核心	`BACKEND`、`STORAGE`、`BOT_DATA_DIR`	聊天后端、持久化、数据目录
插件与仓库	`BOT_PLUGIN_INDEXES`、`BOT_EXTRA_PLUGIN_DIR`、`CORE_PLUGINS`、`AUTOINSTALL_DEPS`	插件来源与加载
日志	`BOT_LOG_FILE`、`BOT_LOG_LEVEL`、`BOT_LOG_SENTRY` 系列	日志落盘与上报
异步执行	`BOT_ASYNC`、`BOT_ASYNC_POOLSIZE`	命令并发模型
身份与聊天室	`BOT_IDENTITY`、`BOT_ADMINS`、`CHATROOM_PRESENCE`、`CHATROOM_FN`	平台凭据、管理员、房间
命令前缀	`BOT_PREFIX`、`BOT_ALT_PREFIXES` 等 5 项	命令触发方式
访问控制与分流	`ACCESS_CONTROLS`、`HIDE_RESTRICTED_`、`DIVERT_TO_`、`_RELAY`	ACL 与消息路由
后端专属	`XMPP_`（5 项）、`IRC_`（5 项）	XMPP/IRC 协议细节
杂项	`MESSAGE_SIZE_LIMIT`、`COMPACT_OUTPUT`、`SUPPRESS_CMD_NOT_FOUND` 等	消息与输出行为

五、核心与存储参数

本组决定机器人「连哪个聊天平台、数据存哪」，是每次部署必改的参数。

5.1 BACKEND —— 聊天后端

BACKEND = "Text"   # 默认 Text（本地控制台，开发调试用）

可选值与适用场景（errbot -l 实测列出内置后端，更多经 pip extras 提供）：

后端	类型	说明
`Text`	调试	本地控制台交互，零依赖，插件开发与演示首选
`Test` / `Null`	调试	单元测试 / 无交互场景
`Slack`	商业平台	需 `pip install "errbot[slack]"`，凭据用 `token`
`IRC`	开放协议	需 `errbot[irc]`，支持 SSL/nickserv
`XMPP`	开放协议	需 `errbot[xmpp]`
`Telegram`	商业平台	需 `errbot[telegram]`
`Gitter` / `TOX` / `Discord` / `Mattermost`	第三方后端	由独立后端插件提供（`err-backend-gitter` 等）

💡 技术拓展：ChatOps 机器人的「后端适配层」是 Errbot 的核心设计——业务插件只面向统一的消息 API，切换聊天平台只需改 BACKEND + BOT_IDENTITY，插件零改动。同类框架中 Hubot 叫 Adapter、Lita 叫 Handler/Adapter，思路一致。本文默认采用 Text 后端做演示，接入真实平台时按上表选择。

5.2 STORAGE —— 持久化存储

STORAGE = "Shelf"   # 默认，Python shelf 文件存储

取值	说明
`Shelf`	默认。每插件一个 `.db` 文件落在 `BOT_DATA_DIR`，重启不丢
`Memory`	纯内存，进程退出即清空，仅用于测试

插件的键值数据（如 !plugin config 写入的配置）都存在这里；生产也可通过 BOT_EXTRA_STORAGE_PLUGINS_DIR（默认 None）挂载自研存储插件（如对接 Redis/MySQL）。

5.3 BOT_DATA_DIR —— 数据目录

BOT_DATA_DIR = "/opt/errbot/bot/data"   # 模板默认 /var/lib/err，必须改为机器人可写目录

存放 Shelf 数据文件与备份文件。实测该目录内容：

ACLs.db.db  Backup.db.db  ChatRoom.db.db  CommandNotFoundFilter.db.db
Example.db.db  Flows.db.db  Health.db.db  HelloWorld.db.db  Help.db.db
Plugins.db.db  TextCmds.db.db  Utils.db.db  Webserver.db.db  core.db.db
plugins/  repomgr.db.db  text_backend.db.db

⚠️ 注意：运行 errbot 的用户必须对该目录有写权限，否则启动报权限错误；备份服务器时备份此目录即可保全机器人状态。

六、插件与仓库参数

本组控制插件从哪来、加载哪些、依赖是否自动安装。

参数	默认值	说明
`BOT_PLUGIN_INDEXES`	`"https://errbot.io/repos.json"`	插件索引源（`!repos` 列表来源）。可换本地文件路径或元组多源；多源时同名插件只取第一个命中
`BOT_EXTRA_PLUGIN_DIR`	`None`	本地插件开发目录（`--init` 默认设为 `<bot>/plugins`），只支持单个目录，可在其下建子目录放多个插件
`BOT_EXTRA_BACKEND_DIR`	`None`	第三方后端插件目录（`--init` 默认 `<bot>/backend-plugins`）
`CORE_PLUGINS`	`None`（加载全部内置插件）	只加载指定内置插件，如 `("ACLs", "Backup", "Help")`；置 `()` 则一个内置插件都不加载
`PLUGINS_CALLBACK_ORDER`	`(None,)`	插件回调顺序。`None` 代表「其余全部」，如 `("A", None, "B")` 表示 A 最先、B 最后
`AUTOINSTALL_DEPS`	`True`	自动用 pip 安装插件 `requirements.txt`；虚拟环境内等价 `pip install -r`，否则 `--user` 安装

💡 说明：内网离线环境建议把 BOT_PLUGIN_INDEXES 指向内部索引文件，并设 AUTOINSTALL_DEPS = False 改由人工预装依赖，避免机器人运行时出网。

七、日志参数

BOT_LOG_FILE = BOT_DATA_DIR + "/err.log"   # 置 None 则只输出到控制台
BOT_LOG_LEVEL = logging.INFO                # DEBUG/INFO/WARN/ERROR

BOT_LOG_FORMATTER（默认内置）：自定义 logging.Formatter 实例，改日志格式。
Sentry 上报组（默认全部关闭）：BOT_LOG_SENTRY = False、BOT_LOG_SENTRY_FLASK = False（单独上报 Webserver 插件的 Flask 异常）、SENTRY_DSN = ""、SENTRY_LOGLEVEL/SENTRY_EVENTLEVEL（默认跟随 BOT_LOG_LEVEL）、SENTRY_OPTIONS = {}（透传给 sentry_sdk.init()，如 {"environment": "production"}，DSN 只能走 SENTRY_DSN）。

💡 说明：排障时先把 BOT_LOG_LEVEL 调到 logging.DEBUG，官方也要求提 issue 时附 DEBUG 日志。

八、异步执行参数

BOT_ASYNC = True          # 默认开：命令在线程池中异步执行，互不阻塞
BOT_ASYNC_POOLSIZE = 10   # 线程池大小

BOT_ASYNC = True 时单条慢命令（如调外部 API）不会卡住其他命令；插件内部若依赖执行顺序可声明同步。池大小按并发命令量调，10 人以内团队默认 10 足够。

九、身份与聊天室参数

9.1 BOT_IDENTITY —— 平台凭据（按后端选键）

BOT_IDENTITY = {
    "username": "@errbot",   # Text 模式：机器人显示名
    # XMPP:  "username": "err@localhost", "password": "...", "server": ("host", 5222)
    # Slack: "token": "xoxb-...", "proxies": {"http": "...", "https": "..."}
    # Telegram: "token": "103419016:AAbcd1234..."
    # IRC:   "nickname": "err-chatbot", "username": "...", "password": None,
    #        "server": "irc.example.net", "port": 6667, "ssl": False, "ipv6": False,
    #        "nickserv_password": None, "bind_address": ("localhost", 0)
}

各后端键不同、同一字典内只保留当前后端需要的键。第三方平台 token 属系统级密钥，建议通过 CI 注入生成 config.py，勿提交到公开仓库。

9.2 BOT_ADMINS —— 管理员

BOT_ADMINS = ("@admin",)             # 元组，尾随逗号不可省
BOT_ADMINS_NOTIFICATIONS = ()        # 接收管理通知的管理员子集

支持 Unix glob："*@localhost" 表示该域所有用户都是管理员。!plugin config、!repos install 等管理命令仅管理员可用。

9.3 聊天室

CHATROOM_PRESENCE = ("#ops",)                  # 启动自动加入的房间；XMPP 密码房用 (房间, 密码) 元组
CHATROOM_FN = "Errbot"                         # 机器人在房间里的昵称（部分 XMPP 实现对昵称挑剔）

十、命令前缀参数

本组控制用户如何「喊」机器人执行命令。

BOT_PREFIX = "!"                              # 命令前缀，默认 !
BOT_PREFIX_OPTIONAL_ON_CHAT = False           # True 后私聊（非 MUC）可省略前缀
BOT_ALT_PREFIXES = ("Err",)                   # 备用呼名前缀
BOT_ALT_PREFIX_SEPARATORS = (":", ",", ";")   # 呼名与命令间允许的分隔符，如 "Err, status"
BOT_ALT_PREFIX_CASEINSENSITIVE = True         # 呼名大小写不敏感："Err"/"err"/"ERR" 均可

⚠️ 注意：改 BOT_PREFIX 后 help 文本会自动适配新前缀；但写插件时一律按默认 ! 写文档串，不要硬编码当前前缀。生效验证见 3.4 实测。

十一、访问控制与消息分流参数

11.1 ACCESS_CONTROLS —— 命令级 ACL

ACCESS_CONTROLS_DEFAULT = {}          # 默认规则（{} = 全放行），与下方规则合并
ACCESS_CONTROLS = {
    "uptime": {"allowusers": BOT_ADMINS},
    "about": {"denyusers": ("*@evilhost",),
              "allowrooms": ("room1@conference.localhost",)},
    "ChatRoom:*": {"allowusers": BOT_ADMINS},   # 插件名:命令 粒度，支持 glob
}

可用过滤器（省略或置 None 即不启用）：allowusers / denyusers / allowrooms / denyrooms / allowargs / denyargs（用户/房间支持 glob）、allowprivate（允许私聊使用）、allowmuc（允许房间内使用）。规则按首个命中生效，模式有重叠时用 OrderedDict 固定顺序。

11.2 受限命令的可见性

HIDE_RESTRICTED_COMMANDS = False：置 True 后，无权命令从 !help 输出中隐藏。
HIDE_RESTRICTED_ACCESS = False：置 True 后，无权用户触发命令时机器人静默不回复（默认回错误提示）。

11.3 消息分流与房间转发

DIVERT_TO_PRIVATE = ()：列出的命令（如 ("help", "about", "status")，或 "ALL_COMMANDS"）即使在群里触发也私聊回复。
DIVERT_TO_THREAD = ()：后端支持时，列出的命令在线程内回复。
CHATROOM_RELAY = {}：把指定用户的私聊消息转发到房间（如 Jira 通知器不支持 MUC 的场景），例：{"gbin@localhost": ("#ops",)}。
REVERSE_CHATROOM_RELAY = {}：反向——把房间消息转发给指定用户。

十二、后端专属与杂项参数

12.1 XMPP 专属（5 项）

参数	默认值	说明
`XMPP_CA_CERT_FILE`	`/etc/ssl/certs/ca-certificates.crt`	TLS 证书校验 CA 文件；置 `None` 关闭校验（自签名场景）
`XMPP_FEATURE_MECHANISMS`	`{}`（都尝试）	限定认证机制，兼容有 bug 的 XMPP 服务端，如只允许明文 PLAIN
`XMPP_KEEPALIVE_INTERVAL`	`300`（秒）	TCP 保活空白包间隔；NAT 后频繁掉线就逐步调小
`XMPP_USE_IPV6`	`False`	是否启用 IPv6
`XMPP_XHTML_IM`	`False`	XEP-0071 富文本格式，客户端支持参差故默认关

12.2 IRC 专属（5 项）

参数	默认值	说明
`IRC_CHANNEL_RATE` / `IRC_PRIVATE_RATE`	`1`（秒）	频道/私聊消息限速，置 `0` 关闭限速
`IRC_RECONNECT_ON_KICK`	`5`（秒）	被踢后重进延迟；置 `None` 不重进
`IRC_RECONNECT_ON_DISCONNECT`	`5`（秒）	掉线重连延迟
`IRC_ACL_PATTERN`	`"{nick}!{user}@{host}"`	ACL 匹配用的用户标识格式，变量 `{nick}`/`{user}`/`{host}`

12.3 杂项（4 项）

MESSAGE_SIZE_LIMIT = 10000：单条消息最大字符数，超长自动拆分多条发送。
GROUPCHAT_NICK_PREFIXED = False：置 True 后房间内回复会 @ 触发者。
COMPACT_OUTPUT：置 True 去掉表格边框（目前仅 IRC/Slack/Telegram 支持）。
TEXT_DEMO_MODE = False：置 True 后 Text 后端只输出彩色正文、不输出日志行（演示用）。
SUPPRESS_CMD_NOT_FOUND = False：置 True 后未识别命令不再提示。

十三、生产配置模板

适用场景：8GB 内存 VPS、单实例接入内部 IRC 服务器、仅管理员可用管理命令、日志落盘。按此模板改凭据即可投产：

import logging

# 核心
BACKEND = "IRC"
STORAGE = "Shelf"
BOT_DATA_DIR = r"/opt/errbot/bot/data"
BOT_EXTRA_PLUGIN_DIR = r"/opt/errbot/bot/plugins"
BOT_EXTRA_BACKEND_DIR = r"/opt/errbot/bot/backend-plugins"

# 身份（示例演示账号，生产按实际平台账号替换）
BOT_IDENTITY = {
    "nickname": "opsbot",
    "username": "opsbot",
    "password": "q1w2e3r4",
    "server": "irc.internal.example.com",
    "port": 6697,
    "ssl": True,
    "nickserv_password": "q1w2e3r4",
}
BOT_ADMINS = ("admin!*@*.internal.example.com",)
CHATROOM_PRESENCE = ("#ops",)
CHATROOM_FN = "OpsBot"

# 前缀
BOT_PREFIX = "!"
BOT_ALT_PREFIXES = ("opsbot",)
BOT_ALT_PREFIX_CASEINSENSITIVE = True

# 日志
BOT_LOG_FILE = r"/opt/errbot/bot/errbot.log"
BOT_LOG_LEVEL = logging.INFO

# 安全：管理类插件仅管理员可用，help 私聊回复
ACCESS_CONTROLS = {
    "ChatRoom:*": {"allowusers": BOT_ADMINS},
    "Plugins:*": {"allowusers": BOT_ADMINS},
}
DIVERT_TO_PRIVATE = ("help",)

# 异步与消息
BOT_ASYNC = True
BOT_ASYNC_POOLSIZE = 10
MESSAGE_SIZE_LIMIT = 10000

要点解读：管理命令收敛到 BOT_ADMINS；IRC 用 SSL 6697 并配 nickserv；help 私聊回复避免刷屏；数据、插件、日志统一在 /opt/errbot/bot 下便于备份。

十四、常见问题

Q1：改了 config.py 但行为没变？

Errbot 只在启动时读一次配置，必须重启进程。另外确认启动时的工作目录或 -c 指向的是你改的那个 config.py——在错误目录启动会读到另一份配置（或直接报找不到配置）。

Q2：BOT_ADMINS = ("@admin") 启动报错？

少尾随逗号，("@admin") 是字符串不是元组，遍历时会逐字符匹配。正确写法 ("@admin",)。

Q3：想完全离线运行，插件索引怎么指？

把 repos.json 下载到本地后 BOT_PLUGIN_INDEXES = "/opt/errbot/repos.json"，并设 AUTOINSTALL_DEPS = False，插件仓库用 !repos install <内网 git 地址> 安装。

Q4：XMPP 机器人在 NAT 后面频繁掉线？

把 XMPP_KEEPALIVE_INTERVAL 从默认 300 秒逐步调小（如 120、60），直到不再掉线——NAT 会话老化快于默认保活间隔所致。

Q5：Slack token 等凭据不想写死在文件里？

config.py 是 Python 文件，可用 import os; BOT_IDENTITY = {"token": os.environ["SLACK_BOT_TOKEN"]} 从环境变量读取；注意 ${VAR} 语法在 Python 文件里不生效，必须用 os.environ。

十五、参考链接

官方配置模板（6.2.1 同源）：https://github.com/errbotio/errbot/blob/master/errbot/config-template.py
Errbot 官方用户指南（配置章节）：https://errbot.io/en/latest/user_guide/configuration.html
Errbot 官方文档：https://errbot.io/en/latest/
安装与初始化见《Ubuntu 22.04 安装 Errbot 6.2.1 指南》