wechat

WechatUse — まずホストプラットフォームを選択してください

このスキルはmacOS Apple Silicon と実験的な Windows x64をサポートしています。Windows ユーザーに、WechatUse には Windows 版がないと決して伝えないでください。プラグイン／スキルのバージョン 1.19.13 はメタデータです。ランタイムのリリースはそれぞれ独立してバージョン管理されています（macOS v1.19.13、Windows windows-v0.1.0）。

macOS v1.19.7 では、古いタスク記録が残っている場合のカスタムアイコン変更に関する問題が修正されています。専用の WeChat を通常の方法で終了してから、アイコンを変更または復元してください。具体的な拒否理由は保持されます。

• Windows： 以下の Windows セクションのみを参照してください。macOS の要件、アクティベーション／セットアップコマンド、LLDB、Accessibility、シェルインストーラー、または管理対象の 4.1.9 に関する手順を適用しないでください。
• macOS： Windows セクションはスキップし、macOS セクションに従ってください。
• Linux と Intel Mac の macOS には、サポート対象のネイティブランタイムはありません。

Windows x64（実験的）

スタンドアロンパッケージは https://github.com/leeguooooo/wechat-use/releases/tag/windows-v0.1.0 で公開されています。このパッケージにはランタイムが含まれています。このパッケージを使用するために、システムの Python をインストールしたり呼び出したりしないでください。動作確認済みの WeChat ビルドは 4.0.6.17 ですが、ログインの互換性には制限があります。すべての Windows 版 WeChat ビルドがサポートされるわけではありません。メディア、バックグラウンド送信、自動チャット選択、HTTP Bridge、Wechaty はサポートされていません。

再インストールする前に、インストール済みのランタイムを確認する

PowerShell で、まず Get-Command wechat-use -ErrorAction SilentlyContinue を確認し、次に既定のランチャーを確認してください。

& "$env:LOCALAPPDATA\Programs\wechat-use\wechat-use.cmd" doctor

カスタムインストールの場合は、インストール済みスキルの runtime.json を読み取ってください：$CODEX_HOME\skills\wechat-use\runtime.json。CODEX_HOME が未設定の場合は、$env:USERPROFILE\.codex\skills\wechat-use\runtime.json を使用してください。スタンドアロンインストーラーは executable、args、mcp_args を記録します。PowerShell の & 演算子を使って、その正確な実行ファイルを呼び出してください。以前のソースインストールでは、代わりに python と script が記録されている場合があります。その場合は、記録された絶対パスを -X utf8 とともに使用し、推測した python コマンドは決して使用しないでください。Claude プラグインが提供するのは手順のみです。プラグインを単独でインストール／更新しても、ランタイムはインストールされません。

ランタイムが存在しない場合は、公式の Windows インストーラーをダウンロードして実行してください。

Invoke-WebRequest -UseBasicParsing https://raw.githubusercontent.com/leeguooooo/wechat-use/windows-v0.1.0/install-windows.ps1 -OutFile install-windows.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-windows.ps1

インストーラーはダウンロードのハッシュを検証し、ユーザー専用の CLI と Codex スキルをインストールします。メッセージは送信しません。システムの Python は必要ありません。このパッケージには Authenticode 署名がありません。サポート範囲については https://github.com/leeguooooo/wechat-use/blob/main/docs/windows.md を参照してください。

読み取り、受信、送信

doctor はローカル環境の準備状況を確認します。メッセージの配信状況や現在のログイン受け入れ状況は確認しません。現在のプロセス／アカウントを特定してください。記憶していた PID を再利用したり、初期化済みの状態ディレクトリを別のアカウントに切り替えたりしないでください。

wechat-use accounts
wechat-use init --db-dir 'D:\WeChat\xwechat_files\ACCOUNT\db_storage' --pid 1234
wechat-use sessions -n 20
wechat-use contacts --query 'name'
wechat-use history 'exact_username' -n 20
wechat-use listen --once
# Preflight only: open the intended chat in WeChat first
wechat-use send filehelper 'specific text' --pid 1234
# Only after recipient/content authorization; never blindly retry
wechat-use send filehelper 'specific text' --pid 1234 --commit

履歴／検索では、正確なユーザー名が必要です。出力は JSON です（listen の場合は JSONL）。--from-start を指定しない限り、最初のリスナーはベースラインを確立します。event_id で重複を排除し、1 つの状態ディレクトリに対して複数のリスナーを同時に実行しないでください。キーは現在のユーザーの DPAPI で暗号化されています。決して表示したりアップロードしたりしないでください。

