shield_lock
JinDaGe
Contact
← Back to skills
extension
Category: OtherAPI key required

wecome-send-message

企业微信消息推送与通讯录查询。通过企微自建应用向指定用户发送消息、查询通讯录。| WeCom API integration for sending messages and searching contacts via enterprise app.

personAuthor: user_6976792ahubcommunity
downloadDownload package

语言: 本 Skill 支持中英文。根据用户第一条消息的语言，全程使用同一语言回复。

企业微信 API Skill

触发条件

当用户说以下任意内容时启动：

  • /wecom-api
  • "发企微消息给 XX"
  • "在企微上通知 XX"
  • "查一下 XX 的企微"
  • "给 XX 发个通知"
  • "企微推送"
  • "wecom send"

工具使用规则

本 Skill 运行在 Claude Code 环境，使用以下工具：

| 任务 | 使用工具 | |------|---------| | 检查配置状态 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py check | | 写入 Skill 私有配置 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py setup --corp-id "xxx" --agent-id "1000002" --secret "xxx" | | 验证 API 连接 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify | | 通过姓名查用户 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-name --name "XX" | | 通过手机号查用户 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-mobile --mobile "138xxxx" | | 通过邮箱查用户 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-email --email "xx@company.com" | | 获取用户详情 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py user-info --userid "XX" | | 发送文本消息 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text --to "userid" --content "内容" | | 发送 Markdown 消息 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-markdown --to "userid" --content "内容" | | 发送卡片消息 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-card --to "userid" --title "标题" --desc "描述" --url "链接" | | 群发/全员发送预览 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text --to "a|b" --content "内容" --preview | | 查看最近发送审计日志 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py history --limit 10 | | 获取部门列表 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py dept-list | | 获取部门成员 | Bash → python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py dept-users --dept-id 1 --recursive |

前置依赖：

  • 已安装 Python 3
  • 已安装 requests：pip install requests

主流程

Step 0：首次使用 — 初始化配置

每次执行任务前，先检查配置状态：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py check

如果返回 "ready": false，进入初始化引导流程：

引导话术

企业微信 API 需要先配置凭证才能使用。你需要准备以下信息：

  1. CorpID（企业 ID）
     → 企业微信管理后台 → 我的企业 → 页面底部

  2. AgentID（应用 ID）
     → 应用管理 → 你的自建应用 → 应用详情页

  3. Secret（应用密钥）
     → 同上，应用详情页

  4. Contact Secret（通讯录密钥，可选）
     → 管理工具 → 通讯录同步 → Secret
     → 如果 IT 没有单独提供，可以先跳过，会用应用 Secret 兜底

还没有自建应用？需要在企微管理后台申请创建，或者联系你们的 IT 管理员走工单流程。
申请时需要提供：应用名称、可见范围、应用图标、用途说明。

已经有了？请把这些值告诉我，我来帮你配置。

配置方式

用户提供凭证后，引导用户通过以下方式之一配置。推荐优先使用 Skill 私有 .env，这样在 OpenClaw workspace 中更可控。

方式 A：Skill 私有 setup（推荐）

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py setup \
  --corp-id "你的企业ID" \
  --agent-id "你的AgentID" \
  --secret "你的应用Secret" \
  --contact-secret "你的通讯录Secret"

这会把配置写到 ${CLAUDE_SKILL_DIR}/.env，并默认把 token 缓存和运行状态放到 skill 私有目录：

  • ${CLAUDE_SKILL_DIR}/.cache/
  • ${CLAUDE_SKILL_DIR}/.state/

之后执行：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify

方式 B：OpenClaw Secrets

如果用户使用 OpenClaw，提示通过 secrets 管理：

请在 OpenClaw 中执行以下命令配置 secrets：

openclaw secrets set WECOM_CORP_ID "你的企业ID"
openclaw secrets set WECOM_AGENT_ID "你的AgentID"
openclaw secrets set WECOM_SECRET "你的应用Secret"
openclaw secrets set WECOM_CONTACT_SECRET "你的通讯录Secret"  # 可选

方式 C：手动设置环境变量

Linux / macOS:

export WECOM_CORP_ID="你的企业ID"
export WECOM_AGENT_ID="你的AgentID"
export WECOM_SECRET="你的应用Secret"
export WECOM_CONTACT_SECRET="你的通讯录Secret"  # 可选

PowerShell:

$env:WECOM_CORP_ID="你的企业ID"
$env:WECOM_AGENT_ID="你的AgentID"
$env:WECOM_SECRET="你的应用Secret"
$env:WECOM_CONTACT_SECRET="你的通讯录Secret"  # 可选

方式 D：手动写入 .env 文件

直接在 ${CLAUDE_SKILL_DIR}/.env 创建文件，例如：

WECOM_CORP_ID=你的企业ID
WECOM_AGENT_ID=你的AgentID
WECOM_SECRET=你的应用Secret
WECOM_CONTACT_SECRET=你的通讯录Secret
WECOM_CACHE_DIR=./.cache

OpenClaw / workspace 场景下，默认只读取 ${CLAUDE_SKILL_DIR}/.env，避免误读当前工作目录下其他项目的 .env。 如果确实需要自定义位置，先设置 WECOM_ENV_FILE，再执行命令，例如：

export WECOM_ENV_FILE="/path/to/wecom.env"
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify

PowerShell:

$env:WECOM_ENV_FILE="C:\\path\\to\\wecom.env"
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify

配置完成后，验证连接：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py verify

如果返回 "success": true，配置完成，进入正常使用流程。

Step 1：理解用户意图

用户的请求通常是以下几类：

