如果您正在使用此工具产生收益，请考虑通过成为 Patreon 成员来支持其开发！ 您的支持将有助于确保该库得到持续维护和定期更新！

---

支持 ARM 和 AMD 架构，并提供 MCP 支持

下载：

• 发布页面
• Docker Hub
• GitHub 容器注册表

支持 n8n 包（n8n.io）

• n8n 包
• 前往设置 -> 社区节点 -> 输入 @aldinokemal2104/n8n-nodes-gowa -> 安装

重大变更

• v6
  • 对于 REST 模式，您需要运行 <二进制文件> rest，而不是直接运行 <二进制文件>。
    • 例如：./whatsapp rest 而不是 ./whatsapp。
  • 对于 MCP 模式，您需要运行 <二进制文件> mcp。
    • 例如：./whatsapp mcp。
• v7
  • 从 7.x 版本开始，我们使用 goreleaser 来构建二进制文件，因此您可以从 发布页面 下载二进制文件。
• v8

  • 多设备支持：现在您可以在单个服务器实例中同时连接和管理多个 WhatsApp 账号。

  • 新的设备管理 API：新增了 /devices 路径下的端点，用于管理多个设备。

  • 设备作用域要求：所有与设备相关的 REST API 调用现在都需要以下任一方式：

    • X-Device-Id 请求头，或
    • device_id 查询参数。
    • 如果仅注册了一个设备，则该设备将作为默认设备。

  • WebSocket 设备作用域：通过连接到 /ws?device_id=<id> 可以将 WebSocket 限定在特定设备上。

  • Webhook 负载变化：所有 webhook 负载现在都包含一个顶级的 device_id 字段，用于标识接收事件的具体设备：

    ```json
    {
      "event": "message",
      "device_id": "628123456789@s.whatsapp.net",
      "payload": { ... }
    }
    ```
    

功能

• 通过 HTTP API 发送 WhatsApp 消息，更多详情请参阅 docs/openapi.yml

• MCP（模型上下文协议）服务器支持 - 使用标准化协议与 AI 代理和工具集成

• 提及某人

  • @phoneNumber
  • 示例：Hello @628974812XXXX, @628974812XXXX

• 幽灵提及（全员提及） - 在不显示消息文本中 @phone 的情况下提及群组成员

  • 将电话号码传递到 mentions 字段以在消息中提及用户而不显示可见的 @
  • 使用特殊关键字 @everyone 自动提及所有群组成员
  • 群组发送消息模态框中提供 UI 复选框

• 发布 WhatsApp 状态

• 发送贴纸 - 自动将图片转换为 WebP 贴纸格式

  • 支持 JPG、JPEG、PNG、WebP 和 GIF 格式
  • 自动调整大小至 512x512 像素
  • 保留 PNG 图片的透明度
  • 动画 WebP 贴纸 受支持，但必须符合 WhatsApp 要求：
    • 必须精确为 512x512 像素
    • 文件大小不得超过 500KB
    • 最长持续时间为 10 秒
    • 如果您的动画贴纸不符合这些要求，请使用 ezgif.com 等工具在上传前调整其尺寸

• 发送前压缩图片

• 发送前压缩视频

• 更改操作系统名称为您的应用名称（这是通过手机连接时的设备名称）

  • --os=Chrome 或 --os=MyApplication

• 基本认证（可添加多个凭证）

  • --basic-auth=kemal:secret,toni:password,userName:secretPassword，或者您可以简化为
  • -b=kemal:secret,toni:password,userName:secretPassword

• 子路径部署支持

  • --base-path="/gowa"（允许在特定路径下部署，例如 /gowa/sub/path）

• 可自定义端口和调试模式

  • --port 8000
  • --debug true

• 自动回复消息

  • --autoreply="Don't reply this message"

• 自动标记已读传入消息

  • --auto-mark-read=true（自动将传入消息标记为已读）

• 自动下载传入消息中的媒体

  • --auto-download-media=false（禁用自动下载媒体，默认值为 true）

