pi-weixin-bridge

中文 | English

把 pi（编码 Agent）接入微信 ClawBot 的桥接服务。直连腾讯官方 iLink 协议，不依赖 OpenClaw，pi 通过 SDK 同进程接入。

在微信里给 ClawBot 发消息，即由 pi 处理并回复——把 pi 的全部能力（含 skills、工具）带到微信聊天界面。

架构

flowchart TD
  微信 -->|iLink HTTPS| 桥接服务
  桥接服务 --> 附件保存与anydoc转换
  附件保存与anydoc转换 --> pi会话
  桥接服务 --> pi会话
  pi会话 -->|文本与文件工具| 桥接服务
  桥接服务 -->|上传与回复| 微信

协议参考腾讯官方开源仓库 Tencent/openclaw-weixin（本服务剥离了其中的 OpenClaw 依赖，仅保留 iLink 客户端）。

前置条件

• 微信 App 8.0.70+，且账号已开通 ClawBot 插件（设置 → 插件 → 微信ClawBot，官方灰度放量中）
• Node.js 22.19+（pi-coding-agent SDK 及其内置 undici 要求 Node 22.19 及以上）
• 已安装并配置好 pi（本服务复用 ~/.pi/agent 下的模型与鉴权配置）

安装与运行

一键安装（推荐，对标 openclaw-weixin-cli）

npm install -g pi-weixin-bridge
pi-weixin-bridge install

install 会依次：① 交互式选择保存路径（状态目录 / pi 工作目录，回车用默认，可 install --yes 跳过询问）→ ② 显示二维码供微信扫码绑定（已有账号则跳过）→ ③ 读取 pi models.json，选择供应方和默认模型 → ④ 启动后台 daemon → ⑤ 生成 Windows 后台快捷方式。非交互安装必须已有有效默认模型，或通过 PI_WEIXIN_MODEL 指定，仍会在未登录时显示二维码。

路径选择说明：

• 状态目录：账号凭据、会话上下文、后台日志的存放位置，默认 ~/.pi-weixin-bridge；选择后写入 ~/.pi-weixin-bridge/config.json，后续所有进程（含 daemon 子进程）自动生效
• pi 工作目录：Agent 读写文件的工作区，新安装默认 ~/pi-weixin-project，已有 Windows 配置且旧目录存在时保留 D:\pi_weixin_project
• 安装时会实际探针校验两个目录可写；POSIX 下自动收紧权限（状态目录 700、账号文件 600，凭据不可被其他用户读取）

CLI 命令

pi-weixin-bridge install     # 一键安装（扫码绑定 + 后台 daemon + 快捷方式）
pi-weixin-bridge login       # 扫码登录 / 重新绑定微信
pi-weixin-bridge config      # 配置路径、模型、访问权限、项目、文件上限和预算
pi-weixin-bridge start       # 前台运行桥接服务（默认）
pi-weixin-bridge stop        # 停止后台 daemon
pi-weixin-bridge status      # 查看后台 daemon 状态（pm2 list 风格表格：重启次数 / CPU / 内存 / 运行时长）
pi-weixin-bridge daemon      # daemon 管理：start/stop/status/restart/logs/install-boot/uninstall-boot
pi-weixin-bridge update      # 从 npm 更新最新版并重启后台
pi-weixin-bridge uninstall   # 卸载（停服务、删自启与快捷方式，保留账号）
pi-weixin-bridge help        # 帮助

npm 更新与卸载

pi-weixin-bridge update
# 或停止后台后安装指定版本，再启动
pi-weixin-bridge daemon stop
npm install -g pi-weixin-bridge@版本号
pi-weixin-bridge daemon start

# 先移除后台服务、自启和快捷方式，再移除 npm 包
pi-weixin-bridge uninstall
npm uninstall -g pi-weixin-bridge

GitHub 保存源码和 CI，用户安装与升级统一使用 npm 上已发布的包。账号与本地配置在卸载后保留。更新前停止后台，npm 安装失败时保持停止并明确提示；重新安装成功后运行 daemon start。

后台 daemon 常驻部署（内置，默认推荐）

重要：后台进程无法扫码，须先交互式登录一次（pi-weixin-bridge install 选择模型并扫码，账号落盘），再启动 daemon。

