Wechaty 入门

关于 Wechaty

Wechaty 是一个面向聊天机器人开发者的对话式 RPA（机器人流程自动化）SDK（软件开发工具包）。它设计精良，API 简单易用。支持所有操作系统，包括 Linux、OSX、Win32 和 Docker，以及众多即时通讯平台，如微信、企业微信、WhatsApp、飞书、Gitter 等。

作为开发者，您可以使用 Wechaty 轻松构建自己的机器人，高效管理消息的收发、创建群聊并发送邀请、添加好友，并在用户与您的机器人之间巧妙地融入人工智能功能。

关于 Wechaty 入门项目

如果您是 Wechaty 的完全新手，那么这个项目将是您的最佳起点。您可以在几分钟内通过云端 IDE 运行它，也可以按照以下章节的说明在本地机器上进行设置。

如果您遇到困难或有任何疑问，欢迎在我们的 Discord 社区 https://discord.gg/7q8NBZbQzt 寻求帮助。

注意：当前 Wechaty 的活跃版本是 v1.x，它与大多数 v0.x 模块不兼容。

• wechaty@0.x - 如果您想使用 Wechaty v0.x，请访问 Wechaty 入门 v0.x 分支。

Wechaty 入门项目的特性

1. 在 Linux、Mac 或 Windows 上开箱即用。
2. 支持所有客户端，如 Web、Pad、Windows 和 Mac。
3. 当收到 ding 消息时，会回复一条 dong 消息。

Wechaty 入门视频教程

以上是一个简短的演示，展示了如何使用微信、WhatsApp 和企业微信部署 ding-dong 机器人。

在云端 IDE 上运行 Wechaty 入门项目

开始使用 Wechaty 最快的方式是使用云端 IDE 来运行 Wechaty 入门项目。您可以选择 Gitpod 或 Google Cloud Shell。

如果您是完全的新手，我们推荐使用 Gitpod。

使用 Gitpod ❤️ Wechaty

Gitpod 是一个在线开源平台，用于提供自动化的、开箱即用的开发环境。您可以点击下方按钮，在 Gitpod 上访问 Wechaty 入门 ding-dong BOT 项目的完整配置。如果您之前从未使用过 Gitpod，您需要使用 GitHub 账号登录。

您可以通过我们的博客了解更多关于 Gitpod ❤️ Wechaty 的信息：无需离开浏览器即可入门：Wechaty ❤️ Gitpod，@huan，2021 年 2 月 6 日

使用 Google Cloud Shell

Google Cloud Shell 是一个可通过浏览器随时随地访问的在线开发和运维环境。您可以通过点击下方按钮在 Google Cloud Shell 上运行该项目。

由 open-in-cloud-shell 生成

打开 Google Cloud Shell 编辑器后，右侧面板中应该会有一个打开的教程，您可以按照该教程进一步了解 Wechaty。

有关在 Google Cloud Shell 上运行该项目的更多信息，请参阅我们的博客：Wechaty 的 Google Cloud Shell 教程，@huan，2021 年 2 月 20 日

在本地机器上运行 Wechaty 入门项目

前提条件

要在您的本地机器上运行该项目，您需要：

1. 已在您的机器上安装 Node.js v16 或更高版本。您可以在终端运行 node -v 命令来检查是否已安装 Node.js。如果已安装，您应该能在终端看到类似 v16.13.0 的版本号。您的版本可能与 v16.13.0 不同。如果未安装或版本低于 16，您需要按照以下链接安装最新版本：

   • Windows
   • Linux（Debian/Ubuntu）
   • macOS

   其他平台的 Node.js 可以在 https://nodejs.org/en/download/package-manager/ 找到。

2. 如果您想使用 Web 以外的 RPA 协议，需要拥有 Wechaty Puppet Service TOKEN。

步骤 1：克隆此仓库

您需要将此仓库克隆到本地机器上，然后通过以下命令切换到 wechaty-getting-started 目录。

git clone https://github.com/wechaty/getting-started.git
cd getting-started

步骤 2：安装依赖项

您需要通过以下命令安装依赖项。

npm install

步骤 3：运行机器人

在 Linux 中可以使用 export 设置环境变量，在 Windows 中则使用 set。如果在运行此命令时遇到错误，请查看第 4 步中的故障排除提示。

Linux