• 自动拒绝来电

  • --auto-reject-call=true 或 WHATSAPP_AUTO_REJECT_CALL=true（有关呼叫事件，请参阅 Webhook 负载）

• 连接时可配置在线状态

  • --presence-on-connect=unavailable 或 WHATSAPP_PRESENCE_ON_CONNECT=unavailable
  • available — 标记为在线（抑制手机通知）
  • unavailable — 注册推送名称而不上线（默认设置，保留手机通知）
  • none — 完全跳过在线状态（不会注册推送名称，联系人可能会看到“-”作为名称）

• 接收消息的 Webhook

  • --webhook="http://yourwebhook.site/handler"，或者您可以简化为
  • -w="http://yourwebhook.site/handler"
  • 更多详情请参阅 Webhook 负载文档

• Webhook 密钥 我们的 Webhook 将附带 HMAC 头部和默认密钥 secret 的 sha256 签名发送给您。 您可以使用以下选项修改此密钥：

  • --webhook-secret="secret"

• Webhook 负载文档 有关详细的 Webhook 负载模式、安全实施和集成示例，请参阅 Webhook 负载文档

• Webhook 事件过滤 您可以通过以下方式过滤转发到您的 Webhook 的事件：

  • --webhook-events="message,message.ack"（逗号分隔列表）
  • 或环境变量：WHATSAPP_WEBHOOK_EVENTS=message,message.ack

  可用的 Webhook 事件：

  事件	描述
  message	文本、媒体、联系人、位置消息
  message.reaction	对消息的表情符号反应
  message.revoked	已删除/撤销的消息
  message.edited	已编辑的消息
  message.ack	投递和已读回执
  message.deleted	用户删除的消息
  group.participants	群组成员加入/离开/晋升/降级事件
  group.joined	您被添加到一个群组
  newsletter.joined	您订阅了一个新闻通讯/频道
  newsletter.left	您退订了一个新闻通讯
  newsletter.message	新闻通讯中发布的新消息
  newsletter.mute	新闻通讯静音设置变更
  call.offer	收到的来电

  如果未配置（为空），则所有事件都将被转发。

• Webhook TLS 配置

  如果您在使用 Webhook 时遇到 TLS 证书验证错误（例如使用 Cloudflare 隧道或自签名证书时）：

  tls: failed to verify certificate: x509: certificate signed by unknown authority
  

  您可以通过以下方式禁用 TLS 证书验证：

  • --webhook-insecure-skip-verify=true
  • 或环境变量： WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true

  安全警告：此选项会禁用 TLS 证书验证，仅应在以下情况下使用：

  • 开发/测试环境
  • Cloudflare 隧道（它们本身提供安全层）
  • 具有自签名证书的内部网络

  对于生产环境，强烈建议使用正确的 SSL 证书（例如 Let's Encrypt），而不是禁用验证。

配置

您可以使用命令行标志（如上所示）或环境变量来配置应用程序。配置可以通过三种方式设置（按优先级顺序）：

1. 命令行标志（最高优先级）
2. 环境变量
3. .env 文件（最低优先级）

环境变量

你可以使用环境变量来配置应用程序。配置可以通过三种方式设置（按优先级从高到低）：

1. 命令行标志（最高优先级）
2. 环境变量
3. .env 文件（最低优先级）

要使用环境变量，请按照以下步骤操作：

1. 将 .env.example 复制到项目根目录下的 .env 文件中（cp src/.env.example src/.env）
2. 根据你的需求修改 .env 文件中的值
3. 或者将相同的变量设置为系统环境变量

可用的环境变量