# 1. 安装并选择模型（自动启动后台）
pi-weixin-bridge install

# 2. 启动后台 daemon（supervisor 常驻：崩溃自动重启、指数退避、日志轮转）
pi-weixin-bridge daemon start
pi-weixin-bridge daemon status    # 查看状态（pm2 list 风格表格）
pi-weixin-bridge daemon logs      # 查看日志（末尾 50 行）
pi-weixin-bridge daemon restart   # 重启
pi-weixin-bridge daemon stop      # 停止

内置 daemon 零第三方依赖，PID/日志落在 ~/.pi-weixin-bridge/daemon/；后台重启和自启依赖 npm 包及 Node 路径存在，跨平台（Windows/POSIX）。

曾用 PM2 运行？ 1.6.0 起不再提供 PM2 配置。先 pm2 stop pi-weixin-bridge 停掉旧进程（避免两个实例同时轮询同一账号），再用 pi-weixin-bridge daemon start 启动。

会话过期（errcode -14）重新扫码：后台模式无法交互扫码，日志会提示：

[main] 后台模式无法扫码。请在终端运行 `pi-weixin-bridge login` 重新扫码，扫码完成后服务自动恢复

在任意终端跑 pi-weixin-bridge login 扫码即可，daemon 检测到账号更新后自动恢复，无需重启服务。

开机自启（可选）：

pi-weixin-bridge daemon install-boot     # 注册每用户登录计划任务（免管理员）
pi-weixin-bridge daemon uninstall-boot   # 移除

Windows 后台快捷方式

运行 pi-weixin-bridge install 会在 npm 包目录生成 start-pi-weixin-bridge.lnk 与 stop-pi-weixin-bridge.lnk，双击即可启动或停止后台。快捷方式以最小化方式运行 Node.js，后台子进程隐藏窗口，并保存状态目录、工作目录、模型和 pi 配置目录。

CLI 与业务脚本使用 Node.js，不调用 PowerShell、cmd 或 bash。Windows 的快捷方式、进程统计和登录任务由固定版本 [email protected] 调用 COM 接口执行；Windows 安装需要 Visual Studio 2022 C++ 构建工具及 Python，原生模块编译失败会终止安装。自启注册仍需运行 pi-weixin-bridge daemon install-boot。

Windows / macOS / Linux 适配

三平台均使用 Node.js 22.19+ 和 npm 全局安装，首次运行 install 完成路径、微信登录和模型选择；后续通过 config 修改配置。新安装默认工作目录为 ~/pi-weixin-project；已有 Windows 配置且旧 D:\pi_weixin_project 存在时保留旧目录，显式路径与环境变量仍优先。

• Windows：使用 Node.js 原生 COM 绑定，无需 PowerShell 或 cmd；支持含空格的 npm 包路径、最小化快捷方式与每用户登录计划任务。
• macOS：后台进程及状态统计使用系统工具；登录自启保存至 ~/Library/LaunchAgents，通过系统 plutil 转换配置，直接运行前台 supervisor，由其管理桥接子进程。注册前先停止已有后台，避免重复实例。
• Linux：后台不依赖 systemd；登录自启需要可用的 systemd 用户会话。无 systemd 的容器或 WSL 可使用 daemon start，前台托管可用 start。

macOS 登录自启：

pi-weixin-bridge daemon stop
pi-weixin-bridge daemon install-boot
pi-weixin-bridge status
pi-weixin-bridge daemon uninstall-boot

自启依赖注册时的 Node、npm 包与配置路径；切换 Node 版本或修改路径后重新注册。三平台 CI 检查全部通过才允许 main 中的版本变化触发发布。

Linux / WSL

本项目跨平台（Windows / Linux / macOS，daemon 杀进程树自动适配平台）。Linux 下同样支持后台 daemon 与会话过期重登（headless），无需扫码即可后台运行。

npm install -g pi-weixin-bridge
pi-weixin-bridge install       # 选择路径、扫码和模型，随后启动后台