export WECHATY_LOG=verbose
export WECHATY_PUPPET=wechaty-puppet-wechat
npm start
# 上述命令等同于以下命令：
# npx ts-node examples/ding-dong-bot.ts

Windows

set WECHATY_LOG=verbose
set WECHATY_PUPPET=wechaty-puppet-wechat
npm start
# 上述命令等同于以下命令：
# npx ts-node examples/ding-dong-bot.ts

现在您已经准备好了！

步骤 4：故障排除

如果您在按照上述步骤操作时遇到问题，请尝试以下方法。您也可以在我们的 gitter 聊天室 中提问。

1. 如果您使用的是 Windows，可能还需要 windows-build-tool：

   npm install windows-build-tools
   

使用不同的木偶

在我们的入门示例中，当未设置 WECHATY_PUPPET 时，ding-dong BOT 会使用 wechaty-puppet-wechat4u，这主要是为了方便新手使用。

默认情况下，Wechaty 会使用 Puppet Service 来登录你的机器人。你也可以使用其他 Puppet Provider，比如 WhatsApp Web 协议（wechaty-puppet-whatsapp）。

如果你想使用 Wechaty Puppet Provider 的其他协议，就需要通过设置环境变量 WECHATY_PUPPET 来指定一个木偶服务提供商名称（与它的 NPM 名称相同）。

感谢社区的大力贡献，目前有许多 Wechaty 木偶可供 Wechaty 使用。它们帮助我们支持 Web、Pad、Mac 和 Windows 等多种协议。

Wechaty 木偶

协议	NPM
Puppet Service	wechaty-puppet-service
Whatsapp Web	wechaty-puppet-whatsapp
微信 Web	wechaty-puppet-wechat
微信 Pad	wechaty-puppet-padlocal

访问我们的官网了解更多关于 Wechaty Puppet 服务提供商 的信息。

例如，如果你想使用 padlocal 木偶，你应该在运行 npm start 之前设置 WECHATY_PUPPET=wechaty-puppet-padlocal。同时，你还需要为 wechaty-puppet-padlocal 准备一个 TOKEN，并将其设置到环境变量 WECHATY_PUPPET_PADLOCAL_TOKEN 中。你可以从 这里 申请 PadLocal TOKEN。下面的代码片段展示了上述内容在 Linux/macOS 和 Windows 上的具体操作。

在 Linux / macOS 上

export WECHATY_PUPPET=wechaty-puppet-padlocal
export WECHATY_PUPPET_PADLOCAL_TOKEN='puppet_padlocal_your-token-here'
npm start

在 Windows 上

set WECHATY_PUPPET=wechaty-puppet-padlocal
set WECHATY_PUPPET_PADLOCAL_TOKEN='puppet_padlocal_your-token-here'
npm start

更多关于在 Windows 上安装 Wechaty 的信息，请参阅这篇 博客文章。

进阶教程

1. Wechaty 教程

以上是一个 10 分钟的视频教程。它使用的是 Wechaty 0.14 或更早版本，因此已经有些过时了。如果你是 Wechaty 的新手，这是一个不错的入门方式。

2. 更多示例

注意：在尝试更多示例之前，请确保你已经试用了本仓库中的 Wechaty 入门项目。

• 官方 Wechaty 示例目录

API 参考

1. 官方 API 文档： https://wechaty.js.org/docs/api

更多资源

1. Docker Wechaty 入门

https://github.com/wechaty/docker-wechaty-getting-started

2. Heroku Wechaty 入门

https://github.com/wechaty/heroku-wechaty-getting-started

3. Wechaty 主页

https://wechaty.github.io

常见问题解答

1. 我无法用我的微信账号登录

2017 年之后注册的微信账号将无法通过 Web API 登录。更多信息请参见 https://github.com/Chatie/wechaty/issues/872。

解决方案：你可以使用 Wechaty 支持的其他协议，比如 pad。更多信息请参见 https://github.com/Chatie/wechaty/issues/1296。

2. Wechaty 中的“木偶”是什么？

在 Wechaty 中，“木偶”（Puppet）是一个用于实现协议插件的抽象类。这些插件是帮助 Wechaty 控制微信的关键组件，这也是我们称之为“木偶”的原因。