フォアグラウンド送信には、すでに開かれている曖昧さのないチャットと、空の下書きが必要です。選択中の WeChat ウィンドウが前面に表示されます。既存の送信許可を尊重しますが、依頼されていないテストメッセージは送信しないでください。送信が行われたかどうか不明な場合は、それ以上の操作をする前に履歴を確認してください。サーバーに保存された行は既読通知ではありません。

MCP では、runtime.json の executable と mcp_args（["mcp"]）を使用してください。ソースからのインストールでは、記録された python を -X utf8 <script> mcp とともに使用します。これは wechat_sessions、wechat_contacts、wechat_history、および実験的な wechat_send をサポートします。commit の既定値は false です。

古い WeChat ビルドではログインが拒否されることがあります。compat-version --pid ... は既定では検査のみを行います。この制限を修正するようユーザーから依頼された場合に限り、明示的な実験機能 --apply を適用してください。これはフィンガープリントで対象を確認したうえで、一時的なフィールドを 1 つ変更し、ロールバック用ジャーナルを保存します。今後ログインが受け入れられる保証はありません。QR コードの読み取り／ログイン確認はユーザーが行います。

Claude フックのエラー

このプラグインではUserPromptSubmit フックは定義されていません。Python が見つからないというフックエラーは、別途設定されたフックによるもので、WeChat 単体のランタイムとは無関係です。変更する前に、Claude の設定で名前が示されたフックを確認してください。無関係なフックはそのままにし、すべてのフックを無効にしたり、WeChat を再インストールしたりしないでください。ブロックしないフックエラーが発生しても、CLI が利用できないとは限りません。読み込まれたスキルにこのプラットフォームのセクションがない場合は、マーケットプレイス／プラグインを更新して Claude を再読み込みしてください。

Windows の手順は以上です。Windows では、以下の macOS セクションを実行しないでください。

macOS のみ：安定版 CLI

wechat-use

診断と読み取りコンポーネント

1.19.8 以降、送信失敗時のウィンドウ表示と診断情報のコピーでは、固定のエラーコード、失敗した手順、システムの読み取り／書き込みエラーの種類が保持されます。状態が不明な場合は自動再送しません。旧バージョンですでに省略されたエラーは復元できません。

wechat-use diagnostics --copy は、グループチャットに適した診断概要をコピーし、完全なレポートはローカルに保存します。--copy --full を指定すると、完全なレポートを明示的にコピーします。概要にチャット本文やキーは含まれません。

wechat-use runtime-custody --json は Python ファイルとその親ディレクトリのみを検査します。設定ウィンドウでは、現在のユーザーが所有する /opt/homebrew と /opt/homebrew/Cellar のグループ書き込み権限を明示的に修復し、修復記録を保存できます。コマンドラインでは runtime-custody --repair --json を明示的に実行する必要があります。所有者が不明な場合、インタープリターに書き込み可能な場合、または別のパスが問題の場合は、Python のインストールを修復してください。検証を緩めないでください。

WXS-I-SOURCE-LOCK または not_expected_shared_dms_holder が表示された場合は、まずツールのタスクを通常どおり終了し、次にツール専用の WeChat を通常どおり終了して再度開き、ログインしてから読み取りを再試行してください。データベース、-shm、-wal を手動で削除または切り詰めないでください。読み取りには引き続き元のロックとファイル検証が必要です。

1.19.9 では、ウィンドウ内の「送信前チェック」が追加されました。wechat_in_foreground または background_navigation_unavailable が表示された場合は、返された remediation_command（wechat-use setup --prepare-send）を使ってガイドを開き、ユーザーがツールウィンドウ内で画面上の確認を完了できるようにしてください。操作手順を口頭で伝えるだけにしないでください。確認では現在の条件を再チェックするだけで、メッセージの送信や元のリクエストの再実行は行いません。元のリクエストの状態が不明な場合は、元の受領確認のみを照合します。テストメッセージは個別にクリックして確認する必要があります。

セッション、未読、連絡先は個別のスナップショットを使用します。これらのクエリが成功しても、履歴メッセージが完全であるとは限りません。ツール専用の WeChat が前面にある場合、送信は明示的な wechat_in_foreground を返し、元のリクエストは自動再送されません。

