wa-automate-nodejs

环境要求

• Node.js 环境（可直接运行 npx 命令；参与仓库开发需 Node.js >=22.21.1）
• 一个可登录的 WhatsApp 账号（首次启动需扫码或使用链接码登录）
• 使用 Docker 方式需已安装 Docker
• 参与 monorepo 开发需 pnpm 11.15.1（工具链由 mise.toml 固定）

安装与启动步骤

1. 1选择合适版本

   v5 仍是 alpha 版本可能有问题，成熟的 v4 生产系统请留在 4.76.0，仅在测试或贡献 v5 时使用 alpha。

2. 2启动 Easy API

   运行 CLI 会启动 Easy API 实例并触发首次认证流程，同时为当前会话暴露交互式文档。

   npx @open-wa/wa-automate@alpha --port 8080

   复制

3. 3完成登录认证

   按运行时提示认证：扫描终端打印的二维码，或改用适合你的链接码登录方式。

4. 4打开接口文档验证

   会话连接后访问 api-docs 页面，能看到交互文档即说明会话已上线、API 可访问。

5. 5多会话与鉴权

   若要跑多个账号，尽早指定 session-id；对暴露到本机之外的 API 建议加 api-key 保护。

   npx @open-wa/wa-automate@alpha --session-id sales --port 8081

   复制

6. 6用配置文件启动

   同目录下新建 wa.config.mjs，写入 apiKey、port 与 mcp 配置，再通过 --config 参数加载启动。

   WA_API_KEY="your-secure-key" npx @open-wa/wa-automate@alpha --config ./wa.config.mjs

   复制

7. 7Docker 方式运行

   拉取 openwa/wa-automate 镜像并映射 8080 端口，加 --init 让初始化进程清理僵尸进程。

   docker run -p 8080:8080 --init openwa/wa-automate

   复制

8. 8嵌入式运行时

   需要自己掌控浏览器驱动与生命周期时，安装核心包与驱动包，在代码中调用 createClient。

   npm install @open-wa/wa-automate @open-wa/driver-puppeteer

   复制

关键配置

如何确认成功

访问 http://localhost:8080/api-docs/ ，页面正常显示交互文档即表示会话已连接、API 可访问。

常见问题

注意事项

• 本项目为非官方项目，与 WhatsApp、Meta 无关联，使用风险自负，使用即表示同意其服务条款。
• v5 为 alpha 版本，建议先在可丢弃的环境中测试，再接入重要系统。
• Docker 方式适合本地测试或一次性的首次运行，除非同时做好会话持久化规划。
• 旧文档或示例提到的部分参数可能已过时，请以你实际运行版本验证过的参数集为准。