ALemonX 用户手册

September 2, 2026 · View on GitHub

面向第一次接触 ALemonX / AlemonJS 的用户。本手册从“这是什么”讲起，解释工作台里常见的核心概念与相关技术，最后整理了常见问题。英文版见 English version。

目录

  1. 认识项目
  2. 相关技术
  3. 常见问题

一、认识项目

ALemonX 是什么

ALemonX（命令行叫 alx）是 AlemonJS 机器人的本地工作台。AlemonJS 是一个基于 Node.js 的机器人开发框架，可以对接 QQ、Discord、OneBot 等平台；ALemonX 则把这些机器人的创建、运行、调试、测试和发布集中到一个图形化工作台里，让你不用全程敲命令。

一句话理解：ALemonX 管“机器人项目”，AlemonJS 是“机器人框架”，你的机器人项目是一个跑在 Node.js 上的 AlemonJS 应用。

你能用 ALemonX 做什么

  • 创建机器人项目：支持 JavaScript / TypeScript，可选样式、图片组件、能力模板（气泡服务、数据存储、QQ Bot、Discord、OneBot 等）。
  • 检查开发环境：自动检测 Node.js、Git、包管理器、浏览器等是否就绪，缺什么给出一键修复入口。
  • 运行机器人：开发模式（热更新）、前台运行、PM2 持续运行三种方式。
  • 管理多个机器人：添加、固定、切换机器人目录，统一查看运行状态与日志。
  • 测试与调试：内置测试中心、LiveChat、机器人应用页，PM2 日志支持分页、流式和导出。
  • 发布：一键打包发布到 npm，或创建 Git Release 标签。
  • AI 协作：在工作台内让 AI Agent 阅读、修改你的机器人代码，每次写操作都要你确认；还有 AI 运维（观察/灰度/自动修复）和 MCP 控制面，供 Codex 等本地 AI 客户端接入。
  • 扩展能力：系统插件（网络、Docker、QQ 管理等）为工作台本身增加本机管理能力。

机器人发布时的构建入口和 bundle 规范见机器人构建规范。

核心概念

工作台与窗口

前端是一个“桌面式”界面：窗口可以拖拽、缩放、最小化，系统功能（环境、任务、运维、账户、插件）以侧栏窗口呈现，每个已安装的系统插件也有自己的窗口。界面支持亮/暗主题，并适配小窗口和窄屏。

机器人项目 / 机器人目录

一个机器人项目就是一个目录，根目录必须包含 package.json。你可以用引导页新建项目，也可以在「管理」中添加已有的机器人目录；工作台以“机器人目录”作为身份键来管理运行、端口、PM2 和机器人应用页。

三种运行方式

方式用途特点
开发模式（dev）日常开发调试使用 lvy app.ts 启动，改动热更新，日志直接可见
前台模式临时运行在当前终端前台运行，Ctrl+C 停止
PM2 持续运行生产运行守护进程管理，异常自动拉起，支持 pm2 save 恢复清单，推荐生产环境使用

统一工作区（workspace）

ALemonX 把模板、工具、新建机器人和系统插件收敛到一个工作区（默认 <运行目录>/workspace，可用 --workspace 或 ALX_WORKSPACE 指定）：

workspace/
├── templates/    项目模板（首次启动从内嵌模板物化，可编辑）
├── packages/     工具目录（内置 Yarn 物化副本；PM2 首次使用时安装到这里）
├── bots/          新建机器人的默认落点
├── plugins/       已安装系统插件（唯一安装目标，优先于程序 plugins/）
└── store/         插件持久数据（每个插件使用 store/<插件 ID>/）

三种入口

  • 浏览器 UI：alx（默认 http://127.0.0.1:17390），日常使用。
  • 命令行 alx：浏览器不可用或远程排障时使用，见 命令行文档。
  • MCP 控制面：让 Codex、豆包等本机 AI 客户端通过标准 MCP 协议管理机器人，见 MCP 文档。

三种容易混淆的“嵌入页面”

