CLI 指令

AstrBot CLI 用于初始化实例、启动 AstrBot、安装后台服务、查看日志、修改常用配置和管理插件。

如果你使用 uv 安装：

uv tool install astrbot --python 3.12

uv 会生成 astrbot 可执行文件，并把它放到 PATH 中。可以用下面的命令确认路径：

Linux / macOS

which astrbot

Windows

where.exe astrbot

TIP

下面的命令都需要在 AstrBot 工作目录中执行，除非命令提供了 --workdir 选项。

快速开始

第一次部署时先初始化目录，再启动 AstrBot：

astrbot init
astrbot run

astrbot init 会在当前目录创建 AstrBot 所需的数据目录和配置文件。初始化完成后，后续启动只需要执行 astrbot run。

顶层指令

指令	用途
astrbot init	初始化当前目录为 AstrBot 工作目录。
astrbot run	在前台启动 AstrBot。
astrbot service	安装和管理 AstrBot 后台服务。
astrbot config	查看或修改常用配置项。
astrbot password	交互式修改 WebUI 登录密码。
astrbot plugin	创建、安装、更新、删除或搜索插件。
astrbot help	查看 CLI 帮助。
astrbot --version	查看 AstrBot CLI 版本。

conf 和 plug 是兼容别名，仍然可用：

astrbot conf get
astrbot plug list

推荐在新文档和脚本中使用 config 和 plugin。

启动 AstrBot

astrbot run

常用选项：

选项	用途
-p, --port <PORT>	指定 WebUI 端口。
-r, --reload	启用插件自动重载，适合插件开发调试。

示例：

astrbot run --port 6185
astrbot run --reload

后台服务

astrbot service 可以把 AstrBot 安装为用户级后台服务，适合长期运行。

不同系统会使用对应的服务管理机制：

系统	服务管理器
Linux	systemd --user
macOS	LaunchAgent
Windows	任务计划程序

安装服务

astrbot service install --now

该命令默认使用当前 PATH 中的 astrbot 可执行文件，并把当前目录作为 AstrBot 工作目录。--now 表示安装后立即启动或重启服务。

常用选项：

选项	用途
--name <NAME>	指定服务名，默认 astrbot。
--workdir <DIR>	指定 AstrBot 工作目录。
--executable <PATH>	指定 astrbot 可执行文件路径。
--force	覆盖已有服务定义。
--now	安装后立即启动或重启服务。

如果 astrbot 不在 PATH 中，可以显式指定可执行文件：

astrbot service install --workdir /path/to/astrbot-root --executable /path/to/astrbot --now

管理服务

astrbot service start
astrbot service stop
astrbot service restart
astrbot service uninstall

这些命令都支持 --name <NAME>，用于管理非默认服务名：

astrbot service restart --name astrbot-test

卸载服务时，如果不希望交互确认，可以使用：

astrbot service uninstall --force

查看服务状态

astrbot service status

状态输出会包含：

• 整体健康状态。
• 当前系统和服务管理器。
• 服务是否已安装、是否启用、当前运行状态。
• AstrBot 工作目录。
• Dashboard 端口。
• WebUI URL 和是否可访问。

常用选项：

选项	用途
--name <NAME>	指定服务名，默认 astrbot。
--workdir <DIR>	指定 AstrBot 工作目录，用于读取端口配置。
--timeout <SECONDS>	指定 WebUI 健康检查超时时间，默认 2 秒。

示例：

astrbot service status --timeout 5

日志

AstrBot CLI 中有两类日志：

类型	命令	说明
服务日志	astrbot service logs	查看服务管理器捕获的控制台输出。
应用日志文件	astrbot service logs --source app	查看 data/logs/astrbot.log，需要先启用文件日志。

查看服务日志

astrbot service logs
astrbot service logs -n 100
astrbot service logs -f

常用选项：

选项	用途
--name <NAME>	指定服务名。
-n, --lines <N>	显示最近 N 行，默认 200。
-f, --follow	持续跟随日志输出。
--include-stderr	在 macOS 和 Windows 上同时显示 stderr 日志。

macOS 和 Windows 下，astrbot service logs 默认只显示标准输出日志，也就是 .out.log。如果需要同时查看错误输出，再加 --include-stderr。

启用应用日志文件

data/logs/astrbot.log 默认不会写入。需要先启用应用日志文件，然后重启 AstrBot：

astrbot service logs enable
astrbot service restart
astrbot service logs --source app

查看应用日志文件配置：

astrbot service logs status

关闭应用日志文件：

astrbot service logs disable
astrbot service restart

自定义应用日志文件路径：

astrbot service logs enable --path logs/astrbot.log

相对路径会以 AstrBot 数据目录为基准解析。

配置

astrbot config 用于查看和修改常用配置项。

astrbot config get
astrbot config get dashboard.port
astrbot config set dashboard.port 6185

支持的配置项：

配置项	说明
timezone	时区，例如 Asia/Shanghai。
log_level	日志等级：DEBUG、INFO、WARNING、ERROR、CRITICAL。
dashboard.port	WebUI 端口。
dashboard.username	WebUI 用户名。
dashboard.password	WebUI 密码。
callback_api_base	回调 API 基础地址，需要以 http:// 或 https:// 开头。

修改密码时会自动写入新版密码哈希：

astrbot config set dashboard.password "new-password"

也可以使用专门的交互式密码指令：

astrbot password
astrbot password --username admin

插件

astrbot plugin 用于管理 data/plugins 下的插件。

指令	用途
astrbot plugin list	查看已安装插件。
astrbot plugin list --all	同时显示未安装插件。
astrbot plugin search <QUERY>	搜索插件。
astrbot plugin install <NAME>	安装插件。
astrbot plugin update [NAME]	更新指定插件；不传名称时更新所有可更新插件。
astrbot plugin remove <NAME>	删除已安装插件。
astrbot plugin new <NAME>	基于模板创建新插件。

安装或更新插件时可以使用 GitHub 代理：

astrbot plugin install example-plugin --proxy https://gh-proxy.example.com/
astrbot plugin update --proxy https://gh-proxy.example.com/

创建新插件会交互式询问作者、描述、版本和仓库地址：

astrbot plugin new my-plugin

帮助

查看全部 CLI 帮助：

astrbot help

查看指定指令帮助：

astrbot help service
astrbot service --help
astrbot service logs --help

查看版本：

astrbot --version