• 安装向导在非 TTY（如 CI / SSH 无终端）下自动使用默认路径；交互终端则会询问状态目录与工作目录。
• 开机自启用 systemd 用户服务（免 root）：

  pi-weixin-bridge daemon install-boot     # 注册并 enable systemd user service
  pi-weixin-bridge daemon uninstall-boot   # 移除
  

  如需未登录也随开机启动，请管理员执行 loginctl enable-linger <用户名>。
• WSL 需启用 systemd（wsl --update + 发行版内 systemd 作为 PID 1），否则 daemon install-boot 会提示不可用，可手动 daemon start。
• 凭据文件在 Linux 下自动收紧为 600、状态目录 700。
• 注意：WSL 与 Windows 的 ~ 不同，两端账号/状态相互独立，互不干扰。

配置

配置解析优先级：环境变量 > ~/.pi-weixin-bridge/config.json（install / config 写入）> 平台默认。

运行 pi-weixin-bridge config 交互式选择配置项；config model 单独选择 models.json 中的供应方和默认模型。配置不重新扫码、不自动启动后台，不改变已有会话通过 /model 选择的模型。

pi-weixin-bridge config help
pi-weixin-bridge config show
pi-weixin-bridge config models
pi-weixin-bridge config model 1
pi-weixin-bridge config get model
pi-weixin-bridge config set budget.dailyTokens 100000
pi-weixin-bridge config set budget.timeZone Asia/Shanghai
pi-weixin-bridge config set maxFileBytes 20971520
pi-weixin-bridge config unset budget.dailyTokens

模型编号对应当次 config models 列表，也可传入完整供应方/模型引用。config set <配置项> <值> 与 config unset <配置项> 支持 model、stateDir、workspace、access、access.admins、access.allowFrom、access.permission、budget、budget.dailyTokens、budget.dailyCost、budget.timeZone、maxFileBytes、projects。数组和对象使用 JSON；建议在交互式 config 中输入 JSON，避免终端参数引号差异。

配置保存前校验模型目录、权限、正数预算、时区、文件上限与项目结构，失败不改写原配置。修改嵌套项保留其他字段；unset access.admins 或 unset access.allowFrom 保留空列表，unset access 会恢复所有联系人完整权限，设置访问限制时必须配置管理员编号。

保存后执行 pi-weixin-bridge daemon restart。修改状态目录或默认工作目录前必须 daemon stop；状态目录变更不会自动迁移旧账号、会话或任务，新目录需已有账号或重新登录，改路径后须重新注册自启。环境变量仍优先，可通过 config show 查看覆盖。从 1.6.1 升级后若提示未选择默认模型，运行 config model，再 daemon start。

程序不读取 .env 文件，以上变量需直接设置到系统环境（Windows 用 setx，POSIX 写入 shell 配置）。

config.json 示例（由 install / config 生成，可手改）：

{ "stateDir": "D:\\data\\piwx", "workspace": "D:\\pi_weixin_project" }

权限：POSIX 下状态目录与账号凭据文件会自动收紧为 700 / 600；Windows 依赖用户目录 ACL（默认即仅当前用户可访问）。

项目结构