变量	描述	默认	示例
APP_PORT	应用程序端口	3000	APP_PORT=8080
APP_HOST	服务器绑定的主机地址	0.0.0.0	APP_HOST=127.0.0.1
APP_DEBUG	启用调试日志	false	APP_DEBUG=true
APP_OS	操作系统名称（WhatsApp 中的设备名称）	Chrome	APP_OS=MyApp
APP_BASIC_AUTH	基本认证凭据	-	APP_BASIC_AUTH=user1:pass1,user2:pass2
APP_BASE_PATH	用于子路径部署的基路径	-	APP_BASE_PATH=/gowa
APP_TRUSTED_PROXIES	反向代理的信任代理 IP 范围	-	APP_TRUSTED_PROXIES=0.0.0.0/0
DB_URI	数据库连接 URI	file:storages/whatsapp.db?_foreign_keys=on	DB_URI=postgres://user:pass@host/db
WHATSAPP_AUTO_REPLY	自动回复消息	-	WHATSAPP_AUTO_REPLY="自动回复消息"
WHATSAPP_AUTO_MARK_READ	自动将收到的消息标记为已读	false	WHATSAPP_AUTO_MARK_READ=true
WHATSAPP_AUTO_DOWNLOAD_MEDIA	自动下载来自收到消息的媒体	true	WHATSAPP_AUTO_DOWNLOAD_MEDIA=false
WHATSAPP_WEBHOOK	事件的 Webhook URL（逗号分隔）	-	WHATSAPP_WEBHOOK=https://webhook.site/xxx
WHATSAPP_WEBHOOK_SECRET	用于验证的 Webhook 密钥	secret	WHATSAPP_WEBHOOK_SECRET=super-secret-key
WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY	跳过 Webhook 的 TLS 验证（不安全）	false	WHATSAPP_WEBHOOK_INSECURE_SKIP_VERIFY=true
WHATSAPP_WEBHOOK_EVENTS	要转发的事件白名单（逗号分隔，空表示全部）	-	WHATSAPP_WEBHOOK_EVENTS=message,message.ack
WHATSAPP_ACCOUNT_VALIDATION	启用账号验证	true	WHATSAPP_ACCOUNT_VALIDATION=false
WHATSAPP_PRESENCE_ON_CONNECT	连接时的状态：available、unavailable 或 none	unavailable	WHATSAPP_PRESENCE_ON_CONNECT=unavailable
CHATWOOT_ENABLED	启用 Chatwoot 集成	false	CHATWOOT_ENABLED=true
CHATWOOT_URL	Chatwoot 实例的 URL	-	CHATWOOT_URL=https://app.chatwoot.com
CHATWOOT_API_TOKEN	Chatwoot API 访问令牌	-	CHATWOOT_API_TOKEN=your-api-token
CHATWOOT_ACCOUNT_ID	Chatwoot 账户 ID	-	CHATWOOT_ACCOUNT_ID=12345
CHATWOOT_INBOX_ID	Chatwoot 收件箱 ID	-	CHATWOOT_INBOX_ID=67890
CHATWOOT_DEVICE_ID	Chatwoot 的 WhatsApp 设备 ID（多设备设置）	-	CHATWOOT_DEVICE_ID=628xxx@s.whatsapp.net
CHATWOOT_IMPORT_MESSAGES	启用消息历史同步到 Chatwoot	false	CHATWOOT_IMPORT_MESSAGES=true
CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES	要导入的历史天数	3	CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES=7

文档：

• 有关详细的 Webhook 负载模式、安全实现和集成示例，请参阅 Webhook 负载文档
• 有关全面的 Chatwoot 集成指南，请参阅 Chatwoot 集成文档

注意：命令行标志会覆盖在环境变量或 .env 文件中设置的任何值。

• 更多命令信息请运行 ./whatsapp --help

要求

系统要求

• Go 1.24.0 或更高版本（用于从源代码构建）
• FFmpeg（用于媒体处理）

平台支持

• Linux（x86_64、ARM64）
• macOS（Intel、Apple Silicon）
• Windows（x86_64）——建议使用 WSL

依赖项（不使用 Docker）

• macOS：
  • brew install ffmpeg webp
  • export CGO_CFLAGS_ALLOW="-Xpreprocessor"
• Linux：
  • sudo apt update
  • sudo apt install ffmpeg webp
• Windows（不推荐，建议使用 WSL）：
  • 安装 FFmpeg：在此下载
  • 安装 libwebp：在此下载（解压后将 bin 文件夹添加到 PATH）
  • 将两者都添加到环境变量

