快速安装

方式一：Docker Hub 一键拉取（推荐）

最简单的方式，无需 clone 代码。

docker run -d --name waylay --privileged \
  -p 13000:13000 -p 3001:3001 \
  micuks/waylay:latest

启动后浏览器打开 http://localhost:13000/qrcode 扫码登录。

带参数启动（快速登录 + 反向 WS 连接 Yunzai）：

docker run -d --name waylay --privileged \
  -p 13000:13000 -p 3001:3001 \
  -e AUTO_LOGIN_QQ=123456789 \
  -e ONEBOT_WS_PORT=3001 \
  -e 'ONEBOT_WS_REVERSE_URLS=["ws://host.docker.internal:2536/OneBotv11"]' \
  --add-host=host.docker.internal:host-gateway \
  -v waylay_qq:/root/.config/QQ \
  micuks/waylay:latest

或使用 Docker Compose：

curl -fsSLO https://raw.githubusercontent.com/Micuks/waylay-qq-bridge/master/docker-compose.yml
# 按需编辑 docker-compose.yml
docker compose up -d

方式二：一键安装脚本（裸机 Linux）

无需 Docker，直接在 Linux 系统上安装运行。脚本会自动安装 QQ、Node.js、ffmpeg 等依赖，并创建 systemd 服务。

curl -fsSL https://raw.githubusercontent.com/Micuks/waylay-qq-bridge/master/install.sh | sudo bash

安装完成后：

sudo systemctl start waylay    # 启动
sudo systemctl enable waylay   # 开机自启
curl http://localhost:13000/qrcode  # 查看登录二维码
journalctl -u waylay -f        # 查看日志

修改配置（如添加快速登录、反向 WS）：

sudo systemctl edit waylay

在编辑器中添加：

[Service]
Environment=AUTO_LOGIN_QQ=123456789
Environment=ONEBOT_WS_REVERSE_URLS=["ws://127.0.0.1:2536/OneBotv11"]

方式三：从源码构建

git clone https://github.com/Micuks/waylay-qq-bridge.git
cd waylay-qq-bridge
docker compose up -d --build

Windows 用户

请参阅 WSL 安装指南 通过 WSL2 在 Windows 上运行 Waylay。

快速登录

首次扫码登录后，后续可以使用快速登录跳过扫码。设置 AUTO_LOGIN_QQ 环境变量为你的 QQ 号即可。

连接 Bot 框架

Waylay 启动后，配置你的 Bot 框架连接到 OneBot v11 WebSocket：

• 正向 WS：让框架连接 ws://你的服务器IP:3001/
• 反向 WS：配置 ONEBOT_WS_REVERSE_URLS 环境变量

各框架的详细对接步骤请参考 对接框架 章节。

验证安装

启动后检查日志：

# Docker
docker logs waylay

# 裸机安装
journalctl -u waylay -f

看到以下输出即表示成功：

[server] Listening on 0.0.0.0:13000
[onebot] Forward WS listening on 0.0.0.0:3001
[bridge] Login successful
[onebot] Adapter started

端口说明

端口	用途
3001	OneBot v11 正向 WebSocket
13000	Bridge WebSocket/HTTP（LLOneBot 兼容 + 扫码登录）