Errbot 6.2.1 常用 CLI 命令与工具详解

Errbot 6.2.1 命令行工具全选项实测详解（--init/--list/--text/--daemon/--pidfile/--restore/--storage-get/set/merge/--new-plugin），含 pip extras 后端管理、Text 会话内管理命令、守护进程与备份恢复的实测排障记录

ErrbotErrbotChatOps自动化运维2026/10/25

Errbot 6.2.1 常用 CLI 命令与工具详解

目标：逐选项讲清 Errbot 6.2.1 的 errbot 命令行工具（13 个选项全覆盖），以及配套的 pip 后端/插件依赖管理与会话内管理命令。本文全部命令与回显均在 Ubuntu 22.04 + Python 3.10.12 + Errbot 6.2.1 环境实测，输出逐行照抄。

一、环境信息

二、工具概览

Errbot 的命令行入口只有一个 errbot 命令，按用途分五组：

组选项用途
总览-h/--help、-v/--version帮助与版本
准备-i/--init、--new-plugin、-l/--list初始化机器人目录、生成插件骨架、列后端
运行直接 errbot、-c、--text、-d/--daemon、-p/--pidfile前台/守护方式启动
数据--storage-get/set/merge、-r/--restore存储读写与备份恢复
配套pip install "errbot[...]"安装聊天后端 extras 与插件依赖

三、前置条件

已安装 Errbot 并激活虚拟环境（下文命令中 errbot 即 /opt/errbot/venv/bin/errbot）：

source /opt/errbot/venv/bin/activate
errbot --version

Errbot version 6.2.1

四、帮助总览：errbot --help

先看官方帮助全文，建立选项地图（实测回显，逐行照抄）：

执行命令：

errbot --help

执行结果：

usage: errbot [-h] [-c CONFIG] [-v | -r [RESTORE] | -l | --new-plugin
              [NEW_PLUGIN] | -i [INIT] | --storage-set STORAGE_SET |
              --storage-merge STORAGE_MERGE | --storage-get STORAGE_GET | -T]
              [-d] [-p PIDFILE]

The main entry point of the errbot.

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Full path to your config.py (default: config.py in
                        current working directory).
  -v, --version         show program's version number and exit
  -r [RESTORE], --restore [RESTORE]
                        restore a bot from backup.py (default: backup.py from
                        the bot data directory)
  -l, --list            list all available backends
  --new-plugin [NEW_PLUGIN]
                        create a new plugin in the specified directory
  -i [INIT], --init [INIT]
                        Initialize a simple bot minimal configuration in the
                        optionally given directory (otherwise it will be the
                        working directory). This will create a data
                        subdirectory for the bot data dir and a plugins
                        directory for your plugin development with an example
                        in it to get you started.
  --storage-set STORAGE_SET
                        DANGER: Delete the given storage namespace and set the
                        python dictionary expression passed on stdin.
  --storage-merge STORAGE_MERGE
                        DANGER: Merge in the python dictionary expression
                        passed on stdin into the given storage namespace.
  --storage-get STORAGE_GET
                        Dump the given storage namespace in a format
                        compatible for --storage-set and --storage-merge.
  -T, --text            force local text backend

optional daemonization arguments:
  -d, --daemon          Detach the process from the console
  -p PIDFILE, --pidfile PIDFILE
                        Specify the pid file for the daemon (default: current
                        bot data directory)

要点解读：

  • -v/-r/-l/--new-plugin/-i/--storage-*/-T 互斥（usage 中的 |），一次只能做一件事；
  • -c 默认读当前目录的 config.py；-p 的 pidfile 默认落在机器人 data 目录；
  • --storage-set/merge 从 stdin 读 Python 字典表达式，选项说明里自带 DANGER 警示（会直接改存储）。

五、版本与后端清单

5.1 errbot --version / -v

执行命令：

errbot --version

执行结果：

Errbot version 6.2.1

5.2 errbot -l / --list —— 列出可用聊天后端

执行命令：

cd /opt/errbot/bot
errbot -l

