Neo-MoFox WebUI 部署指南
欢迎！这份指南会手把手教你安装并启动 Neo-MoFox WebUI——让你从命令行地狱中解脱出来，用浏览器优雅地管理你的机器人。
测试阶段
WebUI 还在测试中，偶尔会闹点小脾气。遇到 bug 别慌，来 GitHub 提 Issue，我们一起修！
第一步：确认你已经装好了主程序
开始之前，确保你已经：
- ✅ 安装并能正常运行 Neo-MoFox 主程序
- ✅ Neo-MoFox 版本建议为
1.2.0-beta.1或更高版本 - ✅ 能打开 Neo-MoFox 插件市场页面
为什么推荐新版？
新版 Neo-MoFox 已经和插件市场深度集成。安装、订阅、更新插件都更省心，不需要你手动克隆仓库、切换分支、复制文件。
第二步：从插件市场安装 WebUI
WebUI 推荐从插件市场安装。插件市场页面是：
2.1 打开插件详情页
- 打开浏览器，访问上面的插件市场链接。
- 如果是第一次进入插件市场，会先看到 「首次使用安全提示」 弹窗。
- 仔细阅读提示后，点击右下角的 「我已知悉」。
- 随后可能会出现 「更便利·更轮椅」 的功能提示弹窗，点击右下角的 「知道了，不再提示」。
- 页面进入 Neo-MoFox WebUI 插件详情页后，确认标题显示为 Neo-MoFox WebUI，插件 ID 显示为
neo-mofox-webui。
安全提醒
插件市场中的插件由作者自行上传。安装前请确认插件名称、作者、简介和版本信息。WebUI 官方插件详情页会显示 官方 标识。
2.2 找到安装区域
进入插件详情页后，页面右侧会有一个 「安装」 面板。这个面板里通常会显示：
- 最新稳定版，例如
v1.0.5 - 发布时间
- 累计下载、订阅人数、评分
- 「下载插件」 按钮
- 「订阅更新」 按钮
如果窗口比较窄，右侧安装面板可能会被挤到页面下方。向下滚动就能看到。
2.3 下载插件包
- 在插件详情页右侧 「安装」 面板点击 「下载插件」。
- 浏览器会打开或下载最新版本的插件包。
- 如果浏览器只是打开了下载链接，请按浏览器提示保存文件。
- 下载完成后，不要解压到随机目录，继续按下一小节放到 Neo-MoFox 的插件目录。
2.4 放入 Neo-MoFox 插件目录
将下载到的 WebUI 插件包按 Neo-MoFox 插件安装规则放入主程序的插件目录。通常位置是：
<Neo-MoFox安装目录>/plugins/放好后，重启 Neo-MoFox 主程序。重启时请观察日志，确认 neo-mofox-webui 插件已经被加载。
版本选择
如果 「安装」 面板显示最新稳定版，例如 v1.0.5，点击 「下载插件」 通常会下载这个最新稳定版。需要指定旧版本时，可以切换到页面上的 「版本」 标签，在版本列表中点击对应版本右侧的 「下载」。
2.5 建议订阅更新
在安装面板中点击 「订阅更新」。新版 Neo-MoFox 会自动处理已订阅插件的更新流程，不需要额外配置 access token。
第三步：配置登录密钥
WebUI 安装完成后，还需要给 Neo-MoFox 的 HTTP 路由配置 API Key。编辑 Neo-MoFox 的配置文件：
<Neo-MoFox安装目录>/config/core.toml找到 [http_router] 这一节，设置你的 API Key：
[http_router]
# 是否启用 HTTP 路由（必须是 true）
enable_http_router = true
# 监听地址（本机访问用 127.0.0.1，局域网访问用 0.0.0.0）
http_router_host = "127.0.0.1"
# 监听端口（默认 8000，别和其他程序冲突就行）
http_router_port = 8000
# 登录密钥列表（重点在这里！）
api_keys = [
"your-super-secret-key-here", # 改成你自己的密钥
]安全提醒
API Key 就像你家钥匙，别随便给别人！
推荐生成一个随机字符串：
- Windows PowerShell：
[System.Guid]::NewGuid().ToString() - Linux / macOS：
openssl rand -hex 32
把生成的结果复制到 <Neo-MoFox安装目录>/config/core.toml 的 api_keys 列表里。
配置示例（仅供参考，别直接复制）：
api_keys = [
"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
]第四步：启动主程序
保存配置文件后，启动或重启 Neo-MoFox：
# 在 Neo-MoFox 根目录运行
uv run main.py启动成功后，你会在日志里看到类似这样的提示：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🌐 WebUI 可访问地址
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
监听地址: 127.0.0.1:8000
🖥️ 本机访问
▶ http://localhost:8000/webui/frontend
▶ http://127.0.0.1:8000/webui/frontend
🌐 局域网访问
▶ http://192.168.1.100:8000/webui/frontend ← 推荐
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━看到这个提示就成功了！
日志里会自动显示所有可访问的地址，包括局域网 IP。手机想访问的话，用带 🌐 标记的那个。
第五步：打开浏览器登录
- 复制可访问地址，推荐使用
http://localhost:8000/webui/frontend。 - 打开浏览器，粘贴地址，回车。
- 输入密钥，也就是你刚才在
config/core.toml里配置的api_keys。 - 点击登录。
登录成功后，你会看到 WebUI 仪表盘，可以在浏览器里管理机器人、查看插件、编辑配置、查看日志等。
恭喜你！🎉
到这里你已经完成部署了！现在可以愉快地用浏览器管理机器人了。
常见问题（遇到问题先看这里）
Q1：插件市场页面打不开怎么办？
解决方法：
- 确认浏览器能访问
https://39.96.71.162/plugin/neo-mofox-webui。 - 如果浏览器提示证书或安全警告，请确认你访问的是本文给出的插件市场地址，再按浏览器提示继续访问。
- 如果网络无法连接，稍后重试，或检查本机网络、代理、防火墙设置。
Q2：插件详情页没看到安装面板怎么办？
原因：窗口宽度较窄时，安装面板可能会移动到页面下方。
解决方法：
- 在插件详情页向下滚动。
- 找到标题为 「安装」 的面板。
- 在里面点击 「下载插件」，或复制
mofox plugin install neo-mofox-webui@版本号命令。
Q3：运行安装命令提示找不到 mofox
原因：当前 Neo-MoFox 环境可能还没有新版插件管理命令。
解决方法：
- 先更新 Neo-MoFox 主程序到推荐版本。
- 重新打开终端，进入 Neo-MoFox 根目录。
- 再运行插件市场给出的安装命令。
- 如果仍然不可用，可先使用插件市场的 「下载插件」 按钮手动下载插件包。
Q4：浏览器显示“无法访问此网站”
原因：
- Neo-MoFox 主程序没运行
- WebUI 插件没加载成功
- 端口被占用了
解决方法：
- 确认主程序正在运行，看终端有没有报错。
- 检查日志，确认
neo-mofox-webui插件已加载。 - 检查端口占用：
- Windows：
netstat -ano | findstr :8000 - Linux / macOS：
lsof -i :8000
- Windows：
- 如果端口被占用，修改
<Neo-MoFox安装目录>/config/core.toml里的http_router_port，改成其他没被占用的端口，例如8080，然后重启主程序。
Q5：输入密钥后提示“认证失败”
原因：
- 密钥输入错误，注意大小写和空格
- 配置文件里
api_keys是空的 - 修改配置后没有重启主程序
解决方法：
- 仔细核对密钥是否和配置文件里的完全一致。
- 确认
<Neo-MoFox安装目录>/config/core.toml的[http_router]部分里，api_keys列表不为空。 - 修改配置后必须重启主程序。
Q6：局域网访问不了（手机 / 其他电脑）
原因：监听地址设置成 127.0.0.1 了。
解决方法：
编辑 config/core.toml，把 http_router_host 改成 0.0.0.0：
http_router_host = "0.0.0.0"然后重启主程序。
安全提示
0.0.0.0 会让局域网内其他设备也能访问。如果你的路由器做了公网端口转发，也可能暴露到公网。
如果暴露到公网，强烈建议：
- 使用超级复杂的 API Key
- 配置防火墙规则限制访问 IP
- 考虑用 Nginx 反向代理加上 HTTPS
Q7：想用其他端口怎么办？
编辑 config/core.toml，修改 http_router_port：
http_router_port = 9999 # 改成你想要的端口重启主程序，然后访问：
http://localhost:9999/webui/frontend更新 WebUI
推荐继续通过插件市场更新 WebUI。
方式一：在插件市场下载新版本
- 打开 Neo-MoFox WebUI 插件详情页。
- 先看右侧 「安装」 面板显示的最新稳定版。
- 点击 「下载插件」 下载最新版本插件包。
- 如果需要指定版本，点击页面上的 「版本」 标签，在版本列表中点击对应版本右侧的 「下载」。
- 将下载到的新版本插件包放入 Neo-MoFox 插件目录，按提示覆盖或替换旧版本。
- 重启 Neo-MoFox。
方式二：订阅后自动更新
- 打开 Neo-MoFox WebUI 插件详情页。
- 在右侧 「安装」 面板点击 「订阅更新」。
- 新版 Neo-MoFox 会自动处理已订阅插件的更新流程。
反馈与贡献
遇到问题或有建议？欢迎：
- 🐛 提交 Bug 报告
- 💡 提出功能建议
- 🛠️ 提交 Pull Request
感谢你的使用！祝你玩得开心 🎉
贡献者
minecraft1024a micraft1024a
sunbiz1024
ikun-11451