开始使用

安装完成、看到「框架启动完成」后，接下来要做的：确认启动成功 → 确定事件来源 → 验证链路 / 打开后台。

1. 启动

python main.py
# 也可指定配置：python main.py D:\config\zcbot.yaml

成功时大致长这样（默认启用 echo / help / scheduler / webui 四个官方插件，其余接入端默认关闭）：

==================================================
ZCBOT 框架 启动中...
==================================================
已加载 N 个用户插件: [...]
框架启动完成，等待消息...

出现最后一行 框架启动完成，等待消息... 即就绪。日志同时写在 data/logs/zcbot.log。

注意：大部分官方插件默认关闭，但有几个例外：

• echo（连通性自检，默认开启）——教程里 /echo 你好 验证链路靠它，详见下方第 2 步；
• help（帮助命令，默认开启）；
• scheduler（定时任务调度器，默认开启）；
• webui（Web 管理后台，默认开启）。

其余如 onebot_adapter / qq_official / telegram 等接入端默认全部关闭，需显式启用。 启用方式：把 core_plugins.yaml 里对应插件的 enabled 改为 true，或运行 python tools/scan_core_plugins.py --enable <插件名>，然后重启。

没报错？ 直接往下。报错了？ 看日志最后几行；依赖问题多半会在启动时自动补装后重试，缺依赖时还会给出中文诊断与 pip install 命令（见 调试排错）。

2. 确定事件来源

事件可以来自三种地方，按需选一种（也可以多种并存）：

事件来源	需要聊天平台吗	做法
IM 消息（QQ / TG / Discord…）	需要	按 对接 IM 平台 连接
定时任务	不要	scheduler + ctx.task() 注册 cron 任务
HTTP 注入	不要	开 http_inject，外部系统 POST JSON 进来

验证链路通不通，任选其一：

• 已接平台 → 对机器人发 /echo 你好（由内置 echo 自检插件响应，默认开启；回 你好 即链路通）
• 不接平台 → 在 core_plugins.yaml 关 onebot_adapter、开 http_inject，然后：

curl -X POST http://127.0.0.1:8901/hook \
     -H "Content-Type: application/json" \
     -d '{"user_id": 10001, "message": "/echo 来自 HTTP"}'

命令逻辑照常跑——没有 IM 也能用。

3. 第一次对话（已对接平台时）

对机器人发：

/echo 你好

它原样回 你好 就说明链路通了。再发 /help（或 /帮助、/菜单，由内置 help 插件提供，默认开启）看全部命令。

4. 打开 Web 管理后台

前提：webui 默认已开启；若你曾在 core_plugins.yaml 中将其关闭，请改回 enabled: true 并重启，否则不会监听端口。

浏览器访问：http://127.0.0.1:8080（端口以 config.yaml → web.port 为准）

端口 / 监听地址 / 会话超时等运行参数只认 config.yaml 的 web: 段； core_plugins.yaml → webui 只负责 enabled 开关。两处同名键曾互相覆盖， 现已在启动时按 config.yaml 收敛，改 core_plugins.yaml 的 port 不会生效。

用户名	admin
密码	admin123

登录后可以：开关/重载插件、管理命令与定时任务、管权限、看仪表盘和日志、在线改配置。

首次登录建议

1. 默认账号 admin / admin123；登录后后台顶部会弹出「建议修改密码」提示（可关闭、不强制），建议尽快在「设置 → 修改密码」改掉——默认密码是种子值，留着有风险。
2. 若要公网访问：web.host 保持 127.0.0.1 + 反向代理；接入端设好 access_token；按需配 IP 白名单。

5. 下一步

目标	去哪
写第一条命令	编写插件
连真实聊天软件	对接 IM 平台
改端口 / 开关插件 / 换数据库	配置系统
插件拆多文件	加载机制
放到服务器	部署上线