注意：webp 包提供了 cwebp（编码器）、dwebp（解码器）和 webpmux（帧提取工具）等工具。 FFmpeg 用于媒体处理。libwebp 工具（webpmux + dwebp）则用于支持动画 WebP 贴纸。

使用方法

基本用法

1. 克隆本仓库：git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
2. 通过命令行或终端打开克隆后的文件夹。
3. 运行 cd src
4. 运行 go run . rest（以 REST API 模式运行）
5. 打开 http://localhost:3000

使用 Docker（无需安装依赖）

1. 克隆本仓库：git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
2. 通过命令行或终端打开克隆后的文件夹。
3. 运行 docker-compose up -d --build
4. 打开 http://localhost:3000

构建自己的二进制文件

1. 克隆本仓库：git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
2. 通过命令行或终端打开克隆后的文件夹。
3. 运行 cd src
4. 执行以下命令：
   1. Linux 和 macOS：go build -o whatsapp
   2. Windows（CMD / PowerShell）：go build -o whatsapp.exe
5. 运行：
   1. Linux 和 macOS：./whatsapp rest（以 REST API 模式运行）
      1. 运行 ./whatsapp --help 查看更多详细选项
   2. Windows：.\whatsapp.exe rest（以 REST API 模式运行）
      1. 运行 .\whatsapp.exe --help 查看更多详细选项
6. 在浏览器中打开 http://localhost:3000

MCP 服务器（模型上下文协议）

本应用还可以作为 MCP 服务器运行，允许 AI 代理和工具通过标准化协议与 WhatsApp 交互。

1. 克隆本仓库：git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice
2. 通过命令行或终端打开克隆后的文件夹。
3. 运行 cd src
4. 运行 go run . mcp，或者构建二进制文件后运行 ./whatsapp mcp
5. MCP 服务器默认会在 http://localhost:8080 启动

MCP 服务器选项

• --host localhost：设置 MCP 服务器的主机地址（默认：localhost）
• --port 8080：设置 MCP 服务器的端口（默认：8080）

可用的 MCP 工具

WhatsApp 的 MCP 服务器提供了一整套工具，供 AI 代理通过标准化协议与 WhatsApp 交互。以下是所有可用工具的完整列表：

📱 连接管理

• whatsapp_connection_status：检查 WhatsApp 客户端是否已连接并登录
• whatsapp_login_qr：启动基于二维码的登录流程，并输出图片
• whatsapp_login_with_code：生成配对码，用于通过手机号进行多设备登录
• whatsapp_logout：注销当前 WhatsApp 会话
• whatsapp_reconnect：尝试使用已保存的会话重新连接 WhatsApp

💬 消息与通信

• whatsapp_send_text：发送文本消息，支持回复和转发
• whatsapp_send_contact：发送包含姓名和电话号码的联系人卡片
• whatsapp_send_link：发送带有自定义标题的链接
• whatsapp_send_location：发送位置坐标（经纬度）
• whatsapp_send_image：发送图片，支持添加标题、压缩及阅后即焚功能
• whatsapp_send_sticker：发送贴纸，自动转换为 WebP 格式（支持 JPG/PNG/GIF）

📋 聊天与联系人管理

• whatsapp_list_contacts：获取 WhatsApp 账户中的所有联系人
• whatsapp_list_chats：获取最近的聊天记录，支持分页和搜索过滤
• whatsapp_get_chat_messages：从特定聊天中获取消息，支持按时间及媒体类型筛选
• whatsapp_download_message_media：下载消息中的图片或视频
• whatsapp_archive_chat：归档或取消归档聊天对话

👥 群组管理

• whatsapp_group_create：创建新群组，可选择初始成员
• whatsapp_group_join_via_link：通过邀请链接加入群组
• whatsapp_group_leave：根据群组 ID 退出群组
• whatsapp_group_participants：列出群组内的所有成员
• whatsapp_group_manage_participants：添加、移除、提升或降级群组成员
• whatsapp_group_invite_link：获取或重置群组邀请链接
• whatsapp_group_info：获取详细的群组信息
• whatsapp_group_set_name：更新群组显示名称
• whatsapp_group_set_topic：更新群组描述或主题
• whatsapp_group_set_locked：切换仅管理员可编辑群组信息模式
• whatsapp_group_set_announce：切换仅公告模式
• whatsapp_group_join_requests：列出待处理的入群申请
• whatsapp_group_manage_join_requests：批准或拒绝入群申请