src/
├── index.ts          # 入口：登录、状态持久化、会话超时/鉴权失效重登、优雅退出
├── cli.ts            # CLI 命令（install/login/config/start/stop/status/update/uninstall/help）
├── wizard.ts         # 安装向导：路径选择、可写探针、扫码、模型选择
├── config-command.ts # `config` 子命令：show/get/set/unset/models/model
├── account.ts        # 账号凭据读写（结构校验 + 隔离备份 + 0600 原子写）
├── config.ts         # 协议常量与路径配置（原子写保存）
├── fs-atomic.ts      # 共享原子写：循环写满 + fsync 文件与父目录 + 失败清理临时文件
├── models.ts         # pi models.json 读取与模型目录
├── catalog.ts        # skill / MCP 列表（外部元数据清洗 + 结构校验）
├── command.ts        # 斜杠命令处理（/help /status /stop 等直接响应）
├── platform.ts       # Windows 辅助脚本调用（winax COM 绑定）
├── npm-command.ts    # npm 命令解析（含 Homebrew 布局候选路径）
├── bridge.ts         # 主循环：getUpdates → 媒体 → pi → sendMessage，typing 状态、任务通知
├── daemon/           # 内置后台 daemon（零第三方依赖，替代 PM2）
│   ├── daemon.ts     # 控制端：拉起/停止 supervisor 进程树、PID 与日志、退避策略
│   ├── supervisor.ts # supervisor 进程：子进程崩溃自动重启（指数退避）、日志轮转
│   ├── boot.ts       # 开机自启：Windows 计划任务 / macOS LaunchAgent / Linux systemd 用户服务
│   ├── process-lock.ts # 独占实例锁：非法内容容错、.reclaim 残留回收
│   ├── pid-identity.ts # PID 身份校验：启动时间比对，防 PID 复用误杀进程组
│   └── procs.ts      # 进程统计（跨平台 CPU / 内存 / 运行时长采样）
├── features/         # 业务能力
│   ├── service.ts    # 斜杠命令编排：/project /model /files /history /schedule 等
│   ├── policy.ts     # 权限沙箱：access 白名单、项目 profile、checkedPath 路径限制
│   ├── approvals.ts  # 工具执行确认（guarded 模式，编号 + 超时 + 参数复核）
│   ├── scheduler.ts  # 定时任务（cron / 单次，失败暂停）
│   ├── library.ts    # 资料库：SHA-256 去重、本地全文检索
│   ├── journal.ts    # 任务历史（500 条上限，running 优先保留）
│   ├── usage.ts      # Token / 成本预算账本（NaN 防护）
│   └── state.ts      # ScopedState 持久化：损坏隔离 + 结构校验 + 原子写
├── logger/           # 分级日志（info/warn/error/debug + 时间戳）
├── ilink/
│   ├── types.ts      # iLink 协议类型与枚举
│   ├── client.ts     # HTTP 客户端（请求头、长轮询、收发、typed errors）
│   ├── errors.ts     # 错误类型（Network/Auth/Protocol/SessionTimeout）
│   ├── login.ts      # 扫码登录流程（含重定向、配对码、过期刷新）
│   ├── context-store.ts # context_token / typing ticket 持久化（0600 原子写）
│   ├── message.ts    # 消息正文提取（文本 / 语音转文字，类型校验）
│   └── media.ts      # 媒体：AES 加解密、CDN 流式下载限额、上传
├── message/          # 消息构造 / 解析 / 通知
│   ├── parser.ts     # 入站消息解析（畸形字段安全降级，归一化数组）
│   ├── builder.ts    # 出站消息构造（文本/图片/文件/视频）
│   ├── documents.ts  # anydoc 文档转换编排 + 产物完整性校验（sidecar 指纹）
│   ├── task-queue.ts # 按会话串行的任务队列（abort 传播、失败不阻塞）
│   ├── task-notifier.ts # 任务进度通知（开始/每 30 秒/结束，顺序保证）
│   └── markdown.ts   # markdown 格式化 / 转义 / 字素簇安全分块
└── pi/
    ├── sessions.ts   # pi 会话管理（隔离 + 串行化 + 空闲淘汰 + ResolvedProfile 权限契约）
    └── conversation-store.ts # 对话持久化（索引损坏自愈）
examples/             # 示例（echo-bot 最小回声机器人）
test/                 # 单元测试（vitest，含 pid-lock 14 例）

最小示例见 examples/echo-bot.ts。

iLink 协议要点

• 基地址：https://ilinkai.weixin.qq.com（登录后可能因 IDC 调度切换）
• 请求头：AuthorizationType: ilink_bot_token、Authorization: Bearer <bot_token>、X-WECHAT-UIN、iLink-App-Id: bot 等
• 核心接口：get_bot_qrcode / get_qrcode_status（登录）、getupdates（长轮询收消息）、sendmessage（发消息）、getconfig / sendtyping（输入状态）、getuploadurl（媒体上传）
• 关键机制：回复须原样带回入站消息的 context_token；getupdates 用 get_updates_buf 做增量同步；errcode -14 表示会话超时需重登
• 媒体：CDN 域名 https://novac2c.cdn.weixin.qq.com/c2c，AES-128-ECB 加解密；入站图片解密后转 base64 供 pi 视觉理解，出站图片经 send_weixin_image 工具上传发送

功能范围