插件通常命名为“PuppetXXX”，例如 PuppetWeChat 使用 Google Puppeteer 通过 Chrome 浏览器控制 微信 Web API，而 PuppetPadchat 则使用 WebSocket 协议连接到协议服务器来控制 iPad 版微信程序。更多详细信息可以参考 维基中的木偶章节。

有关 Wechaty 木偶的更多信息，请参阅我们的文档 Wechaty 木偶。

Wechaty 多语言入门

• TypeScript 版本的 Wechaty 入门
• Python 版本的 Wechaty 入门
• Go 版本的 Wechaty 入门
• Java 版本的 Wechaty 入门
• Scala 版本的 Wechaty 入门
• PHP 版本的 Wechaty 入门
• .NET(C#) 版本的 Wechaty 入门

历史

main v1.18（2022年3月14日）

添加 CQRS Wechaty 示例。

v1.11（2021年10月30日）

分支：v1.11：发布 Wechaty v1.11。

1. v0.13：启用 ESM（ES 模块）支持（chatie/tsconfig#16）。

v0.8（2021年2月20日）

使用 Google Cloud Shell 快速搭建！

v0.6（2021年2月11日）

使用 Gitpod 快速搭建！

v0.0.1（2017年1月12日）

初始版本

贡献者

维护者

@wechaty/contributors

版权与许可

• 代码及文档 © 2018至今 Huan 和 Wechaty 贡献者
• 代码采用 Apache-2.0 许可证发布
• 文档采用知识共享许可协议发布

Wechaty 快速上手指南

Wechaty 是一款专为聊天机器人开发者设计的对话式 RPA（机器人流程自动化）SDK。它支持微信、企业微信、WhatsApp、飞书等多种即时通讯协议，并兼容 Linux、macOS、Windows 及 Docker 环境。本指南将帮助你快速在本地运行一个基础的“丁丁东东”（Ding-Dong）机器人示例。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

1. Node.js: 版本需为 v16 或更高。
   • 检查版本命令：node -v
   • 若未安装或版本过低，请访问 Node.js 官网 下载最新版。
   • 国内用户推荐：可使用 cnpm 或配置淘宝镜像源加速依赖安装。
2. Git: 用于克隆项目代码。
3. Puppet Token (可选):
   • 默认示例使用 wechaty-puppet-wechat (基于 Web 协议)。注意：2017 年后注册的微信账号可能无法通过 Web 协议登录。
   • 若需使用其他协议（如 Pad、Windows 等），需提前在 Wechaty Puppet Service 获取对应的 TOKEN。

安装步骤

1. 克隆项目

将仓库克隆到本地并进入项目目录：

git clone https://github.com/wechaty/getting-started.git
cd getting-started

2. 安装依赖

安装项目所需的 npm 包。国内建议使用镜像源以提高速度：

# 使用官方源
npm install

# 或使用国内镜像源 (推荐)
npm install --registry=https://registry.npmmirror.com

注意：Windows 用户若在安装过程中遇到编译错误，可能需要先安装构建工具： npm install windows-build-tools

基本使用

本项目默认包含一个最简单的机器人示例：当收到消息"ding"时，自动回复"dong"。

运行默认示例 (Web 协议)

根据你的操作系统，设置环境变量并启动机器人：

Linux / macOS:

export WECHATY_LOG=verbose
export WECHATY_PUPPET=wechaty-puppet-wechat
npm start

Windows (CMD):

set WECHATY_LOG=verbose
set WECHATY_PUPPET=wechaty-puppet-wechat
npm start

启动后，终端会显示一个二维码。使用微信扫描二维码即可登录，随后机器人将开始工作。

切换其他协议 (例如 PadLocal)

如果你需要使用非 Web 协议（以 PadLocal 为例），需指定 Puppet 名称并配置对应的 TOKEN：

Linux / macOS:

export WECHATY_PUPPET=wechaty-puppet-padlocal
export WECHATY_PUPPET_PADLOCAL_TOKEN='puppet_padlocal_your-token-here'
npm start

Windows (CMD):

set WECHATY_PUPPET=wechaty-puppet-padlocal
set WECHATY_PUPPET_PADLOCAL_TOKEN='puppet_padlocal_your-token-here'
npm start

请将 'puppet_padlocal_your-token-here' 替换为你实际申请的 Token。

---

更多高级示例请查看项目中的 examples 目录，或访问 Wechaty 官方文档。