本页是 MatrixBot 的产品站。下面的命令与安全说明对应自托管版本 v0.4.0；数字来自本机正在运行的实例，产品目前处于内测开发阶段。完整的项目 README 在源码仓库里。
快速开始
需要 Node.js 22 或更高版本。首次启动会创建管理员账户，初始密码只在这一次的启动日志里打印；也可以事先在 .env 里设置 MAC_ADMIN_PASSWORD。
git clone <repo-url> matrixbot
cd matrixbot
cp .env.example .env # 按需修改端口、模型与文件根目录
npm install
npm run build
npm start # http://127.0.0.1:8790开发模式是后端热重载加 Vite：npm run dev。用 Docker 的话：
docker compose up -d --build
docker compose logs matrixbot | grep 初始密码登录后先到「账户」修改密码，再到「设置 → 连接」添加运行时或模型接口。
连接运行时
连接是 MatrixBot 与 Agent 之间的边界：它决定会话跑在哪台机器、能调用什么工具、危险命令是否需要审批。
| 类型 | 能力 | 地址示例 |
|---|---|---|
| Hermes | 完整 Agent 能力：工具、审批、插话、子 Agent、渠道 | http://host:8642 |
| OpenCode | 代码与文件工作流，按会话恢复运行状态 | http://host:4096 |
| dsh | 命令行 Agent 运行时，适合本机自动化 | 本机进程 |
| ACP | Agent Client Protocol 兼容运行时 | 按运行时配置 |
| OpenAI 兼容 | 纯对话：流式输出、思考过程、多轮上下文 | https://api.example.com/v1 |
一个 Agent 绑定一个连接。接线时填地址与密钥，点「测试」会列出可用模型；连接健康状态在设置页直接可见。
部署与反向代理
建议把 MatrixBot 放在 HTTPS 反向代理后面，并只监听回环地址。浏览器麦克风、跨设备登录和多人使用都要求 HTTPS。
# .env
PORT=8790
HOST=127.0.0.1
MAC_DEFAULT_USER=admin
MAC_ADMIN_PASSWORD=<设置一个强密码>
FILE_ROOTS=$HOME:/tmp反向代理需要关闭响应缓冲以支持 SSE 流式输出，并把请求体上限调大以支持文件上传。经过代理的请求一律要求登录；不要在生产环境打开 MAC_TRUST_LOOPBACK。
安全模型
这一节值得在把实例开放给别人之前读完。它不是营销文案，是使用边界。
- Hermes 以系统账户执行命令。 共享一台 Hermes 连接，等于让对方能在那台机器上做事。只共享给你信任的人，或者给每个人单独部署运行时。
- 审批不是沙箱。 审批只覆盖运行时标记为危险的命令；共享连接时可以设为一律拒绝。
- 普通用户默认隔离。 看不到本机记忆、日志、定时任务、技能和项目；看不到别人的会话、运行状态和屏幕；不能读取家目录文件。
- 敏感文件不开放。 数据库、密钥文件和 data/ 目录不会通过文件接口提供给任何人，包括管理员。
- 操作留痕。 登录、账户与共享变更、发消息（只记长度）、审批与停止都会写入审计日志。
备份与升级
数据库在数据目录里，每个用户一个 SQLite 文件。升级前先停服务、拷贝数据目录与 .env，再拉取新版本执行 npm install && npm run build。回滚就是恢复上一份数据目录并切回上一个构建。
本项目使用 MIT 许可证。安全漏洞请私下报告，不要开公开 issue。