• ✅ 扫码登录 + 凭据持久化 + 会话超时自动重登
• ✅ 文本消息收发（私聊 / 群聊 @）
• ✅ 按微信会话隔离的 pi 多会话 + 串行化
• ✅ 对话自动保存，服务重启后继续上下文；/new 开始新的持久对话
• ✅ 任务开始确认、长任务每 30 秒进度、失败与停止通知
• ✅ 「正在输入」状态提示（getconfig + sendtyping）
• ✅ 入站媒体：图片（解密→pi 视觉）、语音（服务端转文字）、文件/视频（解密落盘→告知路径）
• ✅ 入站文档：anydoc 0.2.4 自动将 PDF、Word、PowerPoint、Excel、OpenDocument、RTF、EPUB、CSV 转为 Markdown 后交给 pi
• ✅ 出站媒体：图片/文件/视频经 CDN 上传后发送（send_weixin_image 工具 + builder）
• ✅ 长文本分块发送（markdown 分块，避免超出微信单条长度）
• ✅ 分级日志 + 错误分类（网络/鉴权/协议）+ 鉴权失效自动重登
• ✅ context_token / typing ticket 持久化（重启恢复）
• ✅ 斜杠命令（基本命令：/help / /status / /new / /model / /skill / /mcp / /reload / /usage / /stop / /ping），未知命令交由 pi
• ✅ 内置后台 daemon（崩溃自动重启 + 日志轮转 + 开机自启，零第三方依赖；Windows 计划任务 / macOS LaunchAgent / Linux systemd 用户服务）
• ✅ 跨平台（Windows / Linux / macOS），安装向导交互式选择保存路径 + 凭据权限加固（POSIX 700/600）
• ✅ 状态文件损坏只降级不瘫痪：JSON 语法或结构非法自动隔离 .corrupt-* 备份并按空数据运行，覆盖任务记录、资料、定时任务与会话索引
• ✅ PID 身份校验：PID 文件记录进程启动时间，PID 被系统复用时拒绝发信号，daemon stop 不误杀无关进程（含进程组）
• ✅ 附件流式限额：按 Content-Length 预检、边读边计数，图片纳入同一上限，超限向用户透传具体字节数
• ✅ 会话空闲淘汰（上限 32、空闲 30 分钟，处理中永不淘汰），会话已持久化，淘汰后重开不丢上下文
• ✅ 消息长文本按字素簇分块，ZWJ 组合、肤色修饰、国旗 emoji 不再被拆散
• ⬜ 出站语音（需 silk 编码，未做）

对话恢复与任务通知

对话保存在状态目录的 sessions/ 下，按账号、工作目录和微信对话隔离。重启后收到下一条普通消息时恢复当前对话；/new 切换到空白对话并保存选择，旧记录保留。保存的是对话内容，不会自动重做重启前未完成的任务；升级前仅保存在内存中的历史无法恢复。

任务开始时发送确认，长任务每 30 秒报告处理阶段、耗时和已结束的工具调用次数，普通回复作为完成结果。任务失败或停止会提示；通知不包含工具参数和原始错误，详细原因写入服务日志。会话文件可能包含用户消息、图片和工具结果，请限制状态目录访问权限。通知发送失败单独记录，不中断 Agent 任务。

附件自动处理

发送 PDF、Word、Excel、PowerPoint 等受支持文档时，桥接服务先保存原件，再使用内置的 anydoc 0.2.4 本地转换为 Markdown，将原件和 Markdown 路径交给 pi。支持格式以 anydoc 的内容识别和扩展名识别结果为准；Markdown、普通文本与其他文件保留现有路径处理方式。转换结果保存在原件旁边（原文件路径.md），不会覆盖原件；长时间转换会在任务进度中显示。转换每个文件最多运行 120 秒，子进程控制输出上限为 16 MiB。

扫描型 PDF 会明确提示需要 OCR，原件保留，默认不上传外部服务；若要使用 Firecrawl 云端 OCR，须另行确认上传。损坏或加密文档转换失败时通知用户，不把失败文件当作已转换文档交给 pi。转换产物带完整性校验（sidecar 记录输入指纹与输出哈希）：超时或中止留下的截断 Markdown 不会被当作转换成功复用，会自动清理并重新转换。