MCP 端点

• SSE 端点：http://localhost:8080/sse
• 消息端点：http://localhost:8080/message

MCP 配置

确保 MCP 服务器正在运行：./whatsapp mcp

对于支持 MCP 和 SSE 的 AI 工具（如 Cursor），请添加以下配置：

{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:8080/sse"
    }
  }
}

生产环境 REST 模式（Docker）

使用 Docker Hub：

docker run --detach --publish=3000:3000 --name=whatsapp --restart=always --volume=$(docker volume create --name=whatsapp):/app/storages aldinokemal2104/go-whatsapp-web-multidevice rest --autoreply="Dont't reply this message please"

使用 GitHub Container Registry：

docker run --detach --publish=3000:3000 --name=whatsapp --restart=always --volume=$(docker volume create --name=whatsapp):/app/storages ghcr.io/aldinokemal/go-whatsapp-web-multidevice rest --autoreply="Dont't reply this message please"

生产模式 REST（Docker Compose）

创建 docker-compose.yml 文件，配置如下：

使用 Docker Hub：

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp:

使用 GitHub Container Registry：

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    command:
      - rest
      - --basic-auth=admin:admin
      - --port=3000
      - --debug=true
      - --os=Chrome
      - --account-validation=false

volumes:
  whatsapp:

或者使用环境变量文件（Docker Hub）：

services:
  whatsapp:
    image: aldinokemal2104/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - APP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

或者使用环境变量文件（GitHub Container Registry）：

services:
  whatsapp:
    image: ghcr.io/aldinokemal/go-whatsapp-web-multidevice
    container_name: whatsapp
    restart: always
    ports:
      - "3000:3000"
    volumes:
      - whatsapp:/app/storages
    environment:
      - APP_BASIC_AUTH=admin:admin
      - APP_PORT=3000
      - APP_DEBUG=true
      - APP_OS=Chrome
      - APP_ACCOUNT_VALIDATION=false

volumes:
  whatsapp:

生产模式（二进制文件）

• 从 release 下载二进制文件

您可以 fork 或编辑此源代码！

当前 API

MCP（模型上下文协议）API

• MCP 服务器为 AI 代理提供与 WhatsApp 交互的标准化工具。
• 支持 Server-Sent Events (SSE) 传输。
• 可用工具：whatsapp_send_text、whatsapp_send_contact、whatsapp_send_link、whatsapp_send_location。
• 兼容支持 MCP 的 AI 工具和代理。

HTTP REST API

• 详细 API 规范请参阅 docs/openapi.yml。
• 使用 SwaggerEditor 可视化 API。
• 可以使用 openapi-generator 生成 HTTP 客户端。