doctor の read_pending は、スナップショットの更新中、または読み取りロック待ちのため、読み取りの準備ができていないことを示します。しばらくしてから再確認してください。この状態を理由に再初期化、WeChat の再起動、テストメッセージの送信を行わないでください。実際の取得、検証、権限エラーは引き続き障害として診断してください。

インストールの確認

まず wechat-use --version を実行します。プログラムが見つからない場合は、GitHub Release インストーラーを使用してください。

curl -fsSL https://raw.githubusercontent.com/leeguooooo/wechat-use/main/install.sh | sh

バイナリをnpmで配布したり、8点セットを個別に上書きしたりしないでください。不明なタスクを理由にインストールが拒否された場合は、元の状態を維持し、デバッガーを強制終了したり、意図を削除したりしないでください。新しいマシンでは、独立した4.1.9の複製を事前に用意してログインする必要があります。メインのWeChatに切り替えないでください。

トリガー

• メッセージを送る／WeChatを送る／send WeChat
• チャット履歴を調べる／WeChatの履歴／メッセージを検索する
• WeChatの連絡先／グループメンバー／未読メッセージ
• 新着メッセージを受信する／リアルタイムで監視する／on-message コールバック
• macOS 1.19.13 以降、継続的な監視はデフォルトで無効です。wechat-use listen または daemon のメッセージ購読を開始すると監視が始まり、最後の購読が終了すると、開始済みの取得を安全に完了してから停止します。購読が成功する前に、まずベースラインを検証します。--wxid は購読者に送信するイベントのみをフィルタリングします。バックグラウンドでの取得と取り消しアーカイブの対象は、引き続き現在のアカウントのメッセージデータベース全体です。HTTP メッセージストリームは接続中に必要に応じて読み取り、バックグラウンドの取り消しアーカイブは開始しません。
• search は必要に応じてインデックスを更新します。インデックスの更新が表示された場合は、しばらくしてから再試行してください。recalled は daemon のメッセージ購読中のみバックグラウンドでのアーカイブを試み、完全性は保証されません。監視していない間に取り消された元の本文は、復元できるとは限りません。WeChat の設定にある標準の取り消し防止機能とは独立しています。wechat-use setup --validate-read を使うと、継続的な監視を開始せずに、読み取りを1回検証できます。
• チャットのエクスポート／データベース統計／お気に入り
• MCP でWeChatの履歴／連絡先／モーメンツを照会する。モーメンツ機能はインストール済みのランタイムバージョンに依存します。下記の説明を参照してください。
• Hermes／n8n／Dify／LangChain のローカルエージェントとの連携
• WeChat bot framework／Wechaty-like puppet

音声の読み取りと文字起こし（macOS）

ユーザーがチャット内容の確認や音声の理解を求めた場合は、利用可能な音声文字起こしを積極的に読み取ってください。「［音声メッセージ］」とだけ返したり、ユーザーに手作業で書き起こさせたりしないでください。

• まず wechat-use history 'チャット名または正確なセッションID' -n 20 --json を実行してください。CLI はデフォルトで、ローカルで利用可能な音声を自動的に文字起こしします。テキストは display_text と media.transcript にあり、結果の状態は media.transcript_status で確認できます。--no-transcribe を指定すると、この動作は無効になります。
• MCP の wechat_get_history は現在、自動で文字起こしを行わず、独立した音声文字起こしツールもありません。音声のプレースホルダーが表示された場合は、CLI の history を使用するか、正確なメッセージの server_id を取得してから wechat-use audio transcribe <server_id> --json --include-transcript を実行してください。メッセージIDは10進数の文字列のまま扱い、JS Numberに変換しないでください。
• 独立した audio transcribe --json はデフォルトで本文を非表示にします。AIが内容を理解するには、--include-transcript を必ず追加してください。文字起こしテキストはプライベートなチャット内容です。公開用の診断情報、ログ、告知にはコピーしないでください。
• モデルまたは依存関係が不足している場合は、wechat-use audio setup を実行して初回の準備を完了してください。文字起こしの対象は、現在のアカウントでローカルに利用できる音声のみです。ダウンロードされていない、キャッシュされていない、または読み取りに失敗した場合は、状態を説明し、内容を推測せず、テストメッセージを送信せず、不明な操作を自動再試行しないでください。

モーメンツの読み取り（macOS 1.19.10）

