1. 项目概述与核心价值如果你和我一样经常需要在 macOS 上处理一些重复性的微信操作比如定时给家人发问候、批量转发通知或者只是想把自己的聊天记录整理成一份可读的文档那么手动操作不仅耗时还容易出错。市面上虽然有各种微信机器人框架但它们大多依赖官方或非官方的 API要么有封号风险要么配置复杂对普通用户极不友好。今天要聊的这个项目wechat-macos-proxy就提供了一种截然不同的思路它不碰微信的任何内部接口而是像一个“数字助手”通过模拟你在屏幕前的点击和输入来完成所有操作。简单来说它让 AI 帮你“看”屏幕和“操作”鼠标键盘。这个项目的核心价值在于它的“非侵入性”和“高兼容性”。因为它基于 macOS 系统级的 GUI 自动化技术所以理论上只要微信 for Mac 这个客户端能正常打开和使用这个工具就能工作。它不修改微信的任何文件不注入任何代码只是作为一个外部的自动化脚本在运行。这对于担心账号安全、又渴望提升效率的用户来说无疑是一个福音。我最初接触它就是为了解决每周需要向几十个群组发送周报摘要的痛点手动复制粘贴简直是一场噩梦。在尝试了多种方案后这个基于图形界面自动化的方案以其稳定和安全的特性吸引了我。接下来我会带你从零开始深入拆解这个工具的安装、配置、核心原理以及实际应用中的各种技巧和坑点。无论你是想实现简单的消息自动回复还是构建一个复杂的、与微信交互的自动化工作流这篇文章都能给你提供一份详实的实操指南。2. 核心原理与技术栈拆解2.1 为什么选择 GUI 自动化在深入代码之前我们必须先理解这个项目最根本的设计哲学为什么放弃 API选择 GUI 自动化这背后有几个关键考量。首先是安全与合规性。微信官方对非官方的 API 调用一直持严格管控态度。使用未公开的接口或协议进行通信轻则导致功能异常重则直接封禁账号。对于个人或企业的重要社交账号而言这种风险是不可接受的。GUI 自动化则完全在“模拟用户”的层面操作它所做的每一个点击、每一次输入都和你亲手操作无异。从微信客户端的视角看这就是一个真实的用户在操作因此从根本上规避了因调用非法接口而触发的风控机制。其次是稳定性和兼容性。微信客户端的 GUI 界面相对稳定虽然也会有改版但其核心的交互元素如搜索框、聊天输入框、发送按钮的变化频率远低于其内部通信协议。基于 GUI 自动化的工具其维护成本主要在于适配界面元素的定位逻辑这比逆向工程不断变化的网络协议要简单和可控得多。只要微信 for Mac 这个应用还在运行这个工具就有办法与之交互。最后是实现的普适性。这种思路不局限于微信。理论上任何拥有图形界面的 macOS 应用都可以通过类似的自动化技术进行操控。这为跨应用的自动化工作流打开了大门。wechat-macos-proxy项目可以看作是这个理念在微信这个具体应用上的成功实践。2.2 核心组件peekaboo 与 AppleScript项目的技术栈非常精简核心依赖是两个系统级工具peekaboo和AppleScript/JavaScript for Automation (JXA)。1. peekaboo屏幕的“眼睛”这是整个项目的“感知”部分。peekaboo是一个命令行工具它的核心功能是获取指定窗口或屏幕区域的截图。为什么不用系统自带的screencapture命令因为peekaboo提供了更精细的控制能力比如可以直接通过窗口名称或进程 ID 来截取特定应用的窗口并且能获取到窗口的详细元信息如坐标、层级。这对于需要精准定位微信聊天窗口和消息区域的自动化脚本至关重要。你可以把它理解为一个高性能、可编程的“截图工具”。2. AppleScript/JXA系统的“手”这是整个项目的“执行”部分。macOS 系统原生支持通过 AppleScript 或 JavaScript for Automation 来控制几乎所有应用程序。我们可以用它们来模拟几乎所有的用户交互激活应用、点击菜单、按下快捷键、在输入框键入文字等等。wechat-macos-proxy中的脚本大量使用了 JXA因为其语法更接近现代编程习惯来执行诸如“打开微信”、“聚焦到搜索框”、“输入联系人名称”、“点击发送按钮”等一系列操作。工作流程串联整个自动化流程就是一个“感知-决策-执行”的循环。例如要实现“发送消息”执行通过 JXA 激活微信打开搜索框输入联系人名并进入聊天窗口。感知通过peekaboo对聊天窗口进行截图确认输入框已就绪且界面状态正确没有弹窗遮挡等。执行再次通过 JXA 将焦点切换到输入框粘贴或键入消息内容模拟按下CommandEnter发送。感知可选步骤通过peekaboo截图验证消息是否发送成功例如检查消息是否出现在对话流中。这种将“看”和“做”分离的架构使得脚本逻辑清晰也便于调试——你可以在任何一步保存截图看看程序到底“看”到了什么。2.3 OpenClaw 技能框架的角色你可能注意到了项目的安装提到了ClawHub和OpenClaw skills 目录。OpenClaw是一个开源的 AI 智能体Agent框架它允许开发者将各种功能封装成“技能”。wechat-macos-proxy就是这样一个技能。这意味着你不仅可以独立运行它还可以将它集成到一个更强大的 AI 智能体中让 AI 根据聊天上下文自动决定何时、如何调用这个微信操作技能。例如你可以构建一个智能体当它收到邮件指令时自动解析指令内容并通过此技能发送微信消息。不过即使你不使用 OpenClaw 框架这个项目也完全可以作为独立的命令行工具运行这得益于它良好的模块化设计。我们接下来的讲解也将主要聚焦于其独立使用模式。3. 环境准备与安装详解3.1 系统与软件前置检查在开始安装之前请确保你的环境满足以下要求操作系统macOS 10.15 (Catalina) 或更高版本。这是许多现代命令行工具和权限系统的基础要求。微信客户端必须安装最新版的微信 for Mac。请从微信官网weixin.qq.com下载并登录你的账号。确保它能正常运行。HomebrewmacOS 的包管理器。如果未安装请在终端执行/bin/bash -c \$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\进行安装。注意建议在开始前先将微信更新到最新版本。新旧版本的界面布局可能存在细微差异使用最新版可以减少自动化脚本定位元素失败的概率。3.2 安装核心依赖peekaboo 与 jq打开终端我们逐一安装所需的命令行工具。1. 安装 peekaboobrew install steipete/tap/peekaboo这里我们通过steipete/tap这个 Homebrew 第三方仓库来安装。steipete是peekaboo工具的开发者。安装完成后可以在终端输入peekaboo --version来验证是否安装成功。2. 安装 jqbrew install jqjq是一个轻量级且强大的命令行 JSON 处理器。在本工具中它用于解析peekaboo输出的窗口信息 JSON 数据从而精准地获取微信窗口的坐标和尺寸。这是实现精准截图的关键一环。3.3 权限配置至关重要的一步macOS 出于安全考虑对控制其他应用和截取屏幕的行为有严格的权限管理。我们必须手动开启两项权限。在终端中分别执行以下两条命令它们会直接打开系统设置的相应面板open \x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture\ open \x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility\第一项屏幕录制权限这个权限允许peekaboo截取屏幕内容。在打开的“屏幕录制”权限列表中找到并勾选“终端”Terminal或你使用的其他终端应用如 iTerm2。如果你通过 IDE 的内置终端运行脚本也可能需要勾选该 IDE如 Visual Studio Code。关键点勾选后必须完全退出终端应用Quit Terminal然后重新打开。这个权限需要重启应用才能生效。第二项辅助功能权限这个权限允许 AppleScript/JXA 控制其他应用程序如模拟点击微信按钮。在“辅助功能”权限列表中同样找到并勾选“终端”。同样勾选后需要重启终端应用。实操心得权限问题是新手失败的最高发区。经常有朋友配置后脚本仍报错十有八九是忘了重启终端。一个验证权限是否生效的简单方法是在终端里尝试执行一个简单的 AppleScript 命令例如osascript -e tell application \System Events\ to keystroke \h\ using command down这会隐藏当前应用。如果弹窗提示需要权限则说明辅助功能权限未生效如果没有提示且当前应用被隐藏了则说明权限正常。3.4 安装 wechat-macos-proxy 技能你有两种安装方式推荐第一种。方式一通过 ClawHub 安装推荐如果你已经安装了clawOpenClaw 的命令行工具只需一行命令clawhub install wechat-macos-proxy这种方式最省心它会自动处理依赖和安装路径。方式二手动从 GitHub 安装# 1. 克隆仓库到本地 git clone https://github.com/chairmanmiao/wechat-macos-proxy.git # 2. 移动到 OpenClaw 的技能目录 # 首先确保 ~/.openclaw/skills/ 目录存在如果不存在可以手动创建。 mkdir -p ~/.openclaw/skills/ # 然后移动克隆下来的仓库 mv wechat-macos-proxy ~/.openclaw/skills/无论哪种方式安装完成后核心的可执行脚本路径都在~/.openclaw/skills/wechat-macos-proxy/scripts/wechat_proxy.sh。为了方便使用我强烈建议你为其创建一个软链接到/usr/local/bin或添加到你的 Shell 配置文件别名中# 创建软链接 ln -s ~/.openclaw/skills/wechat-macos-proxy/scripts/wechat_proxy.sh /usr/local/bin/wechat-proxy # 或者在 ~/.zshrc 或 ~/.bash_profile 中添加别名 echo \alias wechat-proxy~/.openclaw/skills/wechat-macos-proxy/scripts/wechat_proxy.sh\ ~/.zshrc source ~/.zshrc这样你就可以在终端任何位置直接使用wechat-proxy命令了。4. 核心功能实操与脚本解析4.1 连接测试验证环境是否就绪安装配置完成后第一步不是急着发消息而是进行连接测试。这能帮你快速确认所有环节是否通畅。wechat-proxy test # 或者使用完整路径 ~/.openclaw/skills/wechat-macos-proxy/scripts/wechat_proxy.sh test这个test命令会执行一系列检查检查微信应用是否已安装。尝试启动或激活微信窗口。使用peekaboo尝试定位微信主窗口并截图。返回测试结果。如果看到Test passed!或类似的成功提示恭喜你最艰难的环境搭建已经完成。如果失败请根据错误信息回溯检查常见问题包括微信未登录、权限未开启、终端未重启、peekaboo安装失败等。4.2 发送单条消息深入脚本内部让我们以最常用的send功能为例拆解一下脚本到底做了什么。命令格式如下wechat-proxy send \文件传输助手\ \这是一条测试消息来自自动化脚本。\当你执行这条命令时wechat_proxy.sh脚本内部大致经历了以下阶段阶段一参数处理与预备脚本首先解析你传入的两个参数联系人名称和消息内容。联系人名称支持模糊匹配比如“文件传输助手”、“传输助手”甚至“文件”都可能匹配成功。脚本会确保微信应用处于运行状态如果未运行则启动它。阶段二定位联系人这是最关键也最容易出错的一步。脚本通过 JXA 执行如下操作// 伪代码示意 tell application \System Events\ tell process \WeChat\ // 1. 激活微信窗口 set frontmost to true // 2. 模拟按下 CommandF聚焦到搜索框 keystroke \f\ using command down delay 0.5 // 等待搜索框弹出 // 3. 清空搜索框并输入联系人名称 keystroke \a\ using command down // CmdA 全选 keystroke delete // 删除原有内容 keystroke \文件传输助手\ // 输入目标联系人 delay 1 // 等待搜索结果出现 // 4. 按下回车键进入聊天窗口 key code 36 // 回车键 delay 1.5 // 等待聊天窗口完全加载 end tell end tell注意事项这里的delay延迟参数非常经验化。它取决于你的电脑性能、网络状态搜索是否需联网以及微信的响应速度。如果脚本经常在搜索后点错了联系人或者没等到窗口打开就执行下一步你可能需要适当调整这些delay的时长。我的经验是在主力机上可以将delay 1适当缩短到0.8或0.5而在负载较重的机器上可能需要增加到2。阶段三发送消息进入聊天窗口后脚本需要将焦点切换到输入框并输入内容// 伪代码示意 tell application \System Events\ tell process \WeChat\ // 将焦点切换到消息输入框通常通过点击实现 click at {特定的屏幕坐标} // 坐标通过 peekaboo 事先计算获得 delay 0.3 // 输入消息内容 keystroke \这是一条测试消息来自自动化脚本。\ delay 0.5 // 模拟按下 CommandEnter 发送 keystroke return using command down end tell end tell这里有一个技术细节如何获取输入框的坐标原始脚本可能采用固定坐标偏移但更健壮的做法是结合peekaboo。脚本可以先截取整个聊天窗口的图然后利用图像识别或基于窗口布局的启发式算法例如输入框通常位于窗口底部中央区域来动态计算点击位置。这在一定程度上能应对微信窗口大小变化或不同版本带来的布局差异。阶段四验证与清理消息发送后脚本可能会短暂等待并尝试截取屏幕验证消息是否出现在对话气泡中。最后脚本可能会将微信窗口最小化或保持原状这取决于具体实现。4.3 批量发送消息CSV 文件的应用对于运营、社群管理或需要定期通知的场景批量发送是刚需。wechat-proxy支持通过 CSV 文件批量操作。wechat-proxy batch-send /path/to/your/contacts.csvCSV 文件格式要求CSV 文件内容非常简单每行一个联系人格式为联系人,消息。注意是英文逗号。文件传输助手,这是第一条批量测试消息。 张三,你好张三这是自动发送的通知。 李四,李四您好会议提醒。重要提示CSV 文件应保存为UTF-8 无 BOM编码格式否则脚本可能无法正确解析中文联系人名。你可以在文本编辑器如 VS Code、Sublime Text中查看和修改编码格式。脚本执行逻辑读取 CSV 文件逐行解析。对于每一行的“联系人”和“消息”调用一次单条发送的流程。在每条消息发送之间通常会有一个间隔例如 2-3 秒以避免操作过快被微信误判为异常行为同时也让电脑有喘息之机。记录成功和失败的记录。风险控制建议切勿用于群发营销或骚扰信息这不仅违反微信规则也可能导致你的账号被限制。先小范围测试先用包含2-3个联系人的 CSV 文件进行测试确保整个流程无误。控制发送频率可以在脚本的循环中增加sleep时间模拟人工操作间隔。我个人的经验是每分钟发送不超过 5-10 条消息相对安全。准备备用方案批量发送中途可能因网络、弹窗等原因失败。一个健壮的脚本应该具备重试机制和详细的日志记录方便你排查是哪一条失败了。4.4 导出聊天记录本地化存档这是一个非常实用的功能可以将指定联系人的最近若干条聊天记录导出为 Markdown 文件并附带截图。wechat-proxy export \张三\ 50这条命令会尝试导出与“张三”的最近50条聊天记录。实现原理拆解定位与打开聊天窗口与发送消息类似首先导航到目标联系人的聊天界面。滚动与截图脚本需要模拟鼠标滚动或按键如Page Up将历史消息加载到当前视图中。每加载一屏就用peekaboo截取一次聊天区域的图片。OCR 识别可选原始项目可能不包含 OCR 功能。更高级的实现会结合 OCR 工具如 macOS 自带的vision框架命令或开源的Tesseract对截图进行文字识别将图片中的消息文本提取出来。结构化整理将识别出的文本、时间戳可能需要从截图或界面元素中获取以及截图文件本身进行关联整理成结构化的数据。生成 Markdown将数据写入一个.md文件。每条消息可能以“时间 发送人 内容 [截图链接]”的格式呈现。保存媒体文件将所有截图保存到与 Markdown 文件同级的目录中。注意事项与局限性能与耗时导出大量记录非常耗时因为涉及频繁的截图和可能的 OCR 识别。准确性OCR 识别不可能达到 100% 准确尤其是对特殊字体、表情包、复杂排版或图片质量较差时。隐私导出的数据包含所有聊天截图请妥善保管避免隐私泄露。滚动限制微信的聊天窗口可能只缓存有限的历史消息无法通过简单滚动导出非常久远的历史记录。4.5 监听模式与消息检查项目还提到了“监听模式”和“检查新消息”功能这些属于更高级的自动化场景。检查新消息其原理是定期例如每10秒使用peekaboo扫描微信的 Dock 图标或应用窗口标题栏查找是否有未读消息角标那个红色的小数字。这可以通过分析应用窗口的辅助功能属性或直接对 Dock 区域进行图像识别来实现。监听模式实验性这旨在实现一个“机器人”般的自动回复。其流程可能是一个无限循环检查是否有新消息通过角标或特定联系人的未读状态。如果有则打开该联系人的聊天窗口截图获取最新消息内容OCR。根据预设的规则或调用外部 AI 接口如 OpenAI API生成回复内容。执行发送消息流程。等待一段时间回到步骤1。警告监听模式对稳定性和准确性要求极高且长时间高频截图和模拟操作可能对系统性能有影响也增加了被微信注意到的风险。目前这个功能标记为“实验性”建议仅在受控环境下谨慎测试。5. 常见问题排查与实战技巧5.1 问题排查清单在实际使用中你可能会遇到各种问题。下面是一个快速排查清单问题现象可能原因解决方案执行脚本无反应或立即报错1. 脚本路径错误2. 依赖未安装 (peekaboo,jq)1. 使用which wechat-proxy检查命令是否在 PATH 中。2. 运行brew list | grep -E \(peekaboo|jq)\检查依赖。报错提示“无法找到微信窗口”或截图失败1. 微信未启动或未登录2. 屏幕录制权限未开启或未生效3. 微信窗口被最小化或隐藏1. 手动启动并登录微信。2.重点检查系统偏好设置 - 安全性与隐私 - 屏幕录制确保终端被勾选并彻底重启终端。3. 确保微信窗口在屏幕上可见未被其他窗口完全遮挡。能启动微信但搜索不到联系人或点击位置错误1.delay延迟时间不足2. 微信界面版本更新导致元素位置变化3. 屏幕分辨率或缩放设置影响坐标计算1. 尝试在脚本中增加关键步骤后的delay时间需修改脚本源码。2. 可能是项目需要更新以适应新版微信。检查 GitHub Issues。3. 尝试将显示器缩放调整为“默认”分辨率再试。消息发送失败输入内容但未发送1. 输入框未正确聚焦2. 发送快捷键不匹配1. 脚本中点击输入框的坐标可能不准。需要调试坐标。2. 确认发送快捷键是CommandEnter。某些系统或输入法下可能需要调整。批量发送时中途卡住或报错1. 某条消息发送失败导致流程中断2. CSV 文件格式或编码错误3. 操作频率过快1. 检查脚本是否有错误处理机制。手动运行单条发送定位失败的具体行。2. 确保 CSV 为 UTF-8 无 BOM且联系人名准确。3. 在批量发送的循环中增加sleep间隔。5.2 实战技巧与进阶优化1. 调整延迟参数脚本中的delay是硬编码的。如果你的电脑很快可以适当调小以提升速度如果慢或不稳定则需调大。建议直接修改wechat_proxy.sh脚本或其调用的 JXA 脚本文件。找到包含delay的语句例如delay 1将其修改为delay 1.5或delay 0.7然后保存测试。2. 处理弹窗干扰微信偶尔会有“更新提示”、“安全提醒”等弹窗。这些弹窗会遮挡界面导致脚本点击错位。一个简单的防御性编程思路是在关键操作如点击发送前先用peekaboo截取当前活动窗口的特定区域比如发送按钮所在区域进行简单的颜色或像素匹配确认目标按钮“可见且可点击”后再执行操作。如果检测到弹窗可以尝试模拟按下Esc或回车键来关闭它。3. 日志记录与调试对于自动化脚本详尽的日志是救命稻草。你可以修改脚本在每一步操作前后都输出日志到文件记录“准备搜索联系人张三”、“已输入搜索关键词”、“已进入聊天窗口”等信息。当脚本失败时查看日志就能快速定位到在哪一步出了问题。结合peekaboo的截图功能你甚至可以在每个步骤后自动保存一张截图进行可视化调试。4. 集成到自动化工作流wechat-proxy的本质是一个命令行工具这赋予了它极大的灵活性。你可以将它嵌入到任何 Shell 脚本、Python 脚本或自动化工具如cron定时任务、LaunchAgents守护进程、Alfred、Keyboard Maestro等中。定时任务使用crontab设置每天上午 9 点给“文件传输助手”发送一条天气简报。# 编辑 crontab: crontab -e 0 9 * * * /usr/local/bin/wechat-proxy send \文件传输助手\ \$(curl -s http://wttr.in/Beijing?format3)\响应式自动化写一个 Python 脚本监控某个文件夹当有新文件放入时自动将其路径通过微信发送给你。与 AI 结合如前所述作为 OpenClaw 的一个技能你可以让 AI 智能体在分析邮件或网页内容后自主决定是否需要通过微信向你发送摘要。5. 关于稳定性的心理预期必须清醒认识到基于 GUI 的自动化天生比基于 API 的自动化更“脆弱”。因为它依赖于一个相对稳定的视觉界面。微信 for Mac 的任何一次界面改版都可能“破坏”现有的脚本。因此不要期望它能像工业级软件一样 100% 稳定运行数月。它的最佳定位是在受控环境下处理明确、重复的个人自动化任务。当它失效时你需要有能力根据错误日志进行调试或等待项目作者更新适配新版本。6. 安全、合规与最佳实践最后我们必须严肃讨论使用这类工具的安全与合规边界。这不仅是技术问题更是责任问题。1. 严格遵守平台规则微信《软件许可及服务协议》中明确禁止“未经腾讯许可使用插件、外挂或非经授权的第三方工具/服务接入本软件和相关系统”。GUI 自动化工具虽然不直接“接入系统”但大规模、高频次的自动化操作仍然可能被系统检测为异常行为。因此绝对不要将其用于群发广告、营销信息。刷屏、骚扰其他用户。模拟点击参与抢红包、刷投票等。任何可能对其他用户造成困扰或违反法律法规的行为。2. 最小化与可审计原则最小化操作频率在满足需求的前提下让脚本运行得“慢”一些加入合理的随机延迟模拟人类操作节奏。最小化操作范围仅对你自己的账号或明确获得授权的操作对象使用。操作可审计保留详细的发送日志记录下每条消息的发送时间、目标和内容摘要。万一出现问题你至少能清楚地知道脚本做了什么。3. 隐私保护脚本在运行时可能会在内存或临时文件中接触到你的消息内容尤其是导出功能。请确保不要在公共或不安全的计算机上使用。定期清理脚本可能生成的临时截图或日志文件。不要将包含敏感信息的自动化脚本上传到公开的代码仓库。4. 技术上的风险隔离如果条件允许可以考虑在单独的 macOS 用户账户甚至虚拟机中运行这类自动化脚本。这个账户只用于自动化任务不包含你的主要社交关系和敏感数据。这样即使出现意外也能将风险隔离在最小范围。归根结底wechat-macos-proxy是一个展示了 macOS 自动化强大可能性的工具。它巧妙地在“功能需求”和“安全限制”之间找到了一个平衡点。作为使用者我们在享受技术带来的便利时更应当时刻保持克制与敬畏将它用在提升个人效率、解决重复劳动的正道上而不是去试探或破坏平台的规则和生态。