1. 为什么我们需要一个命令行版的企业微信如果你和我一样日常工作中重度依赖企业微信进行团队沟通、文件传输和机器人通知那你一定经历过这样的场景正在终端里全神贯注地调试代码突然需要给同事发个文件或者查看一下某个群里的消息。于是你不得不停下敲击键盘的手用鼠标或快捷键切换到企业微信的窗口完成操作再切换回终端。这种频繁的上下文切换不仅打断了流畅的编程心流也让工作效率大打折扣。更别提在一些服务器环境或者没有图形界面的开发机里你根本无法安装和使用桌面版的企业微信。这正是wecom-cli这类命令行工具诞生的核心驱动力。它不是一个简单的玩具而是一个旨在将企业微信的核心功能无缝集成到开发者工作流中的生产力工具。想象一下你可以在不离开终端的情况下通过一行命令发送消息、上传文件、甚至管理机器人这无疑是对传统工作方式的一次“降维打击”。结合当前热门的 AI Agent 开发趋势命令行工具更是成为了连接自动化脚本与即时通讯平台的关键桥梁。你可以轻松地将wecom-cli嵌入到你的 CI/CD 流水线、监控告警脚本或者 AI Agent 的决策执行层中让机器与人的沟通变得像调用一个本地 API 一样简单直接。2. 环境准备与核心概念扫盲在开始动手之前我们需要先理清几个关键概念并准备好运行环境。这能帮你避开后续 90% 的配置坑。2.1 理解企业微信的“凭证”CorpID, Secret 与 AgentIdwecom-cli本质上是通过企业微信官方提供的 API 来工作的。要调用这些 API你需要三把“钥匙”CorpID企业ID这是你所在企业的唯一标识。它通常由企业微信管理员在管理后台的“我的企业” - “企业信息”页面找到。格式类似于wwxxxxxxxxxxxxxxxx。AgentId应用ID/AgentId企业微信中的“应用”是功能的载体。你需要创建一个“自建应用”来获得 API 调用的权限。在管理后台的“应用管理” - “自建”中创建应用后就能看到其唯一的 AgentId。这个 ID 决定了你的消息从哪个应用发出。Secret应用密钥这是最关键也最敏感的信息相当于该应用的密码。同样在应用详情页的“权限管理”部分可以获取。务必妥善保管一旦泄露应立即重置。wecom-cli会使用 Secret 向企业微信服务器换取一个有时效性的访问令牌Access Token之后的所有操作都基于这个令牌进行。简单来说流程是用 CorpID 和 Secret 换 Token再用 Token 和 AgentId 来发送消息。很多人在第一步就卡住了因为没分清 CorpID 和 AgentId或者找错了 Secret 的位置。2.2 安装 wecom-cli多种途径总有一款适合你wecom-cli通常是一个用 Go 或 Python 等语言编写的单文件二进制工具安装非常灵活。对于 macOS/Linux 用户推荐使用 Homebrew 或直接下载# 方法一使用 Homebrew如果作者提供了 tap brew install some-tap/wecom-cli # 方法二从 GitHub Releases 直接下载二进制文件最常见 # 假设最新版本是 v0.3.0根据你的系统架构选择 wget https://github.com/author/wecom-cli/releases/download/v0.3.0/wecom-cli_darwin_amd64 -O /usr/local/bin/wecom-cli chmod x /usr/local/bin/wecom-cli # 方法三通过 Go 安装如果项目是 Go 写的 go install github.com/author/wecom-clilatest对于 Windows 用户你可以直接从 Releases 页面下载wecom-cli_windows_amd64.exe文件将其重命名为wecom-cli.exe然后放入一个已添加到系统 PATH 环境变量的目录如C:\Windows\System32\或你自己创建的C:\Tools\并在 PATH 中添加该路径。这样你就可以在任意位置的命令行或 PowerShell 中直接使用wecom-cli命令了。安装完成后在终端输入wecom-cli --version或wecom-cli -h如果能看到版本号或帮助信息说明安装成功。注意网络上的相关工具名称可能略有不同如wechat-cli、wecom等请以具体项目的 README 为准。本文以wecom-cli作为通用指代。2.3 初始化配置安全地存储你的密钥直接在命令中粘贴 CorpID 和 Secret 既麻烦又不安全。wecom-cli通常支持通过配置文件或环境变量来管理这些凭证。配置文件方式推荐便于管理多个企业或应用大多数 CLI 工具会默认在用户主目录~/.wecom-cli.yaml或~/.config/wecom-cli/config寻找配置文件。你需要创建一个这样的文件# ~/.wecom-cli.yaml corp_id: wwxxxxxxxxxxxxxxxx agent_id: 1000002 corp_secret: your-very-long-and-secret-string-here然后你可以通过命令wecom-cli config --path ~/.wecom-cli.yaml来指定使用这个配置或者工具会自动加载。环境变量方式适合 CI/CD 等自动化环境export WECOM_CORP_IDwwxxxxxxxxxxxxxxxx export WECOM_AGENT_ID1000002 export WECOM_CORP_SECRETyour-secret在脚本中你可以直接设置这些环境变量然后运行wecom-cli命令工具会自动读取。实操心得我强烈建议使用配置文件并设置严格的文件权限如chmod 600 ~/.wecom-cli.yaml防止其他用户读取。对于团队共享配置可以考虑使用加密的配置管理工具如git-crypt或密钥管理服务。3. 消息发送从基础文本到复杂卡片发送消息是wecom-cli最核心的功能。企业微信 API 支持多种消息类型wecom-cli基本都做了封装。3.1 发送纯文本与 Markdown 消息基础文本消息是最简单的。它支持提及成员但格式有限。# 发送给指定用户多个用户用 | 分隔 wecom-cli message send --user UserID1|UserID2 --msg-type text --content 服务器部署完成请查收。 # 发送给指定部门多个部门用 | 分隔 wecom-cli message send --party PartyID1|PartyID2 --msg-type text --content 部门通知下午两点开会。 # 发送给指定标签组的人员 wecom-cli message send --tag TagID --msg-type text --content 标签组通知...这里的UserID、PartyID、TagID都需要从企业微信管理后台获取。所有人的格式是all具体用户的格式是userid但注意在文本消息中只有被的用户在手机端才会收到特殊提醒。Markdown 消息则是程序员的最爱它支持丰富的排版可读性极强。wecom-cli message send --user UserID --msg-type markdown --content # 监控告警通知 **告警级别** font color\warning\警告/font **告警主机** nginx-prod-01 **告警信息** CPU 使用率持续 5 分钟超过 90% **发生时间** $(date) **快速链接** [查看监控面板](https://grafana.example.com) 请相关同事及时处理。 Markdown 内容需要用引号包裹并且注意转义内部的双引号。企业微信的 Markdown 支持标准语法如标题、加粗、代码块、链接等非常适合发送结构化的告警、报告或日志摘要。3.2 发送图片、文件与图文消息传输二进制文件是刚需。wecom-cli通常需要你先将文件上传到企业微信服务器获取一个media_id然后再发送。但好的工具会将这两步合并。# 发送图片工具自动处理上传 wecom-cli message send --user UserID --msg-type image --file-path /path/to/screenshot.png # 发送文件如日志文件、文档 wecom-cli message send --user UserID --msg-type file --file-path /var/log/app/error.log --filename 今日错误日志.txt--filename参数可以指定接收方看到的名字如果不指定则默认使用原始文件名。图文消息News可以发送一个更丰富的卡片包含标题、描述、图片和链接。wecom-cli message send --user UserID --msg-type news --title 版本发布公告 v2.1.0 --description 本次更新包含性能优化和3个Bug修复。 --url https://your-confluence-page --picurl https://example.com/cover.png这对于发送产品更新、活动通知等场景非常有用。picurl是封面图的网络地址需要是公网可访问的。3.3 消息发送的实战技巧与避坑指南内容长度限制企业微信对单条消息的内容长度有限制如文本消息最长2048字节Markdown更长但也要注意。如果发送的日志或报告过长wecom-cli应该自动截断或分条发送。如果没有这个功能你需要在脚本中自己处理比如按行分割或先压缩成文件再发送。媒体文件大小与类型限制图片不能超过2MB文件不能超过20MB普通应用。发送前最好在脚本里做一下大小检查。另外注意企业微信支持的文件类型白名单。异步发送与速率限制企业微信 API 有调用频率限制大概每分钟数千次但具体看企业规模。在循环中给大量用户发消息时需要在脚本中增加延时如sleep 0.1避免触发限流导致失败。wecom-cli本身是同步调用发送成功会返回0错误码失败则返回非零并打印错误信息。调试与日志首次使用时可以加上--verbose或--dry-run参数如果工具支持让工具打印出将要发送的请求体而不实际发送方便检查格式是否正确。4. 接收与处理消息打造交互式机器人单向发送只是基础真正的自动化在于能够接收并响应消息。这需要用到企业微信的“接收消息”模式通常通过设置一个可公网访问的“回调URL”来实现。wecom-cli可以扮演一个本地服务器接收、解析并触发你自定义的处理逻辑。4.1 配置企业微信应用启用接收消息这一步在管理后台完成进入你的自建应用管理页面。找到“接收消息”设置点击“配置”。你需要提供一个URL如https://your-public-domain.com/wecom/callback、一个Token自定义的字符串用于生成签名和一个EncodingAESKey用于消息加解密点击随机生成即可。点击保存时企业微信会向你的 URL 发送一个验证请求你需要正确处理并返回指定的echostr参数才能验证成功。4.2 使用 wecom-cli 启动回调服务器如果你的wecom-cli支持服务器模式命令可能类似这样wecom-cli server start \ --port 8080 \ --token YourConfiguredToken \ --aes-key YourEncodingAESKey \ --handler-script /path/to/your/handler.py这个命令会在本地 8080 端口启动一个 HTTP 服务器。你需要使用内网穿透工具如 ngrok、frp将http://localhost:8080暴露为一个公网 HTTPS URL企业微信要求回调地址必须是 HTTPS并将这个 URL 填到上一步的配置中。--handler-script参数指向一个你编写的脚本。当服务器收到用户发往该应用的消息时它会将解密后的消息体JSON格式作为标准输入stdin传递给这个脚本并执行它。你的脚本处理完后可以将回复内容打印到标准输出stdoutwecom-cli服务器会将其作为回复发送给用户。4.3 编写你的第一个消息处理脚本下面是一个简单的 Python 处理脚本示例 (/path/to/your/handler.py)#!/usr/bin/env python3 import sys import json # 从标准输入读取企业微信推送的 JSON 数据 raw_input sys.stdin.read() try: data json.loads(raw_input) except json.JSONDecodeError: # 如果不是JSON可能是验证请求直接原样返回wecom-cli通常已处理 sys.stdout.write(raw_input) sys.exit(0) # 提取消息信息 msg_type data.get(MsgType, ) sender data.get(FromUserName, ) # 发送者的UserID content data.get(Content, ).strip() # 文本消息内容 # 定义你的处理逻辑 if msg_type text: if content ping: reply pong elif content.startswith(echo ): reply content[5:] elif content 日志: # 这里可以执行一个命令获取日志 import subprocess log subprocess.check_output([tail, -n, 20, /var/log/syslog]).decode(utf-8) reply f最近20条系统日志\n\n{log}\n else: reply f收到你的消息{content}。你可以尝试发送“ping”、“echo 你好”或“日志”。 # 构建回复消息体必须是企业微信要求的JSON格式 response { ToUserName: sender, FromUserName: data.get(ToUserName, ), CreateTime: int(time.time()), MsgType: text, Content: reply } # 输出到标准输出wecom-cli服务器会发送它 print(json.dumps(response))这个脚本实现了一个简单的交互机器人回复ping为pong回复echo xxx则复读xxx回复日志则返回服务器日志。你可以在此基础上无限扩展连接数据库、调用 API、触发部署脚本等等。避坑指南处理脚本的权限和环境要特别注意。确保脚本有可执行权限 (chmod x handler.py)并且脚本中调用的命令在wecom-cli服务器的运行环境下是可用的。对于生产环境建议使用更健壮的消息队列或 Webhook 框架来处理避免脚本阻塞导致服务器无法响应新消息。5. 管理机器人Webhook与群聊除了通过应用发送消息企业微信还有更轻量级的“群机器人”功能。它通过一个 Webhook URL 工作无需复杂的应用配置和 OAuth非常适合简单的通知场景。5.1 创建与使用群机器人在企业微信群里点击右上角菜单 - “添加群机器人”。设置机器人名字和头像创建成功后你会获得一个以https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key开头的 Webhook URL。这个 URL 包含了密钥等同于密码必须保密。wecom-cli通常也支持通过机器人 Webhook 发送消息wecom-cli webhook send --key your-webhook-key --msg-type markdown --content **构建通知**\n 项目: frontend\n 状态: font color\info\成功/font\n 分支: main\n 耗时: 2分30秒这种方式完全独立于企业微信应用不消耗应用的 API 调用额度且配置极其简单是发送 CI/CD 构建状态、监控告警的首选。5.2 通过命令行管理群聊部分高级功能一些高级的wecom-cli工具可能集成了部分管理 API允许你获取群聊列表wecom-cli chatroom list发送消息到群聊指定群聊的chatid进行发送其命令格式与应用消息发送类似。创建群聊这对于自动化创建项目组、会议群等场景很有用。但请注意群聊管理 API 的权限控制更严格通常需要更高的应用权限如通讯录权限。在使用前务必在管理后台为你的应用开启相应权限。6. 集成到自动化脚本与 AI Agent命令行工具的终极价值在于“可编程性”。我们可以轻松地将wecom-cli嵌入到各种自动化流程中。6.1 在 Shell 脚本中发送通知这是一个最简单的例子在备份脚本完成后发送通知#!/bin/bash # backup.sh BACKUP_FILE/backup/data_$(date %Y%m%d).tar.gz tar -czf $BACKUP_FILE /path/to/data if [ $? -eq 0 ]; then wecom-cli message send --user sysadmin --msg-type text --content 数据库备份成功$BACKUP_FILE大小$(du -h $BACKUP_FILE | cut -f1) else wecom-cli message send --user sysadmin --msg-type text --content font color\warning\数据库备份失败/font 请立即检查服务器状态。 fi6.2 在 CI/CD 流水线中发送构建结果以 GitLab CI 为例在.gitlab-ci.yml中添加一个 stagestages: - build - notify send-wecom-notification: stage: notify script: - | if [ $CI_JOB_STATUS success ]; then MSG✅ 构建成功 - $CI_PROJECT_NAME ($CI_COMMIT_REF_NAME) else MSG❌ 构建失败 - $CI_PROJECT_NAME ($CI_COMMIT_REF_NAME)\n提交: $CI_COMMIT_MESSAGE\n详情: $CI_JOB_URL fi # 假设 wecom-cli 已安装在 runner 环境或使用 docker 镜像 wecom-cli webhook send --key $WECOM_ROBOT_KEY --msg-type markdown --content $MSG only: - main - develop这里我们使用了机器人的 Webhook并将密钥存储在 GitLab 的 CI/CD 变量WECOM_ROBOT_KEY中。6.3 作为 AI Agent 的执行器Action这是当前非常热门的应用场景。AI Agent如基于 LangChain、AutoGPT 等框架构建可以理解自然语言指令并规划任务。wecom-cli可以成为 Agent 的一个“技能”Skill或“工具”Tool负责执行“发送消息”、“查询信息”等动作。假设你有一个 Python 编写的 AI Agent你可以这样集成import subprocess import json class WeComTool: def send_message(self, to_user: str, content: str, msg_type: str text): 使用 wecom-cli 发送消息 cmd [ wecom-cli, message, send, --user, to_user, --msg-type, msg_type, --content, content ] result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode 0: return {status: success, message: 消息发送成功} else: return {status: error, message: f发送失败: {result.stderr}} # 在你的 Agent 逻辑中调用 agent_tools { send_wecom_message: WeComTool().send_message } # 当 LLM 决定需要发送消息时调用这个工具 # 例如LLM 输出: send_wecom_message to_userzhangsan content会议改到3点这样你的 AI Agent 就具备了通过企业微信与真人交互的能力。Harness 这类基础设施层正是用来标准化、安全地管理这些工具调用、处理权限和审计日志的。7. 高级配置、故障排查与安全实践7.1 多应用与多环境配置管理你可能需要同时管理开发、测试、生产等不同环境的企业微信应用或者在同一环境使用多个不同应用。wecom-cli通常支持通过--config参数指定不同的配置文件。你可以创建多个配置文件~/.wecom-cli.dev.yaml(开发环境应用)~/.wecom-cli.prod.yaml(生产环境应用)~/.wecom-cli.robot.yaml(专门用于机器人通知的应用)然后通过别名alias来简化命令# 在 ~/.bashrc 或 ~/.zshrc 中添加 alias wecom-devwecom-cli --config ~/.wecom-cli.dev.yaml alias wecom-prodwecom-cli --config ~/.wecom-cli.prod.yaml # 使用 wecom-prod message send --user ops-team --content 生产服务器重启完成。7.2 常见错误与排查方法invalid credential或access_token is invalid这是最常见的问题。原因包括CorpSecret 错误或已失效去管理后台检查并重置。服务器时间不同步企业微信 API 对时间戳有严格要求确保运行wecom-cli的机器时间准确。Access Token 缓存问题有些 CLI 工具会缓存 token如果 token 在别处被刷新这里就会失效。尝试清除缓存文件通常位于~/.cache/wecom-cli或类似位置或重启工具。userid not found发送消息时指定的 UserID 不存在。检查用户是否已离职或被禁用以及 UserID 是否正确区分大小写。可以通过企业微信管理后台或通讯录 API 核对。ip not in whitelist企业微信应用可以设置“可信 IP”白名单。如果你从公司网络外部如家里、云服务器调用 API需要将出口 IP 地址添加到应用设置的白名单中。callback failed接收消息服务器配置失败。检查回调 URL 是否公网可访问且是 HTTPS。Token 和 EncodingAESKey 是否与后台配置完全一致注意不要有多余空格。你的回调服务器wecom-cli server是否正常运行且防火墙端口已打开。命令执行报错unsafely这个错误提示可能源于你使用的某个特定wecom-cli实现版本它可能包含一个名为unsafely的命令行标记或子命令用于跳过某些安全检查例如 SSL 证书验证。除非你完全清楚风险并在受控环境如测试内网中使用否则应避免使用此类标记。更常见的做法是确保你的系统根证书有效或者使用--insecure如果支持等更通用的参数。排查时始终使用--verbose参数来查看详细的 HTTP 请求和响应这是定位问题的利器。7.3 安全最佳实践最小权限原则为wecom-cli使用的企业微信应用分配最小的必要权限。如果只用来发通知就不要开通通讯录读取权限。秘密信息零落地在 CI/CD 等自动化环境中永远不要将 CorpSecret、Webhook Key 等硬编码在脚本里。使用环境变量或密钥管理服务如 HashiCorp Vault、AWS Secrets Manager。审计日志重要的发送操作尤其是生产环境应在你自己的日志系统中记录谁、在什么时候、发送了什么内容。wecom-cli本身可能不提供此功能你需要在调用它的上层脚本中实现。网络隔离运行wecom-cli server的回调服务器应部署在受保护的网络环境中并配置好防火墙规则只允许企业微信的 IP 段需要查询企业微信官方文档访问回调端口。命令行与企业微信的结合远不止于发送一条消息那么简单。它打通了自动化世界与团队协作平台之间的壁垒。从我自己的使用经验来看初期花一点时间克服配置上的小麻烦后期带来的效率提升和流程自动化收益是巨大的。无论是凌晨三点收到自动化的故障告警还是让 AI Agent 自动将每日报告推送到项目群这种“一切尽在命令行掌控之中”的感觉正是工程师追求的效率与优雅。