功能	菜单	方法	URL
✅	列出设备	GET	/devices
✅	添加设备	POST	/devices
✅	获取设备信息	GET	/devices/:device_id
✅	删除设备	DELETE	/devices/:device_id
✅	设备登录（二维码）	GET	/devices/:device_id/login
✅	设备登录（验证码）	POST	/devices/:device_id/login/code
✅	设备登出	POST	/devices/:device_id/logout
✅	重新连接设备	POST	/devices/:device_id/reconnect
✅	获取设备状态	GET	/devices/:device_id/status
✅	使用扫描二维码登录	GET	/app/login
✅	使用配对码登录	GET	/app/login-with-code
✅	登出	GET	/app/logout
✅	重新连接	GET	/app/reconnect
✅	设备列表	GET	/app/devices
✅	连接状态	GET	/app/status
✅	用户信息	GET	/user/info
✅	用户头像	GET	/user/avatar
✅	更改用户头像	POST	/user/avatar
✅	更改用户昵称	POST	/user/pushname
✅	用户我的群组*	GET	/user/my/groups
✅	用户我的新闻通讯	GET	/user/my/newsletters
✅	用户隐私设置	GET	/user/my/privacy
✅	用户联系人	GET	/user/my/contacts
✅	用户检查	GET	/user/check
✅	用户企业资料	GET	/user/business-profile
✅	发送消息	POST	/send/message
✅	发送图片	POST	/send/image
✅	发送音频	POST	/send/audio
✅	发送文件	POST	/send/file
✅	发送视频	POST	/send/video
✅	发送贴纸	POST	/send/sticker
✅	发送联系人	POST	/send/contact
✅	发送链接	POST	/send/link
✅	发送位置	POST	/send/location
✅	发送投票/民意调查	POST	/send/poll
✅	发送在线状态	POST	/send/presence
✅	发送聊天在线状态（打字提示）	POST	/send/chat-presence
✅	撤回消息	POST	/message/:message_id/revoke
✅	回复消息	POST	/message/:message_id/reaction
✅	删除消息	POST	/message/:message_id/delete
✅	编辑消息	POST	/message/:message_id/update
✅	标记消息已读（私信）	POST	/message/:message_id/read
✅	收藏消息	POST	/message/:message_id/star
✅	取消收藏消息	POST	/message/:message_id/unstar
✅	下载消息媒体	GET	/message/:message_id/download
✅	使用链接加入群组	POST	/group/join-with-link
✅	通过链接获取群组信息	GET	/group/info-from-link
✅	获取群组信息	GET	/group/info
✅	退出群组	POST	/group/leave
✅	创建群组	POST	/group
✅	列出群组成员	GET	/group/participants
✅	添加群组成员	POST	/group/participants
✅	移除群组成员	POST	/group/participants/remove
✅	提升群组成员等级	POST	/group/participants/promote
✅	降低群组成员等级	POST	/group/participants/demote
✅	导出群组成员（CSV）	GET	/group/participants/export
✅	列出群组申请的成员	GET	/group/participant-requests
✅	批准群组申请的成员	POST	/group/participant-requests/approve
✅	拒绝群组申请的成员	POST	/group/participant-requests/reject
✅	设置群组头像	POST	/group/photo
✅	设置群组名称	POST	/group/name
✅	锁定群组	POST	/group/locked
✅	开启群组公告模式	POST	/group/announce
✅	设置群组话题	POST	/group/topic
✅	获取群组邀请链接	GET	/group/invite-link
✅	取消关注新闻通讯	POST	/newsletter/unfollow
✅	获取聊天列表	GET	/chats
✅	获取聊天消息	GET	/chat/:chat_jid/messages
✅	为聊天标记	POST	/chat/:chat_jid/label
✅	置顶聊天	POST	/chat/:chat_jid/pin
✅	归档聊天	POST	/chat/:chat_jid/archive
✅	设置阅后即焚消息	POST	/chat/:chat_jid/disappearing

✅ = 可用
❌ = 尚不可用
* = 存在已知限制（见下方说明）

说明：

• *用户我的群组: 由于 WhatsApp 协议的限制，最多返回 500 个群组。这是由 WhatsApp 服务器强制执行的，而非本 API 的限制。详情请参阅 whatsmeow 源代码。

用户界面

MCP UI

• 设置 MCP（已在 cursor 中测试）
• 测试 MCP
• 成功设置 MCP

HTTP REST API UI

描述	图片
首页
登录
使用验证码登录
发送消息
发送图片
发送文件
发送视频
发送贴纸
发送联系人
发送位置
发送音频
发送投票
发送状态
发送链接
我的群组
通过链接获取群信息
创建群组
通过链接加入群组
管理群成员
我的新闻通讯
我的联系人
商业资料

Mac OS 注意事项

• 如果遇到错误（pkg-config --cflags 中出现无效标志 -Xpreprocessor），请执行以下操作： export CGO_CFLAGS_ALLOW="-Xpreprocessor"

重要提示

• 本项目为非官方项目，与 WhatsApp 官方无任何关联。
• 请使用 WhatsApp 官方 API，以避免任何问题。
• 目前我们仅能运行 MCP 或 REST API，这是 whatsmeow 库的限制。独立的 MCP 功能将在未来推出。