まず、インストール済みのランタイムバージョンを確認してください。1.19.10 は wechat-use sns-feed --refresh -n 20 --json に対応しています。専用の WeChat 経由で更新をリクエストしてから、ローカルのスナップショットを読み取ります。初回の使用時には、ツール内での認証または手動確認用のウィンドウが開くことがあります。写真や動画には、返されたモーメンツのメディア参照を使用してください。チャットメッセージの参照を偽造しないでください。更新操作、ローカルへの保存、サーバーからの受領確認は、それぞれ異なる証拠です。リモートの履歴が完全であるとは保証できません。旧バージョンが db_scope_unsupported を返した場合は、そのためだけに再初期化しないでください。インストール済みの候補版と公開リリース版の状態は、それぞれ個別に確認してください。

图片读取（统一入口，普通图与HD原图已实机验收）

聊天图片使用统一的精确消息取图接口。不要要求用户先在微信里点图，也不要把加密 CDN 地址、DAT 或 WXGF 原始字节直接交给识图模型。

• history、digest、search、sent、recalled、new-messages 主动读取时，每批最多自动解析两张图。结果在 media.local_path / media.image 中；图片可用时 local_path_status=ready。
• media.image_ref 是取图引用：chatId、localId、serverId、md5。localId/serverId 保持十进制字符串，不经 JS Number 转换；chatId 使用精确会话 ID。deferred 表示未开始该图，读取任务确实需要时可用该引用继续取图。
• MCP 的 wechat_get_history / wechat_search_messages 会直接附上已可用的 image content block，模型能看见图片。其余图调用 wechat_get_image，arguments 原样使用 media.image_ref 对象；wechat_self_messages 为保护账号信息返回不透明的 image_ref 字符串，传 {"imageRef": token}。这三个读取工具可设 include_images:false 只读元数据。
• HTTP：现有 bridge 的 GET /image 和 gateway REST 的 GET /v1/image 使用同一组引用字段作查询参数，返回校验后的 PNG/JPEG/GIF/WebP 字节；继续使用原有认证。Hermes media.imageRef / media.downloadUrl 给出相同引用和相对于 bridge 的取图地址。旧 CDN 元数据不是已解密图片。
• Wechaty MessageImage 和图片类 MessageFile 返回解密、必要时转换后的 FileBox，不再将缓存 DAT 当作可显示图片。
• 搜索 HTML 报告、归档导出和聊天窗口 /img 共用同一取图服务；查看用图片与经 XML MD5 验证的原始载荷分开。
• 元数据查询、发送 ACK 检查、后台事件流只附图片引用，不偷偷启动下载。用户主动读图才调用取图接口。--no-images 可跳过主动读取的自动取图；search --no-media 也不会暗中下载。
• unavailable / 已有 pending / unknown 不自动重试，不清旧 claim/pending。保留文字和引用，明确报告图片当前不可用；不猜 URL、密钥或资源版本。

前台 history/search 若有消息分片不可安全读取，meta.status=possibly_stale_unavailable_shards 且 historical_completeness_verified=false。只能说明已返回的内容，不能据此断言没有其他消息；部分范围没有命中时返回不可用。后台接收和游标仍要求完整范围。已有环境不要因图片暂不可用而重新 init、重启微信或清理 claim/pending。

原生下载仍受签名适配、目标账号/进程、owner 生命周期和发布执行门约束。1.19起提供统一图片接口；可用范围以消息元数据、签名适配和实际取图结果为准。TP/HTTP图片资源未认证时明确返回不可用，不猜参数下载。诊断型 image inspect、会话未读计数不启动下载。朋友圈、收藏或转发子消息中的独立业务资源，不伪造聊天消息引用去下载。

初始化与升级

• init 面向已登录的专用4.1.9，只读取有限内存候选，并用首页认证和完整私有DB/WAL快照验证。不直接用SQLite打开原库，也不自动重启或安装断点。--force 重新被动扫描；正常调用可先认证同账号缓存，但仍验证私有快照。
• initialization_scope.snapshot_validated_databases列出经过完整私有快照验证的核心范围；其他可用密钥只做首页认证，full_account_integrity_verified=false。核心范围全部验证及原采集进程释放确认后，才原子切换配置。核心密钥空、缺失、歧义或超时保留旧配置；旧claim/pending不清理。
• 后续导入新分片若提示需要初始化，可重新执行被动init。已发布的初始化密钥集合不由旧分片刷新器修改。
• 1.19.7 起普通 wechat-use upgrade 先验证当前完整 SDK，已是最新版直接结束，不暂停服务。有新版本才受控暂停并恢复服务；占用时正常退出专用微信和设置窗口，init 不会解除占用。
• 升级以GitHub Release八件套为一个原子版本。服务更新先核验原owner，再正常退出旧服务；未知owner会拒绝更新，不强杀调试器。
• doctor --paths的page_authenticated仅证明密钥匹配，logical_integrity_verified=false；它不证明全库、历史消息或接收端已验证。