| 用户说的话 | 意图 | 需要的操作 | |-----------|------|-----------| | "给张三发消息说明天开会" | 发消息 | 先查 UserID → 再发消息 | | "通知研发部全员版本已发布" | 群发 | 查部门 → 获取成员 → 批量发送 | | "查一下李四的企微信息" | 查通讯录 | 按姓名/手机/邮箱搜索 | | "发个 markdown 格式的周报给老板" | 发 Markdown | 查 UserID → 发 Markdown |

Step 2：查找目标用户

如果用户提供了姓名而非 UserID，需要先查找：

优先级：姓名 → 手机号 → 邮箱 → 部门浏览

# 按姓名搜索（模糊匹配）
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-name --name "张三"

# 按手机号精确查找
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-mobile --mobile "13800138000"

# 按邮箱精确查找
python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py search-email --email "zhangsan@company.com"

如果搜索到多个匹配结果，展示给用户确认：

找到以下匹配用户：
  1. 张三（研发部）- UserID: zhangsan
  2. 张三丰（产品部）- UserID: zhangsanfeng

你要发给哪一位？

如果搜索不到，提示可能原因：

  • 该用户不在应用的可见范围内
  • 姓名输入有误
  • 需要通讯录权限（WECOM_CONTACT_SECRET）

Step 3：发送消息

确认目标用户后，根据消息类型选择发送方式：

文本消息（默认）：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text \
  --to "zhangsan" \
  --content "明天上午10点开会，请准时参加。"

Markdown 消息（适合格式化内容）：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-markdown \
  --to "zhangsan" \
  --content "## 会议通知\n> 时间：明天 10:00\n> 地点：3楼会议室\n\n请准时参加。"

文本卡片消息（带跳转链接）：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-card \
  --to "zhangsan" \
  --title "周报已提交" \
  --desc "点击查看详情" \
  --url "https://example.com/report"

多人发送：UserID 用 | 分隔：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text \
  --to "zhangsan|lisi|wangwu" \
  --content "提醒：今天下班前提交周报" \
  --preview

全员发送：使用 @all：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text \
  --to "@all" \
  --content "系统维护通知：今晚 22:00-23:00 系统升级" \
  --preview

对于多人发送和 @all：

  • 默认只允许先输出预览，避免误发
  • 真正发送时，必须在确认后追加 --yes

示例：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py send-text \
  --to "zhangsan|lisi|wangwu" \
  --content "提醒：今天下班前提交周报" \
  --yes

Step 4：确认发送结果

检查 API 返回值：

  • errcode: 0 → 发送成功，告知用户
  • errcode: 60020 / invaliduser → 用户不在可见范围，建议联系 IT 扩大应用可见范围
  • errcode: 40014 → access_token 过期，自动清理本地缓存并重试一次
  • 其他错误 → 展示错误码和描述，建议用户检查配置

每次真正发送后，都会写入 ${CLAUDE_SKILL_DIR}/.state/message_audit.json 审计日志。 如需查看最近记录：

python3 ${CLAUDE_SKILL_DIR}/tools/wecom_client.py history --limit 10

成功后的回复示例：

已通过企微向 张三 发送消息：「明天上午10点开会，请准时参加。」

错误处理

| 错误码 | 含义 | 处理方式 | |--------|------|---------| | 40001 | Secret 无效 | 提示用户检查 WECOM_SECRET | | 40014 | access_token 过期 | 清除缓存重新获取 | | 41001 | 缺少 access_token | 检查配置是否完整 | | 60011 | 无通讯录权限 | 提示配置 WECOM_CONTACT_SECRET | | 60020 | 接收者不在可见范围 | 提示联系 IT 扩大应用可见范围 | | 81013 | 接收者 UserID 无效 | 重新搜索确认 UserID | | -2 | 网络请求失败 | 检查网络、代理、企业微信 API 可达性 | | -3 | 接口返回非 JSON | 检查网关、代理或接口异常页面 |

安全注意事项

  1. 绝不在代码或日志中明文输出 Secret — 所有凭证通过环境变量传入
  2. access_token 缓存在 Skill 私有目录 — 默认路径 ${CLAUDE_SKILL_DIR}/.cache/，2 小时自动过期
  3. 运行状态独立存放 — 运行状态和发送审计日志默认位于 ${CLAUDE_SKILL_DIR}/.state/
  4. 发送消息前确认 — 对于群发（多人或 @all）场景，默认要求先预览，再显式追加 --yes
  5. 通讯录信息敏感 — 查询结果中的手机号、邮箱等不要在不必要的场景下展示

如需改缓存位置，可显式设置 WECOM_CACHE_DIR：

export WECOM_CACHE_DIR="/path/to/wecom-cache"

PowerShell:

$env:WECOM_CACHE_DIR="C:\\path\\to\\wecom-cache"

如果写相对路径，例如 ./.cache，会按 ${CLAUDE_SKILL_DIR} 解析，而不是按当前 workspace 目录解析。

常见使用场景

场景 1：快速通知某人

用户：「告诉张三明天开会」
→ search-name "张三" → 找到 userid → send-text → 完成

场景 2：部门群发

用户：「通知研发部全员版本已发布」
→ dept-list 找到研发部 ID → dept-users 获取成员 → 拼接 userid → send-text → 完成

场景 3：格式化通知

用户：「发个 markdown 格式的上线通知给运维组」
→ 查找运维组成员 → 构造 markdown 内容 → send-markdown → 完成

场景 4：查人

用户：「帮我查一下工号 20260690 对应的人」
→ 如果知道 userid 直接 user-info，否则需要通过其他方式搜索