go-whatsapp-web-multidevice 快速上手指南

go-whatsapp-web-multidevice 是一个基于 Go 语言构建的高效 WhatsApp 多设备网关。它支持通过 HTTP API 发送消息、接收 webhook 回调，并原生支持 MCP (Model Context Protocol)，非常适合用于构建 AI 助手或自动化工作流。

环境准备

系统要求

• 架构支持：完美支持 ARM (如树莓派、Apple Silicon) 和 AMD (x86_64) 架构。
• 操作系统：Linux, macOS, Windows。
• 网络：服务器需能访问 WhatsApp 官方服务（若在国内部署，可能需要配置代理）。

前置依赖

本工具提供编译好的二进制文件和 Docker 镜像，无需安装 Go 语言环境即可直接使用。

• 若使用二进制文件：无额外依赖。
• 若使用 Docker：需安装 Docker Engine 和 Docker Compose。

---

安装步骤

你可以选择以下任意一种方式进行安装：

方式一：下载二进制文件（推荐）

1. 访问 GitHub Releases 页面。
2. 根据你的系统架构下载对应的压缩包（例如 go-whatsapp-web-multidevice_Linux_x86_64.tar.gz）。
3. 解压并赋予执行权限：

tar -xzf go-whatsapp-web-multidevice_Linux_x86_64.tar.gz
chmod +x whatsapp

注意：从 v6 版本开始，启动命令需指定模式。REST API 模式请使用 ./whatsapp rest。

方式二：使用 Docker

直接从 Docker Hub 拉取镜像：

docker pull aldinokemal2104/go-whatsapp-web-multidevice:latest

或者使用 GitHub Container Registry：

docker pull ghcr.io/aldinokemal/go-whatsapp-web-multidevice:latest

---

基本使用

1. 启动服务

使用二进制文件启动

运行以下命令启动 REST API 服务，监听 8000 端口：

./whatsapp rest --port 8000

常用参数示例（开启自动回复和 Webhook）：

./whatsapp rest --port 8000 --autoreply="收到消息，稍后回复" --webhook="http://your-server.com/handler"

使用 Docker 启动

docker run -d \
  --name gowa \
  -p 8000:3000 \
  -v $(pwd)/data:/app/storages \
  aldinokemal2104/go-whatsapp-web-multidevice:latest rest

注：默认容器内端口为 3000，上述命令将其映射到宿主机的 8000 端口。

2. 连接 WhatsApp 账号

1. 在浏览器中访问 http://localhost:8000（或你设置的 IP 和端口）。
2. 页面上将显示一个二维码。
3. 打开手机 WhatsApp：
   • Android: 点击右上角菜单 -> "已连接的设备" -> "连接设备"。
   • iOS: 进入 "设置" -> "已连接的设备" -> "连接设备"。
4. 扫描二维码进行绑定。支持同时绑定多个设备（多账号管理）。

3. 发送第一条消息

绑定成功后，你可以通过 HTTP API 发送消息。

示例：发送文本消息

curl -X POST http://localhost:8000/api/send-message \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "8613800138000",
    "message": "你好，这是来自 Go WA 的测试消息！"
  }'

示例：提及某人 (Mention)

curl -X POST http://localhost:8000/api/send-message \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "8613800138000@g.us",
    "message": "Hello @8613900139000, 请查看此消息。",
    "mentions": ["8613900139000@s.whatsapp.net"]
  }'

示例：发送贴纸 (自动转换格式)

curl -X POST http://localhost:8000/api/send-sticker \
  -F "phone=8613800138000" \
  -F "file=@/path/to/image.png"

4. 配置 Webhook (接收消息)

若要接收他人发来的消息，启动时添加 --webhook 参数：

./whatsapp rest --webhook="http://your-server.com/webhook" --webhook-secret="your_secret_key"

当收到消息时，工具会向你的地址发送 JSON Payload，包含 device_id 和消息内容。

---

提示：更多高级功能（如 MCP 集成、n8n 节点安装、环境变量配置等）请参考项目官方文档。