执行结果：

Available backends:
	Test
	Text
	XMPP
	IRC
	Telegram
	Null
	SlackV3

解读：列出的是当前环境已装依赖后可加载的后端——XMPP/IRC/Telegram 因安装了对应 extras 而出现，SlackV3 来自 errbot[slack]；基础安装只有 Test/Text/Null。注意 -l 需要在含 config.py 的目录执行，否则报 I cannot find the config file //config.py. You can change this path with the -c parameter see --help。

六、初始化机器人目录：errbot --init

在指定目录生成最小可用机器人（config.py + data/plugins/backend-plugins 子目录）。

执行命令：

mkdir -p /opt/errbot/bot2
errbot --init /opt/errbot/bot2
ls -la /opt/errbot/bot2

执行结果：

Your Errbot directory has been correctly initialized!
Just do "errbot" and it should start in text/development mode.

total 24
drwxr-xr-x 5 root root 4096 Oct 25 06:57 .
drwxr-xr-x 3 root root 4096 Oct 25 06:57 ..
drwxr-xr-x 2 root root 4096 Oct 25 06:57 backend-plugins
-rw-r--r-- 1 root root  780 Oct 25 06:57 config.py
drwxr-xr-x 2 root root 4096 Oct 25 06:57 data
drwxr-xr-x 3 root root 4096 Oct 25 06:57 plugins

⚠️ 注意：目标目录必须预先存在。对不存在的目录执行会实测报错（exit=1）：

Target directory /xxx/botdir must exist. Please create it.
The initialization of your errbot directory failed: [Errno 2] No such file or directory: '/xxx/botdir/data'.

生成的 config.py 仅 780 字节，是 Text 后端最小配置（BACKEND = "Text"、BOT_ADMINS = ("@CHANGE_ME",) 等）；接入真实聊天平台时按《Errbot 6.2.1 配置参数详解》补 BOT_IDENTITY。

七、启动机器人

7.1 前台启动（默认读当前目录 config.py）

执行命令：

cd /opt/errbot/bot
errbot

执行结果（启动横幅，节选）：

2026-10-25 06:57:49,327 INFO     errbot.bootstrap          Found Storage plugin: Shelf.
2026-10-25 06:57:49,331 INFO     errbot.bootstrap          Found Backend plugin: Text
2026-10-25 06:57:49,449 INFO     errbot                    webhooks: Flag to bind /echo to echo
────────────────────────────────────────────────────────────────────────────────
 You start as a bot admin in a one-on-one conversation with the bot.
...
• Use !ml to flip on/off the multiline mode (Enter twice at the end to send).
────────────────────────────────────────────────────────────────────────────────

BACKEND = "Text" 时进入本地控制台会话，直接输入 !about、!echo hello 即可对话；Ctrl+C 优雅退出。

7.2 -c 指定配置文件

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

不在机器人目录时使用，常用于 systemd 单元 ExecStart。

7.3 -T / --text 强制 Text 后端

无论 config.py 里 BACKEND 配的是什么，-T 都强制用本地 Text 后端启动——生产配置出问题时用它快速本地验证插件，无需改配置。

⚠️ 注意：-T 不带参数，errbot -T Text 会实测报错 errbot: error: unrecognized arguments: Text（exit=2）。后端取值写在 config.py 的 BACKEND，不是 -T 的参数。

八、守护进程模式：-d 与 -p

errbot -d -p /run/errbot/errbot.pid
  • -d/--daemon：脱离控制台后台运行（内部用 daemonize 实现）；
  • -p/--pidfile：指定 pid 文件，缺省落在机器人 data 目录。

实测现象（Text 后端下）：命令 exit=0、pidfile 生成（2 字节），日志停在 Found Backend plugin: Text——随后进程因 stdin EOF 立即退出（Text 后端从标准输入读命令，守护进程没有 stdin）。所以：