模型

安装扫码后自动读取 pi 的 models.json 中实际配置的供应方，按供应方编号和模型编号选择，保存默认值到 ~/.pi-weixin-bridge/config.json。不预设供应方。PI_CODING_AGENT_DIR 可指定 pi 配置目录，鉴权沿用 pi；缺失配置或默认模型时明确报错。

微信 /model 查看当前会话模型，/model list 列出供应方、模型及编号，/model <编号或供应方/模型> 仅切换当前会话，选择持久化，其他会话与安装默认值保持原选择。/reload 更新配置并保留各会话选择；环境变量 PI_WEIXIN_MODEL 指定安装默认模型。

斜杠命令

命令回复统一用 markdown 列表格式（微信端按 markdown 渲染；单换行会被折成空格，列表项才是硬换行）。

文件、会话与资料

模型可调用 send_weixin_file 把当前项目内的报告、PDF、Word、Excel 等实际文件发回当前对话；默认单文件上限 20 MiB，可通过 maxFileBytes 调整。发送前检查真实路径，拒绝目录和越出项目的路径。

• /sessions 查看当前项目历史；/resume <编号> 切换；/rename <名称> 命名；/export 导出并发送 HTML。
• /files 查看保存的资料；/files find <关键词> 本地检索；/file <编号> 取回原件；/file <编号> markdown 取回转换结果。
• 资料按当前微信对话保存，内容 SHA-256 去重（去重要求原文件仍在，被清理后重传同一文件会重新保存）；原件位于接收时的项目 .weixin-files/，索引位于状态目录 documents/。切换项目后，文件取回仍要求当前项目包含该文件，必要时先切回原项目。
• 本地全文检索最多加载最近 200 份资料，按新旧顺序占用预算（新资料优先），每份文本不超过 2 MiB、总计 32 MiB，返回最多 8 个片段与来源；单个文件丢失只跳过该文件。模型也可用 search_weixin_files 检索。
• 扫描 PDF 使用 /ocr <文件编号>，机器人展示上传 Firecrawl 的文件与费用提示后，用户再发 /approve <确认编号> 才会执行。仅此次文件获授权；/reject <编号> 拒绝，120 秒未确认则取消。
• anydoc 支持的办公文档内嵌图片会另存为资产；PDF 内嵌图片不通过不受支持的 toDocument 提取。转换每文件超时 120 秒；子进程控制输出上限 16 MiB，Markdown 文件本身由磁盘容量限制。

权限与项目

配置文件可加入以下字段，示例中的微信用户标识和工作目录需要替换为实际值：

{
  "access": {
    "admins": ["你的微信用户标识"],
    "allowFrom": ["只读用户标识"],
    "permission": "guarded"
  },
  "projects": {
    "reports": {
      "workspace": "D:\\reports",
      "permission": "guarded",
      "tools": ["read", "grep", "find", "ls", "write", "edit", "send_weixin_file", "search_weixin_files"]
    }
  },
  "maxFileBytes": 20971520,
  "budget": { "dailyTokens": 100000, "dailyCost": 5, "timeZone": "Asia/Shanghai" }
}

未配置 access 时保持个人使用方式，能发消息的用户具有完整权限；配置后只接收管理员及白名单消息，普通白名单用户为只读。管理员的 guarded 模式在工具执行前展示完整参数，写入、命令执行与文件发送等待编号确认；参数超过展示上限则拒绝操作。full 允许完整工具执行，read-only 仅允许读取、查找和资料检索，并禁用用户扩展和技能。

/project 查看项目，/project reports 切换。项目支持 model、tools 与 skills 名单，模型使用实际 供应方/模型编号。会话模型选择优先于项目模型，再使用安装默认模型；切换项目清除之前的模型覆盖。工作目录与工具限制不构成操作系统沙箱，完整权限的命令及用户扩展仍需可信。

任务历史、定时与预算

/history 查看持久任务记录，/result <编号> 查看最后保存的文本回复或错误。相同消息编号不会重复提交模型；重启时把未结束的任务标记为中断。/retry <编号> 需要再次确认，使用原指令与已保存的附件重新处理，不回滚之前的修改；未完成下载的附件需要重发。/tasks 和 /cancel 使用当前队列编号，/history 使用持久记录编号，两者用途不同。