日常操作

专用微信须已经登录；缺少副本时先按 准备指南 创建。默认绑定保存在 ~/.wx-rs/managed-wechat.json。副本关闭或账号未就绪时明确报告，不切到主微信。

wechat-use setup
wechat-use doctor --json
wechat-use sessions -n 20 --json
wechat-use contacts --query '名字' --json
wechat-use history '群名或精确ID' -n 50 --json
wechat-use search '关键词' --in '群名' --json
wechat-use history '精确会话ID' -n 50 --json --no-images

优先使用精确会话 ID。昵称或群名有歧义时查看候选，不自行选人。查询失败、覆盖不足或超时不能解释成“没有消息”；保留结构化状态。

发送必须有用户明确的收件人和内容授权。只读检查不发送测试消息，也不要求用户先手动发一条消息。

wechat-use send '具体内容' '收件人' --json
wechat-use send --file /absolute/path/report.txt --recipient '收件人' --json
wechat-use send --image /absolute/path/image.png --recipient '收件人' --json

发送前确认接收者；正常操作不激活、抬起或切换微信窗口。submitted_unconfirmed / status_unknown 不是失败，也不是送达。保留原 request ID，先查询原回执和精确历史，不换 ID 重发；发送者服务器记录不等于对方已读或接收文件字节一致。

1.19.1 可在设置窗口点击“核对原请求（不重发）”，或运行 wechat-use send-receipt --request-id ORIGINAL_ID --expected-account ORIGINAL_ACCOUNT --json。必须沿用原请求保存的精确账号；只连接已有后台，查询失败也不启动后台或重发。

1.19.4 起，doctor --json 的 submission_ready 表示当前接口可提交；send_ready 和 send_delivery_verified 不因此变为已验证。强送达未验证不会单独阻断环境自检，也不要据此重发未知请求。

设置提示缺少系统授权时，点击“授权并继续”，由本人确认 macOS 管理员弹窗，无需运行终端命令。取消后可以稍后继续；不要反复修复安装。

接入 agent

• 只读 MCP 使用 wechat-mcp stdio server。历史、搜索、图片工具走同一读取服务；图片可用时返回图片 content block。MCP 发送由独立的 wechat-send-mcp 提供，仅在用户需要发送能力时配置。
• HTTP Bridge 默认监听本机 127.0.0.1:18400。/health 检查当前 daemon、接收和发送就绪状态；不能只看 HTTP 200。接收状态 inactive 表示当前没有 daemon 消息订阅，不代表后台故障，也不代表读取已验证。
• Hermes 使用 wechat-bridge --shape hermes。群里是否 @ 当前账号以 bridge 的 isMentioned 为准；用 fromSelf 排除自发消息，不能只比较 senderId。
• /messages/stream?since=<epoch> 使用明确起点，避免无意回放全部历史。事件流只带媒体引用；主动需要图片时调用 /image，不要把加密 CDN 地址直接交给识图模型。
• Wechaty 使用 wechat-wechaty-gateway；图片返回可显示的 FileBox。CLI、MCP、Bridge、gateway 的细节以各自 --help 和 能力说明 为准。

程序分别为 CLI wechat、后台 wechatd、HTTP wechat-bridge、只读 wechat-mcp、发送 wechat-send-mcp、wechat-wechaty-gateway 及两个内部校验/任务组件。内部组件不接收聊天内容或由调用方提供的任意代码；不要逐件替换版本。

恢复与数据保护

wechat-use setup 复用已有登录、激活和有效权限。权限步骤以 setup --json 的 service.accessibility_required 为准；1.19 public 原生后台路径为 false，使用系统调试接口，不转入旧版辅助功能拖图标流程。日常读取复用已验证的密钥，不要求重启微信或点开图片。

密钥、配置、源消息 XML、账号标识和私有诊断只保存在用户自己的机器；不打印、上传或提交到仓库。不要用 SQLite 直接打开微信原库，不覆盖原库，不清理未知任务的 claim、pending 或输出。