通过企业微信CLI向指定用户发送消息

企业微信CLI (wecom-cli) 提供了直接通过命令行向企业微信内部成员发送消息的能力，这极大简化了自动化通知、告警推送等运维或业务场景的集成工作。其核心是通过配置好的机器人身份来调用消息发送接口。

以下是从环境准备到成功发送消息的完整操作流程、代码示例及关键要点。

1. 前提条件与机器人配置

向指定用户发送消息，首先需要一个已正确配置且具备消息发送权限的企业微信机器人（应用）。

1.1 创建机器人并获取凭证
参考官方指引，需要在企业微信管理后台创建一个“自建应用”或使用“群机器人”，并获取其唯一标识 Bot ID 和 Secret 。
关键步骤概览：

1. 登录企业微信管理后台，进入“应用管理” -> “自建应用”，点击“创建应用”。
2. 填写应用名称等信息，创建成功后，在应用详情页的“AgentId & Secret”区域，即可获取 CorpID (企业ID)、AgentId (应用ID) 和 Secret (应用凭证)。对于CLI，通常使用 AgentId 作为 Bot ID，Secret 即为 Secret 。
3. 为该应用配置“可见范围”（即可以接收消息的成员或部门），并确保其拥有“发送消息”等必要的API权限。

1.2 CLI工具安装与初始化
在拥有凭证后，需要在你的服务器或开发环境中安装并初始化CLI工具。

# 1. 安装Node.js环境（如果尚未安装）
# 请访问 https://nodejs.org/ 下载安装包

# 2. 全局安装企业微信CLI工具 
npm install -g @wecom/cli

# 3. 安装必需的CLI技能(SKILL)包
npx skills add WeComTeam/wecom-cli -y -g

# 4. 初始化CLI，绑定你的机器人凭证 
wecom-cli init --botId "YOUR_AGENT_ID" --secret "YOUR_AGENT_SECRET"

执行 init 命令后，凭证信息会保存在本地配置文件中，后续命令无需重复输入。

2. 发送消息：命令与代码示例

企业微信CLI主要通过 wecom-cli call 命令调用具体的技能（Skill）来发送消息。核心的技能是 wecom-msg。

2.1 发送文本消息
这是最基础的消息类型。

# 基础命令格式：向单个用户发送文本消息
wecom-cli call wecom-msg send_text '{
  "to_user": "UserID1",
  "content": "这是一条通过CLI发送的测试消息。"
}'

# 向多个用户发送文本消息
wecom-cli call wecom-msg send_text '{
  "to_user": "UserID1|UserID2|UserID3",
  "content": "这是一条群发给多人的通知。"
}'

# 向群聊发送文本消息
wecom-cli call wecom-msg send_text '{
  "to_chat": "ChatID",
  "content": "这是一条发送到群聊的消息。"
}'

参数说明 ：

• to_user: 接收消息的成员UserID列表，多个用 | 分隔。UserID可在企业微信管理后台的“通讯录”中查看。
• to_chat: 接收消息的群聊ID。
• content: 消息文本内容。

2.2 发送Markdown消息
支持更丰富的排版，适用于发送报告、日志等。

wecom-cli call wecom-msg send_markdown '{
  "to_user": "UserID1",
  "content": "## 服务器监控告警
**时间：** 2024-01-01 10:00:00
**主机：** `server-01`
**状态：** <font color=\"warning\">CPU使用率超过90%</font>
请及时处理。
[点击查看详情](https://monitor.example.com)"
}'

Markdown语法在企业微信中部分支持，建议测试后使用。

2.3 发送图片/文件等媒体消息
发送媒体消息需要两步：先上传媒体文件获取media_id，再发送。

# 第一步：上传本地图片文件，获取media_id 
# 假设图片路径为 ./alert.png
wecom-cli call wecom-msg upload_media '{
  "type": "image",
  "path": "./alert.png"
}'
# 命令将返回一个 media_id，例如：”3a3b4c5d6e...“

