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

企业微信 API Skill

触发条件

当用户说以下任意内容时启动：
- /wecom-api
- "发企微消息给 XX"
- "在企微上通知 XX"
- "查一下 XX 的企微"
- "给 XX 发个通知"
- "企微推送"
- "wecom send"

工具使用规则

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

前置依赖：
- 已安装 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：理解用户意图

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

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点开会，请准时参加。」

错误处理

安全注意事项

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，否则需要通过其他方式搜索