/schedule add {"prompt":"检查工作目录并汇报","cron":"0 9 * * *","timeZone":"Asia/Shanghai"}
/schedule add {"prompt":"汇总今日资料","at":"2026-10-01T09:00:00+08:00","timeZone":"Asia/Shanghai"}
/schedule
/schedule pause <编号>
/schedule resume <编号>
/schedule delete <编号>

单次日期必须在未来且带时区，周期由 cron-parser 解析。仅管理员可创建和管理。服务需要持续运行及有效微信上下文才能执行、投递；重启不补做正在执行的任务，失败或中断会暂停并保留原因。定时任务使用独立会话，不自动引入普通对话的附件；原项目选择发生变化时暂停。guarded 项目的定时执行使用只读工具，full 项目保留完整权限；当前定时任务只投递文本，普通对话支持文件回传。

/daily 按配置时区报告今日已返回用量，budget 达标后拒绝后续请求；未返回 usage 的请求明确记为未知，已报告的部分仍累计。预算无法保证单次任务不超额。/doctor 只读检查本地目录、模型配置与权限，不发送模型请求，不输出凭据。

状态目录新增 preferences/、documents/、tasks/、usage/ 和 schedules.json；记录不保存附件解密参数或微信上下文令牌。微信上下文独立存于 contexts/，按账号隔离；旧 context.json 不跨账号迁移，升级后向机器人发一条消息以刷新上下文。历史、结果、文件可能含私密内容，不自动清理，请维护目录访问权限。

⚠️ 安全提示

pi 是具备工具执行能力的编码 Agent（默认含 bash 等工具）。接入微信后，任何能给该 ClawBot 发消息的人，都可能通过对话让 pi 在你的机器上执行命令。请务必：

• 仅在私聊中使用，不要将 ClawBot 拉入不可信的群聊
• 通过 PI_WEIXIN_WORKSPACE 限定 pi 的工作目录，降低误操作影响面
• 使用 config.json 的 access 白名单、管理员与项目 tools/skills 限制；选择 guarded 要求操作确认

开发

npm run typecheck   # 类型检查（tsconfig.check.json，覆盖 src/ 与 test/）
npm test            # 单元测试（vitest；pretest 自动清理测试残留目录）
npm run build       # 构建到 dist/

依赖说明：tsx 为运行时依赖（npm bin 入口经它直接运行 TS 源码，无需构建）；fast-xml-parser 仅测试使用，位于 devDependencies。已知问题：生产依赖链含 [email protected]（经 pi-coding-agent → openai，修复版 8.12.2 被 SDK 锁版，npm audit 报 high 但无法在本仓库修复），需上游发版。

CI：GitHub Actions 在 push / PR 时自动跑 typecheck + test + build（Node 22 × ubuntu / windows / macos）。推送到 main 后比较推送前后的 package.json 版本号，仅版本变化且检查通过时发布 npm 并创建 GitHub Release；版本不变和 PR 均不发布。发布前由维护者确认版本号、CHANGELOG 和验证结果，再修改版本并推送；CI 不另设审批步骤。npm 已发布的版本跳过上传，仍可补建缺失的 Release。

后台 status 区分初始化、等待扫码、消息循环已启动与重启中。前台和后台桥接共享独占实例锁，重复启动拒绝；PID 文件损坏时明确报错。停止先发 SIGTERM 让桥接中断模型请求、发送中断通知并释放锁，宽限期后仍未退出才强杀；失败保留 PID 信息。前台运行与登录过程中首次 Ctrl+C 为优雅停止，再次 Ctrl+C 立即退出。Windows 自启直接使用绝对 Node 路径，启动器等待结果并传播退出码；Linux unit 保存自定义路径并配置 ExecStop。实际系统注册需要在使用机器上执行。

故障排查

许可

MIT。本项目的 iLink 协议客户端（src/ilink/）衍生自腾讯开源的 Tencent/openclaw-weixin（MIT 许可，Copyright Tencent），完整归属与原始许可证见 NOTICE。