⚠️ 注意：-d 只对真实聊天后端（IRC/XMPP/Slack 等）有意义；Text 后端请前台跑或交给 systemd。生产托管更推荐 systemd 而非 -d（可自动拉起、统一日志），systemd 单元写法见《Ubuntu 22.04 安装 Errbot 6.2.1 指南》。

九、存储管理：--storage-get / --storage-set / --storage-merge

Errbot 把每个插件的键值数据存在 Shelf 存储里（按插件命名空间隔离），这三个选项用于停机状态下从命令行直接读写，常用于排障与数据迁移。

9.1 --storage-get 读命名空间

执行命令：

cd /opt/errbot/bot
errbot --storage-get Webserver

执行结果：

{}

未配置过的插件命名空间为空字典。输出格式与 --storage-set/--storage-merge 的输入兼容，可直接做导出/导入。

9.2 --storage-set 整体覆盖（DANGER）

从 stdin 读 Python 字典表达式，先删除该命名空间再写入：

执行命令：

echo '{"env": "prod", "retry": 3}' | errbot --storage-set Health
errbot --storage-get Health

执行结果：

{'retry': 3, 'env': 'prod'}

9.3 --storage-merge 合并写入

执行命令：

echo '{"region": {"zone": "a"}}' | errbot --storage-merge Health
errbot --storage-get Health

执行结果：

{'region': {'zone': 'a'}, 'retry': 3, 'env': 'prod'}

解读：merge 只新增键、不覆盖已有键（retry 仍为 3）；适合补字段。要改已有键的值用 --storage-set 重写整个命名空间。

⚠️ 注意：机器人运行中存储被独占打开，另起的 CLI 进程执行 storage 操作会报 Storage does not appear to have been opened yet——先停机器人再操作。

十、备份与恢复：!backup 与 -r/--restore

10.1 生成备份（会话内命令）

在机器人会话中执行 !backup（Backup 核心插件，仅管理员）：

[@CHANGE_ME ➡ @errbot] >>> The backup file has been written in "/opt/errbot/bot/data/backup.py".

实测文件：

-rw-r--r-- 1 root root 14348 Oct 25 06:58 /opt/errbot/bot/data/backup.py

backup.py 是一个 Python 脚本，内容是把仓库列表、插件配置、各插件存储逐一写回的语句（首行注释也写明：This file is not executable on its own. use errbot -r FILE to restore your bot.）。

10.2 恢复：errbot -r

在新机器人目录执行：

mkdir -p /opt/errbot/bot3
errbot --init /opt/errbot/bot3
cd /opt/errbot/bot3
errbot -r /opt/errbot/bot/data/backup.py

恢复过程日志以 **** RESTORING the bot from ... 开头，依次恢复 repo_manager、插件配置与存储。文件缺省时默认读 data 目录下的 backup.py（errbot -r）。

⚠️ 实测排障记录：对 Text 后端生成的备份执行恢复会失败——!backup 会把 TextCmds 插件里的 TextPerson 对象按 repr 写进 backup.py（pobj["user"] = <errbot.backends.text.TextPerson object at 0x...>），恢复时 exec 该文件直接抛 SyntaxError: invalid syntax（exit=255）。结论：!backup/-r 面向真实聊天后端；Text 演示环境直接备份 data/ 目录更可靠。另外恢复链路依赖 pytest（Null/Test 后端引用），极简环境需先 pip install pytest。

十一、生成插件骨架：errbot --new-plugin

交互式向导，在当前目录创建插件骨架（<name>.plug + <name>.py）：

执行命令：

cd /opt/errbot/bot/plugins
errbot --new-plugin mytest

执行结果（向导问答，照抄）：

