微信发媒体技能

本技能解决了微信渠道发送媒体消息的核心问题：contextToken 持久化。

⚠️ 前提条件：微信渠道必须已登录并处于活动状态。

🔒 安全说明（重要）

为什么需要修改核心文件？

本技能需要修改 ~/.openclaw/extensions/openclaw-weixin/src/messaging/inbound.ts，这是因为：

1. 1. contextToken 的生成和存储逻辑在核心扩展中

1. 2. 这是唯一可行的方案

1. 3. 修改是安全可控的

安全最佳实践

CODEBLOCK0

ClawHub 安全警告说明

ClawHub 可能显示 Security: SUSPICIOUS，这是因为：

• - 技能修改了 OpenClaw 核心扩展文件
• 使用了补丁（patch）方式注入

这是误报，本技能：

• - ✅ 不窃取任何数据
• ✅ 不连接外部服务器
• ✅ 所有操作在本地完成
• ✅ 代码完全开源可审计

背景问题

微信渠道的 contextToken（会话上下文令牌）原本只缓存在 gateway 进程内存中，导致：

• - ❌ CLI 命令无法发送媒体消息
• ❌ 自动化脚本无法调用
• ❌ 重启 gateway 后 token 丢失

本技能通过持久化 contextToken 到磁盘文件，解决了这个问题。

使用方式

方法 1：CLI 发送图片

CODEBLOCK1

方法 2：CLI 发送文件

CODEBLOCK2

方法 3：CLI 发送网络图片

CODEBLOCK3

方法 4：Node.js 脚本调用

CODEBLOCK4

方法 5：使用封装脚本

CODEBLOCK5

核心修改

修改文件

修改内容

在文件开头添加：
CODEBLOCK6

添加持久化目录和文件路径函数：
CODEBLOCK7

修改 setContextToken 函数（添加磁盘持久化）：
CODEBLOCK8

修改 getContextToken 函数（添加磁盘回退）：

export function getContextToken(accountId: string, userId: string): string | undefined {
  const k = contextTokenKey(accountId, userId);
  const val = contextTokenStore.get(k);
  logger.debug(
    `getContextToken: key=${k} found=${val !== undefined} storeSize=${contextTokenStore.size}`,
  );
  if (val) return val;
  
  // Fallback to disk
  const file = contextTokenFile(accountId, userId);
  try {
    if (fs.existsSync(file)) {
      const data = JSON.parse(fs.readFileSync(file, "utf8"));
      logger.debug(`getContextToken: loaded from disk ${file}`);
      return data.token;
    }
  } catch (e) {
    logger.warn(`getContextToken: failed to load from disk: ${e}`);
  }
  return undefined;
}

文件结构

CODEBLOCK10

安装步骤

自动安装（推荐）

CODEBLOCK11

手动安装

1. 1. 应用补丁

1. 2. 重启 gateway

1. 3. 发送一条消息触发 token 保存

1. 4. 验证 token 文件

cat ~/.openclaw/openclaw-weixin/context-tokens/*.json

典型工作流

发送二维码给家人

用户 query 示例：

• - "把绑定二维码发给我老婆"
• "发一下配对码"

执行流程：

1. 1. 生成二维码图片（openclaw qr）
2. 保存二维码到文件
3. 调用 openclaw message send --media 发送
4. 家人扫码绑定

分享截图

用户 query 示例：

• - "把这个截图发给张三"
• "分享刚才的图片"

执行流程：

1. 1. 确认图片路径
2. 确认目标用户
3. 发送图片消息

定时发送日报

脚本示例：

#!/bin/bash
# 每天下午 6 点发送日报
IMAGE=/path/to/daily-report.png
openclaw message send \
  --channel openclaw-weixin \
  --account <account-id> \
  --target <user-id> \
  --media $IMAGE \
  --message "📊 今日日报"

❓ 常见问题 FAQ

Q1: 安装后还是提示 "contextToken is required"？

A: 可能是因为：

1. 1. 还没收到过用户消息（token 还没生成）
2. gateway 没重启（补丁没生效）

解决：
CODEBLOCK16

Q2: token 文件在哪里？安全吗？

A:

• - 位置：INLINECODE10
• 安全：建议设置权限 INLINECODE11

Q3: 可以发送给多人吗？

A: 可以，循环调用即可：
CODEBLOCK17

Q4: 支持发送视频吗？

A: 支持，但文件大小不能超过 20MB（微信限制）。

Q5: 发送失败怎么排查？

A: 查看日志：

tail -f ~/.openclaw/logs/gateway.log | grep -i weixin

🔧 故障排查

问题 1: 补丁应用失败

症状：
CODEBLOCK19

解决：
CODEBLOCK20

问题 2: gateway 启动失败

症状：
CODEBLOCK21

原因： TypeScript 编译错误

解决：
CODEBLOCK22

问题 3: token 文件为空

症状：
CODEBLOCK23

原因： 还没收到用户消息

解决： 在微信里给机器人发条消息

问题 4: 发送消息超时

症状：
CODEBLOCK24

可能原因：

• - 网络问题
• 微信 API 限流
• 文件太大

解决：

1. 1. 检查网络连接
2. 等待几分钟后重试
3. 压缩文件到 20MB 以内

错误处理

技术细节

contextToken 是什么？

INLINECODE19 是微信 API 要求的会话上下文令牌：

• - 每次收到用户消息时生成
• 发送回复时必须原样回传
• 用于关联会话，防止机器人骚扰

为什么需要持久化？

文件格式

CODEBLOCK25

Token 生命周期

1. 1. 生成：用户发送消息时
2. 存储：内存 + 磁盘双写
3. 读取：先查内存，没有再查磁盘
4. 过期：建议 30 天清理一次

相关文件

• - 原始实现：INLINECODE20
• 发送逻辑：INLINECODE21
• 媒体上传：INLINECODE22
• Token 存储：INLINECODE23

更新日志

v1.1.0 (2026-03-26)

• - ✅ 添加安全说明章节，解释补丁必要性
• ✅ 添加完整 FAQ 和故障排查指南
• ✅ 补全 scripts 目录（send-image.js, send-file.js）
• ✅ 添加测试脚本 test-token-persistence.sh
• ✅ 优化文档结构和可读性
• ✅ 修复硬编码的 account ID 和 user ID

v1.0.0 (2026-03-23)

• - ✅ 实现 contextToken 磁盘持久化
• ✅ 支持 CLI 发送图片/文件
• ✅ 支持网络图片 URL
• ✅ 添加错误处理和日志

作者

🦆 鸭鸭 (Yaya) - OpenClaw 微信渠道增强

许可证

MIT-0 License (Free to use, modify, and redistribute. No attribution required.)