名称谁在用能做什么
系统面板页系统插件插件自己的管理界面，可调用宿主能力与特权操作
宿主 WebView系统插件打开的 resource 窗口普通 iframe，展示插件自身静态页面并提供受控宿主能力
机器人应用页机器人插件只能访问当前机器人的 ./api/*，是机器人自己的前端

三者的代理、权限、页面注入与生命周期互不复用。系统插件请求打开 HTTP/HTTPS 地址时，会交给左下角的浏览器创建新标签；只有系统插件自身的静态 resource 页面才会在插件窗口内打开。详细边界见：WebView 架构。

系统插件 vs 机器人插件

  • 系统插件：为 ALemonX 本身提供系统级能力（网络、防火墙、Docker 等），与具体机器人无关。
  • 机器人插件：为某个机器人提供命令、配置页、机器人应用页，属于机器人项目的一部分。

快速上手

  1. 安装：按 README 的「一行安装」安装 alx（国内用户使用镜像命令）。
  2. 打开：运行 alx，在浏览器打开 http://127.0.0.1:17390；或 alx open。
  3. 创建：在引导页选择「开发」创建新机器人，或「管理」添加已有机器人目录。
  4. 检查环境：在「环境」确认 Node.js（v22.22.3+）、Git 等就绪，按提示一键修复。
  5. 运行：在「运行」选择开发模式调试，或使用 PM2 持续运行。
  6. 测试与发布：用测试中心验证功能，再通过「发布」打包到 npm 或创建 Git Release。

二、相关技术

下面的技术你在工作台里都会遇到。对新手来说，不需要先学会全部，只要理解“它是什么、负责什么”就够了，具体操作工作台会引导你完成。

技术一句话解释在 ALemonX 里的作用
Node.js在电脑上运行 JavaScript 的“引擎”机器人的运行基础，ALemonX 也用它管理机器人进程
npm / YarnJavaScript 的“包管理器”，负责下载和安装依赖安装机器人依赖、启动脚本、打包发布
JSON一种通用的数据/配置文本格式package.json 等配置文件
YAML另一种更易读的配置格式alemon.config.yaml 机器人配置
JavaScript / TypeScript写机器人逻辑的语言机器人模板支持 JS 或 TS
Git代码版本管理工具项目版本管理、创建 Git Release
PM2Node.js 进程守护工具让机器人持续运行、异常自动重启
Redis内存数据库可选的内置缓存，可关闭
SSE服务器向浏览器单向推送事件的机制工作台实时刷新日志、任务进度
MCP让 AI 客户端连接本地工具的协议Codex 等接入 ALemonX 控制面
AlemonJS 生态机器人框架 + 配套工具运行、构建、检查机器人

Node.js

  • 是什么：一个让 JavaScript 在电脑上直接运行的运行时（runtime）。就像浏览器能“跑”网页里的 JS 一样，Node.js 让 JS 能跑在服务器/本地。
  • 在 ALemonX 里做什么：你的机器人是 Node.js 应用；ALemonX 负责用 Node.js 启动、停止和监控它们，并检查 Node.js 环境是否可用。
  • 需要你做什么：版本建议 v22.22.3 或更高。版本过低时工作台会提示升级，但不会阻止你继续使用；只有“完全缺失或无法运行”才是阻断项。

npm 与 Yarn

  • 是什么：包管理器。npm 随 Node.js 自带，Yarn 是另一款常用包管理器；它们负责从仓库下载别人写好的代码包（依赖）并记录版本。
  • 在 ALemonX 里做什么：安装机器人依赖（install）、构建、启动脚本、发布到 npm。ALemonX 内置了 Yarn 副本，创建项目和安装依赖不依赖你手动安装 npm 包；PM2 等工具也会被自动安装到工作区。
  • 需要你做什么：一般不用手动操作；需要时在工作台选择包管理器（npm / yarn / pnpm）。

JSON

  • 是什么：JavaScript Object Notation，一种用 {}、[]、"key": value 描述数据的纯文本格式，人和程序都能读。
  • 在 ALemonX 里做什么：package.json（项目元信息、依赖、脚本）、插件清单 alx.json、部分本地数据文件都是 JSON。
  • 需要你做什么：只要知道配置文件是 JSON、注意逗号和引号即可；工作台的配置编辑器会帮你校验。

YAML

  • 是什么：另一种配置格式，用缩进表达层级，比 JSON 更“易读”。ALemonJS 机器人使用 alemon.config.yaml 配置平台账号、监听端口等。
  • 在 ALemonX 里做什么：工作台提供该配置的可视化编辑器，也会在设置里注入主题变量等。
  • 需要你做什么：注意 YAML 对缩进敏感；用工作台编辑器修改比手写更安全。

JavaScript / TypeScript

  • 是什么：JavaScript 是机器人逻辑的编写语言；TypeScript 是带类型检查的 JS 超集，能提前发现很多低级错误。
  • 在 ALemonX 里做什么：创建项目时可选择 JS 或 TS 模板；机器人命令、事件处理都写在源码里。
  • 需要你做什么：写机器人功能时了解基础语法即可；AI Agent 也可以在你确认后帮你改代码。

JSX / JSXP

  • 是什么：JSX 是一种在 JS 里写界面结构的语法；JSXP（jsxp）是 AlemonJS 用来在机器人里生成图片/界面组件的渲染方案。
  • 在 ALemonX 里做什么：机器人的图片消息、帮助页等组件；模板里可选是否包含图片组件能力。

Git

  • 是什么：代码版本管理工具，记录每次修改，支持回退、分支和协作。
  • 在 ALemonX 里做什么：初始化仓库、查看改动、提交，以及创建 Git Release 标签用于发布。
  • 需要你做什么：确保已安装 Git；不熟悉命令也没关系，工作台有图形化 Git 面板。

PM2

  • 是什么：Node.js 进程守护工具，让程序持续运行、崩溃自动重启，并管理日志。
  • 在 ALemonX 里做什么：机器人「持续运行」模式基于 PM2；ALemonX 在启动/重启/reload 成功后执行 pm2 save 保存恢复清单。
  • 身份与移动：PM2 应用名由机器人根目录的 .alemonx-id 与 package.json 名称决定，移动目录不会改变身份；旧项目没有该文件时保持旧名，直到配置被重写。
  • 需要你做什么：首次部署在服务器上时，管理员按 PM2 输出执行一次 pm2 startup，避免主机重启后丢失守护进程。

Redis

  • 是什么：一个高性能内存数据库，常用来做缓存、队列。
  • 在 ALemonX 里做什么：内置的可选 Redis，可调整端口（--redis-port）或关闭（--redis-off）；设置页可随时调整。
  • 需要你做什么：一般不用管；端口被占用时可以换端口或关闭。

SSE

  • 是什么：Server-Sent Events，服务器单向推送事件给浏览器的机制，类似“订阅了一个实时消息流”。
  • 在 ALemonX 里做什么：日志、任务进度、插件变更、运维事件等页面实时刷新都靠它。

MCP

  • 是什么：Model Context Protocol，一套让 AI 客户端（Codex、豆包等）安全连接本地工具的标准协议，使用 JSON-RPC 2.0。
  • 在 ALemonX 里做什么：把机器人管理能力以受限工具的形式暴露给本地 AI 客户端；所有修改性操作都要求 confirm: true 确认。
  • 需要你做什么：想用 AI 客户端控制机器人时，按 MCP 文档 配置 stdio 或流式 HTTP；可设置 MCP_ALLOWED_ROOTS 限制可管理的目录。

AlemonJS 生态工具

工具作用
alemonjs机器人框架核心包
alemonc机器人检查/启动辅助（npx alemonc start）
lvy开发/构建工具（lvy app.ts、lvy build）
jsxp图片/界面组件渲染

三、常见问题

安装与启动

Q1：国内安装很慢或直接失败，怎么办？

使用镜像命令安装（README「国内用户安装」），例如 curl ... | ALX_PREFER_MIRROR=1 sh；ghfast.top 不可用时换成 ghproxy.net 或 gh-proxy.com。也可设置 ALX_DOWNLOAD_BASE 指向自建镜像。安装脚本会自动校验 SHA-256。

Q2：提示 alx: command not found？

安装脚本会把 alx 放到用户命令目录（macOS/Linux 通常是 ~/.local/bin，Windows 是 %LOCALAPPDATA%\Programs\ALemonX）。重新打开终端，或把该目录加入 PATH。

Q3：端口 17390 被占用？

用 alx --port 其他端口 启动，或先停掉占用进程；内置 Redis 端口冲突可用 --redis-port 调整或 --redis-off 关闭。

Q4：浏览器打不开工作台？

确认服务已启动：alx health、alx status、alx doctor 可以诊断。默认监听 0.0.0.0，局域网可直接访问 http://服务器IP:17390；只想本机访问用 alx --host 127.0.0.1。

Q5：提示需要管理员权限 / sudo？

部分系统级操作（安装环境依赖、系统服务、插件特权操作）需要授权。可在特权弹窗输入密码（password 模式）或使用系统原生授权（native 模式）；操作会写入审计记录。

Q6：后台服务注册到哪里？移动 alx 程序后怎么办？

alx install 注册的是你当前执行的 alx 程序（不会复制到别的目录），并把安装时解析出的工作区固定进服务参数，后台服务与前台使用同一工作区。每次执行 alx install 都会以当前程序与工作区直接覆盖重新注册，不会因为已安装而跳过。 安装默认开启开机自启；Linux 上还会默认尝试开启无登录运行（权限不足时会提示，可在设置 → 服务中稍后启用）。程序移动后，从新位置重新执行 alx install，或直接执行 alx start（会自动检测并按当前程序重新注册）；alx status 会显示注册的程序与工作区路径。

卸载后台服务：执行 alx uninstall --yes，或在「设置 → 服务」点「卸载服务」。卸载只移除后台服务注册与开机自启，不会删除工作台数据、账户或机器人项目；之后手动运行 alx 即可重新打开工作台。

环境与依赖

Q7：Node.js 版本太低怎么办？

建议升级到 v22.22.3+。版本低时工作台会标记为 outdated 并显示升级入口，但不会阻止使用；只有缺失或无法运行才会阻断。

Q8：缺少 Git 或包管理器？

在「环境」页面查看检查项，按提示一键安装。Git 用于版本管理与发布；包管理器用于安装机器人依赖。

机器人运行

Q9：机器人启动失败，日志在哪里看？

开发/前台模式的日志在终端或运行面板；PM2 模式用「PM2 日志」查看，支持分页、流式、导出。命令行可用 alx logs 查看后台服务日志（macOS：~/Library/Logs/alx.log；Linux：journalctl --user -u alx.service；Windows：%LOCALAPPDATA%\alx\alx.log）。

Q10：提示端口被其他进程占用？

工作台会自动识别端口归属；确认是其他程序占用后，换一个机器人端口，或停止占用程序。Windows 下端口归属按进程树识别 npm/yarn 派生的 Node 进程。

Q11：开发模式和 PM2 模式有什么区别？

开发模式适合改代码：改动热更新、日志直观；PM2 模式适合稳定运行：守护进程、自动重启、开机恢复清单，生产环境推荐。

配置与数据

Q12：机器人配置在哪里改？

机器人根目录的 alemon.config.yaml（平台账号、端口等）和 package.json（依赖、脚本、发布信息）。工作台提供可视化编辑器，敏感字段（.env、.npmrc、alemon 配置草稿）不会持久化到浏览器。

Q13：工作台的数据存在哪里，怎么备份？

工作区目录保存模板、工具、新建机器人和系统插件；系统插件固定在 workspace/plugins，安装时不会写入程序目录。插件的默认可恢复数据目录为 workspace/store/<插件 ID>，例如 QQ 的登录态和下载组件；插件升级不会删除它。工作台状态（账户、配置、SQLite、下载缓存）在用户配置目录（Docker 部署在宿主机 ./data）。AI 运维数据默认在 ops.db（SQLite）。备份工作区和数据目录即可。

工作区路径也会显示在创建机器人的"保存位置"里（默认 workspace/bots）。模板或内置工具若检测到更新版本，不会自动覆盖；如需刷新，删除对应副本目录后重新使用即可。

Docker 部署也默认启用 Redis；它仅监听容器内 127.0.0.1，不会新增对外端口。./data 卷会保留其配置与回退快照。

Q14：忘记工作台管理员密码？

认证已开启时，使用紧急恢复命令重设超级管理员：alx auth reset-super-admin --account ... --password ... --confirm-password ... --yes。它会立即使旧会话失效，并禁用其他超级管理员账号；普通账号、角色和工作台数据会保留。alx auth status 可查看当前状态。生产部署建议配合防火墙限制访问来源。

为避免密码出现在 shell 历史和进程参数中，请使用 --password-stdin 并通过标准输入连续传入两次密码。Docker 部署必须在容器内执行，保证写入实际运行服务的认证文件：docker compose exec -T alx /app/alx auth reset-super-admin --account <账户> --password-stdin --yes。先执行 docker compose exec -T alx /app/alx auth status 可确认配置路径。

AI 与 MCP

Q15：为什么 AI 写代码要反复确认？

这是设计的安全边界：所有修改性操作都必须由你确认（confirm: true），MCP 的约束在 Go 服务层强制执行，不依赖客户端提示。你随时可以拒绝或停止任务。

Q16：Codex 连不上 MCP？

先 command -v alx 确认 alx 在 PATH；stdio 方式填启动命令 alx、参数 mcp；流式 HTTP 需要先设置 MCP_TOKEN 并启动 alx mcp-http，地址 http://127.0.0.1:17391/mcp。可选设置 MCP_ALLOWED_ROOTS 限制可管理目录。

Q17：AI 能对我的机器人做什么，不能做什么？

能：读源码、改代码、安装依赖、构建、Git 操作、管理运行（在你确认后）。不能：任意宿主 Shell 命令、读取 .env/.npmrc/私钥、访问 .git/node_modules/符号链接、读写超过 1 MiB 的文件。

更新与升级

Q18：如何更新 ALemonX？

alx update 检查并自动更新（校验 SHA-256）。Docker 部署请在宿主机执行 sh docker-install.sh pull && restart，不要在容器内执行 alx update。

Q19：更新后配置会丢吗？

不会。模板与工具包只在缺失时复制，已存在文件不会被覆盖；账户、配置、SQLite 与插件数据都保留。若遇到不兼容，先备份 workspace、./data（Docker）与 ops.db 再升级。

更多细节见：命令行 · Docker 部署 · MCP 控制面 · 系统插件开发 · 机器人应用页规范。