This wizard will create a new plugin for you in 'mytest'.
What should the name of your new plugin be?
> What may I use as a short (one-line) description of your plugin?
> Which minimum version of errbot will your plugin work with?
Leave blank to support any version or input CURRENT to select the current version 6.2.1.
> Which maximum version of errbot will your plugin work with?
Leave blank to support any version or input CURRENT to select the current version 6.2.1.
> Success! You'll find your new plugin at 'mytest/mytest.plug'
(Don't forget to include a LICENSE file if you are going to publish your plugin).

生成的 mytest/mytest.plug（插件清单文件）：

[Core]
name = mytest
module = mytest

[Documentation]
description = A test plugin

[Python]
version = 3

解读：向导依次问名称、一行描述、最低/最高兼容版本（留空=不限，输入 CURRENT 锚定当前 6.2.1）；生成后重启机器人或 !plugin activate mytest 即可加载。

十二、pip 管理后端与插件依赖

Errbot 用 pip extras 声明各聊天后端的依赖，装核心包后按需补装：

extras命令内容（6.2.1 实测）
IRCpip install "errbot[irc]"irc==20.5.0
Slackpip install "errbot[slack]"errbot-backend-slackv3==0.3.2
Telegrampip install "errbot[telegram]"python-telegram-bot==13.15
XMPPpip install "errbot[xmpp]"slixmpp==1.15.0 + pyasn1
Discordpip install "errbot[discord]"err-backend-discord==3.0.1
Mattermostpip install "errbot[mattermost]"err-backend-mattermost==3.0.0

执行命令（装完后端重列验证）：

pip install "errbot[irc]"
errbot -l

Successfully installed irc-20.5.0 ...

errbot -l 输出中即出现 IRC。插件本身的 Python 依赖由 AUTOINSTALL_DEPS = True（默认）在插件安装时自动 pip install -r requirements.txt，也可用 pip install -r <插件目录>/requirements.txt 手工预装（离线环境推荐）。

十三、Text 会话内管理命令（速查）

机器人运行后，管理操作通过会话命令完成（管理员身份）。Text 后端实测常用项：

命令作用实测回显要点
!about版本与致谢This is Errbot version 6.2.1
!whoami当前身份person = CHANGE_ME、class is 'TextPerson'
!status plugins插件状态表图例 A = Activated, D = Deactivated, B = Blacklisted, C = Needs to be configured
!plugin config Webserver {'HOST': '0.0.0.0', 'PORT': 3141, 'SSL': None}写插件配置Plugin configuration done.
!plugin deactivate Utils / !plugin activate Utils停/启插件Plugin Utils deactivated.
!repos install https://github.com/errbotio/err-helloworld.git装第三方插件A new plugin repository has been installed correctly ... → !hello 回 Hello World !
!inroom / !inperson / !asuser / !asadmin切换会话上下文Text 后端专属调试命令
!ml多行输入开关回车两次发送

十四、注意事项

  1. errbot 各主功能选项互斥，串行多步操作分多次执行（先 --init 再启动）。
  2. 所有依赖 config.py 的选项（含 -l、storage 系列）都要在机器人目录执行或用 -c 指定。
  3. storage 系列直接改生产数据，操作前先备份 BOT_DATA_DIR。
  4. -d 守护模式仅用于真实聊天后端；Text 后端守护化会立即退出（见八、实测）。
  5. 守护/开机自启生产上优先用 systemd，-d/-p 作辅助。

十五、常见问题

Q1：执行 errbot 报 I cannot find the config file //config.py？

当前目录没有 config.py。cd 到机器人目录，或 errbot -c /path/to/config.py。

Q2：errbot -T Text 报 unrecognized arguments: Text？

-T 是开关不带值，直接 errbot -T；指定其他后端改 config.py 的 BACKEND。

Q3：机器人运行时执行 --storage-get 报 Storage does not appear to have been opened yet？

存储被运行中的进程独占。停机器人后再执行 storage 命令。

Q4：errbot -d 后 ps 看不到进程？

若 BACKEND = "Text"，守护进程因 stdin EOF 立即退出，pidfile 虽生成但进程已不在——这是预期行为，换真实聊天后端或改前台/systemd 运行。

Q5：errbot -r backup.py 报 SyntaxError: invalid syntax？

备份来自 Text 后端、含对象 repr（见十、实测排障），该备份不可恢复；改用直接备份 data/ 目录的方式。

十六、参考链接