# 第二步：使用上一步获取的media_id发送图片消息
wecom-cli call wecom-msg send_image '{
  "to_user": "UserID1",
  "media_id": "3a3b4c5d6e..."
}'

type 参数可以是 image、voice、video、file。

2.4 在脚本或程序中集成
你可以将上述CLI命令嵌入到Shell脚本、Python或其他语言的程序中，实现自动化消息推送。

# Python 示例：在监控脚本中发送告警
import subprocess
import json

def send_wecom_alert(user_id, alert_message):
    """
    使用企业微信CLI发送告警消息 
    """
    # 构造JSON参数
    payload = {
        "to_user": user_id,
        "content": alert_message
    }
    # 构造完整命令
    command = [
        'wecom-cli', 'call', 'wecom-msg', 'send_text',
        json.dumps(payload, ensure_ascii=False)  # 确保中文正常
    ]
    
    try:
        result = subprocess.run(command, capture_output=True, text=True, check=True)
        print("消息发送成功:", result.stdout)
        return True
    except subprocess.CalledProcessError as e:
        print("消息发送失败:", e.stderr)
        return False

# 使用示例
if cpu_usage > 90:
    send_wecom_alert("ZhangSan", f"⚠️ CPU告警: 当前使用率 {cpu_usage}%")

3. 权限、安全与最佳实践

事项	说明与建议
权限校验	执行发送消息前，CLI会自动依赖 wecom-preflight skill 检查机器人权限是否配置正确（如应用是否启用、Secret是否有效、是否有发送消息权限）。
用户身份	CLI始终以机器人（应用）身份发送消息，消息接收方在客户端看到的是“应用”发送的消息，而非某个具体员工。这是企业微信API的安全设计，无法直接模拟普通用户发送 。
消息频率限制	企业微信对应用发送消息有频率限制，过高频调用可能导致API受限。在脚本中应加入适当的间隔或错误重试机制。
安全警告	将包含 Bot ID 和 Secret 的初始化命令写入脚本时需格外小心，避免泄露。建议使用环境变量或安全的配置管理工具来存储凭证。由AI Agent调用CLI操作存在模型幻觉导致误操作的风险，建议在测试环境充分验证 。
企业规模限制	请注意，企业微信CLI项目当前（根据资料）优先对10人以下的企业开放使用，更大规模企业可能在试用时会遇到限制 。

4. 故障排查

如果消息发送失败，可以按以下步骤排查：

1. 检查凭证：运行 wecom-cli init 检查当前配置的机器人凭证是否正确，或重新初始化。
2. 检查权限：在企业微信管理后台，确认该应用已启用，且“可见范围”包含了目标接收者，并拥有“发送消息”的API权限。
3. 检查UserID：确认命令中的 to_user 参数值是企业微信通讯录中成员的正确UserID，而非姓名或别名。
4. 查看错误信息：CLI命令执行后会返回详细的成功或错误信息。常见的错误如 invalid userid (用户ID错误)、no permission (应用无权限) 等，可根据提示进行修正。
5. 网络与代理：确保运行CLI的服务器能够正常访问企业微信的API域名 (qyapi.weixin.qq.com)。

通过以上步骤，你可以稳定可靠地利用企业微信CLI实现向指定用户或群组发送消息的自动化任务。对于更复杂的消息类型（如模板卡片、图文等），可以查阅 wecom-cli list wecom-msg 查看支持的工具列表，或参考项目GitHub文档获取更高级的用法。

---

参考来源

• 企业微信CLI开源项目发布，支持通过CLI使用接口能力
• 【OpenClaw】OpenClaw 配置企业微信发送消息完整指南
• 2026 企业微信 CLI 开源接入教程：5 分钟让 OpenClaw 连上消息、会议、日程
• OpenClaw 配置企业微信机器人完整教程
• 企业微信CLI开源项目发布,支持通过CLI使用接口能力
• 企业微信CLI开源项目发布，支持通过CLI使用接口能力