Skip to content
BranchesTags

Repository files navigation

FakeClaw

并非龙虾！一个运行在 Windows 上的无 token 消耗、轻部署的自动化工具，功能是多平台消息通知转发器和这台电脑上多种 IDE 的远程操作桥。

原理是服务常驻本机，负责监听系统通知和私聊命令，再通过消息平台转发与本地桌面自动化完成 IDE 操作及结果回传。

当前支持 NapCat / QQ、Telegram、飞书、企业微信 作为消息入口。

快速入口：快速开始 | 消息平台 | 远程命令 | 校准与兼容性 | 环境变量

主要功能

  • 把这台 Windows 机器上的 IDE、终端和桌面应用通知 转发到指定消息平台私聊，方便在离开电脑时继续看本机动静
  • 通过私聊 远程拉起本机 IDE，切换到目标窗口，并把提示词粘贴到聊天输入区
  • 支持按需 只粘贴不发送，适合先远程准备提示词、再回到电脑上手动确认
  • 每次自动化任务结束后都会 回传执行结果和桌面截图，方便确认到底有没有命中正确窗口和输入区
  • 支持通过 统一配置、校准脚本和本地校准网页 修正不同机器、不同分辨率、不同 IDE 布局下的输入框定位问题
  • 支持 Windows 托盘常驻控制，可查看运行状态、暂停/恢复通知、重启服务并打开配置面板修改 .env
  • 支持 快速回复，支持的 IDE 通知转发后，下一条非命令私聊可直接发送到对应 IDE

本次更新

  • 新增统一消息平台抽象，可在 NapCat / QQ、Telegram、飞书、企业微信 之间切换
  • 扩展 .env.example，补齐各平台机器人与鉴权相关配置
  • 新增 docs/messaging-platforms.md，汇总各平台接入说明
  • 新增 快速回复自动指定 IDE 逻辑，收到支持的 IDE 通知后可直接回一句话继续执行
  • 统一了桌面自动化配置，布局阈值集中放在 config/desktop-automation.config.json
  • 新增桌面校准脚本和批处理入口，方便在不同机器上重新标定输入框位置
  • 新增本地校准网页，可在浏览器里分析候选输入区、试跑草稿配置并保存
  • 新增 start-tray.bat 和托盘程序，可从系统托盘管理服务状态、通知开关与平台配置
  • 新增显示保活和本地管理接口，便于后台常驻运行

消息平台

支持的平台与入口：

  • NapCat / QQ: 默认模式，使用 WebSocket 收发消息，startup/start-qq.bat 会先拉起 NapCat 再启动服务
  • Telegram: 使用 Bot API 长轮询收发私聊消息，启动入口为 startup/start-telegram.bat
  • 飞书: 使用长连接接收私聊文本命令，启动入口为 startup/start-feishu.bat
  • 企业微信: 使用自建应用回调接收命令并回发消息，启动入口为 startup/start-wecom.bat

注意：目前仅 QQ 和飞书机器人通信经过实测，其余平台的机器人通信链路尚未经完整测验。

通用规则：

  • 通过 BOT_PLATFORM 选择当前消息平台，默认值为 napcat
  • 各平台都复用同一套 /help、/status、/shot 和 IDE 自动化命令
  • 当前选中平台对应的授权用户会同时作为通知接收方和远程命令执行者

更详细的接入字段、回调地址和公网要求见 docs/messaging-platforms.md。

IDE 支持矩阵

IDE 通知转发 远程操作 支持程度 / 备注
Codex 支持 open / focus / minimize / paste / send / screenshot 相对稳定
Cursor 支持 open / focus / minimize / paste / send / screenshot 可用，建议校准后使用
Trae 支持 open / focus / minimize / paste / send / screenshot 可用，建议校准后使用
Antigravity 支持 open / focus / minimize / paste / send / screenshot 可用，建议校准后使用
CodeBuddy 支持 open / focus / minimize / paste / send / screenshot 适配一般，依赖布局与兜底点击，建议保守使用
VS Code 支持 open / focus / minimize / paste / send / screenshot 可用，优先走 VS Code 专用规则，再回退到通用规则，建议校准后使用
Windsurf 支持 不支持 仅通知转发
Kiro 支持 不支持 仅通知转发
JetBrains IDEs 支持 不支持 仅通知转发，含 AI Assistant / Junie 及宿主 IDE
Zed 支持 不支持 仅通知转发
PowerShell 支持 不支持 仅通知转发

补充说明：

  • Trae CN 共享 Trae 的远程自动化能力与校准配置，命令目标为 traecn
  • CodeBuddy CN 共享 CodeBuddy 的远程自动化能力与校准配置，命令目标为 codebuddycn
  • VS Code 的通知来源仍归一化为 Code，远程命令目标为 vscode
  • 所有远程自动化任务都会串行执行；忙碌时会直接拒绝，不排队

快速开始

依赖

  • Windows
  • Node.js 22+
  • 已授予 Windows 通知读取权限
  • 已在需要转发的 IDE 或桌面应用里开启系统通知，至少要允许横幅或通知中心提示
  • 如需使用托盘程序，还需要本机可用的 .NET Framework C# 编译器：C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe

按平台补充：

  • NapCat / QQ 模式需要本机已安装并登录 NapCat
  • Telegram 模式需要可用的 Bot Token 和私聊 Chat ID
  • 飞书 模式需要本机可访问公网并在飞书后台启用长连接接收事件
  • 企业微信 模式需要本机或代理可接收平台事件回调

NapCat 项目：

安装与初始化

npm install
Copy-Item .env.example .env

至少需要配置：

  • BOT_PLATFORM
  • 你准备远程操作的 IDE 对应 *_LAUNCH_COMMAND

按平台至少再补充：

  • napcat: NAPCAT_TOKEN、NAPCAT_START_SCRIPT、QQ_USER_ID
  • telegram: TELEGRAM_BOT_TOKEN、TELEGRAM_CHAT_ID
  • feishu: FEISHU_APP_ID、FEISHU_APP_SECRET、FEISHU_OPEN_ID
  • wecom: WECOM_CORP_ID、WECOM_CORP_SECRET、WECOM_AGENT_ID、WECOM_USER_ID、WECOM_TOKEN、WECOM_ENCODING_AES_KEY

飞书配置

当前飞书接入方式已经调整为长连接，不再使用本地 webhook。

在飞书开放平台侧至少需要完成：

  1. 创建企业自建应用，并启用机器人能力
  2. 为应用开通接收消息所需权限
  3. 在“事件与回调”里把订阅方式切换为“使用长连接接收事件”
  4. 订阅事件 im.message.receive_v1
  5. 把机器人添加到可用范围，确保你自己可以给它发私聊消息
  6. 获取自己的 open_id，写入 FEISHU_OPEN_ID

项目侧只需要保留这些飞书变量：

  • FEISHU_APP_ID
  • FEISHU_APP_SECRET
  • FEISHU_OPEN_ID
  • FEISHU_RECEIVE_ID_TYPE
  • FEISHU_API_BASE_URL

不再需要配置飞书 webhook 地址、端口、路径或 verification token。

启动方式

推荐通过 portmux 启动，这样本地监听端口会跟当前项目自动绑定，避免和系统保留端口或其他项目冲突：

portmux start

如果本机还没有把 portmux 放进 PATH，也可以直接：

cargo run --manifest-path E:\_workSpace\PortManager\Cargo.toml -- start

只启动转发服务：

startup/start-app.bat

按平台启动：

startup/start-qq.bat
startup/start-telegram.bat
startup/start-feishu.bat
startup/start-wecom.bat

说明：

  • startup/start-qq.bat 会先启动 NapCat，再启动转发服务
  • 其他平台脚本只启动转发服务，并在脚本内设置对应 BOT_PLATFORM

开发模式：

npm run dev

托盘程序（可选）

.\start-tray.bat

说明：

  • 首次运行会先执行 scripts/build-tray-app.ps1，编译生成 tray/bin/FakeClaw.Tray.exe
  • 托盘程序会在后台拉起 portmux start，并通过 portmux 已分配的本地管理接口读取状态
  • 托盘菜单支持查看状态、暂停通知、恢复通知、重启服务、打开配置面板和退出
  • 双击托盘图标可打开配置窗口；点击“保存并应用”后会自动重启服务，使新的 .env 配置立即生效
  • 当前平台为 napcat 时，托盘启动服务前会尝试按 NAPCAT_START_SCRIPT 拉起 NapCat

环境变量

以下变量以 .env.example 为准。

核心连接

  • BOT_PLATFORM: 当前消息平台，支持 napcat | telegram | feishu | wecom
  • BOT_NAME: 通用机器人显示名，未单独配置平台名称时作为回退

QQ / NapCat

  • QQ_BOT_NAME: QQ / NapCat 机器人显示名，未配置时回退到 BOT_NAME
  • NAPCAT_WS_URL: NapCat WebSocket 地址，默认 ws://127.0.0.1:3001
  • NAPCAT_TOKEN: NapCat WebSocket token
  • NAPCAT_START_SCRIPT: 本机 NapCat 启动脚本路径
  • QQ_USER_ID: 唯一允许执行远程命令、同时接收通知的 QQ 账号

Telegram

  • TELEGRAM_BOT_NAME: Telegram 机器人显示名，未配置时回退到 BOT_NAME
  • TELEGRAM_BOT_TOKEN: Telegram Bot Token
  • TELEGRAM_CHAT_ID: 唯一允许执行远程命令、同时接收通知的私聊 Chat ID
  • TELEGRAM_API_BASE_URL: Telegram Bot API 地址，默认 https://api.telegram.org
  • TELEGRAM_POLL_TIMEOUT_SECONDS: 长轮询超时时间，默认 20

飞书

  • FEISHU_BOT_NAME: 飞书机器人显示名，未配置时回退到 BOT_NAME
  • FEISHU_APP_ID
  • FEISHU_APP_SECRET
  • FEISHU_OPEN_ID: 唯一允许执行远程命令、同时接收通知的目标用户
  • FEISHU_RECEIVE_ID_TYPE: 默认 open_id
  • FEISHU_API_BASE_URL: 默认 https://open.feishu.cn
  • 飞书当前使用长连接收事件，不需要配置本地 webhook 或 verification token

企业微信

  • WECOM_BOT_NAME: 企业微信机器人显示名，未配置时回退到 BOT_NAME
  • WECOM_CORP_ID
  • WECOM_CORP_SECRET
  • WECOM_AGENT_ID
  • WECOM_USER_ID: 唯一允许执行远程命令、同时接收通知的企业微信用户
  • WECOM_TOKEN: 回调验签 token
  • WECOM_ENCODING_AES_KEY: 回调消息解密密钥
  • WECOM_WEBHOOK_HOST: 本地事件监听地址，默认 127.0.0.1
  • WECOM_WEBHOOK_PORT: 企业微信本地事件监听端口；未显式配置时默认等于 ADMIN_CONTROL_PORT + 2
  • WECOM_WEBHOOK_PORT_OFFSET: 当 WECOM_WEBHOOK_PORT 未显式配置时，默认偏移量为 2
  • WECOM_WEBHOOK_PATH: 默认 /wecom/events
  • WECOM_API_BASE_URL: 默认 https://qyapi.weixin.qq.com

通知过滤

  • NOTIFY_SOURCE_ALLOWLIST: 允许转发的通知来源，默认包含 Code, Cursor, Windsurf, Trae, Kiro, CodeBuddy, Antigravity, JetBrains, Zed, Codex, PowerShell
  • NOTIFY_POLL_INTERVAL_MS: 桌面通知轮询间隔，默认 1500
  • NOTIFY_FILTER_MODE
  • NOTIFY_KEYWORDS

本地管理接口

  • ADMIN_CONTROL_HOST: 本地管理接口监听地址，默认 127.0.0.1
  • ADMIN_CONTROL_PORT: 本地管理接口端口；若通过 portmux 启动，会优先使用分配到的 PORT

说明：

  • 主要供托盘程序读取 /admin/status 并执行暂停/恢复通知等本地控制
  • 建议保持为本机回环地址，不要暴露到公网

远程启动命令

  • CODEX_LAUNCH_COMMAND
  • VSCODE_LAUNCH_COMMAND
  • CURSOR_LAUNCH_COMMAND
  • TRAE_LAUNCH_COMMAND
  • TRAE_CN_LAUNCH_COMMAND
  • CODEBUDDY_LAUNCH_COMMAND
  • CODEBUDDY_CN_LAUNCH_COMMAND
  • ANTIGRAVITY_LAUNCH_COMMAND

如果某个 IDE 的 open 拉不起来，优先把本机可执行路径或启动命令写到对应变量里。

自动化与截图

  • AUTOMATION_TIMEOUT_MS: 单次自动化超时，默认 30000
  • KEEP_DISPLAY_AWAKE: 是否定时发送保活避免显示器自动黑屏，默认 true
  • KEEP_DISPLAY_AWAKE_INTERVAL_SECONDS: 保活心跳间隔秒数，默认 30
  • SCREENSHOT_DIR: 截图输出目录
  • SCREENSHOT_RETENTION: 截图保留数量
  • SCREENSHOT_AFTER_ACTION_DELAY_MS: 粘贴/发送后到截图前的等待时间

校准页

  • CALIBRATION_WEB_ENABLED: 是否启用本地校准页，默认启用
  • CALIBRATION_WEB_HOST: 校准页监听地址，默认 127.0.0.1
  • CALIBRATION_WEB_PORT: 校准页端口；未显式配置时默认等于 ADMIN_CONTROL_PORT + 1
  • CALIBRATION_WEB_PORT_OFFSET: 当 CALIBRATION_WEB_PORT 未显式配置时，默认偏移量为 1

远程命令

只有当前平台授权用户发来的私聊文本命令会被执行：

  • napcat: QQ_USER_ID
  • telegram: TELEGRAM_CHAT_ID
  • feishu: FEISHU_OPEN_ID
  • wecom: WECOM_USER_ID

通用命令

  • ping
  • /status
  • /help
  • /shot
  • 暂停通知
  • 恢复通知

也支持中文入口：

  • 菜单
  • 状态

IDE 远程操作模式

可远程操作的目标为：

  • codex
  • vscode
  • cursor
  • trae
  • traecn
  • codebuddy
  • codebuddycn
  • antigravity

命令模式统一为：

/<target> <prompt>
/<target> nc <prompt>
/<target> send <prompt>
/<target> paste <prompt>
/<target> open
/<target> focus
/<target> minimize
/<target> screenshot

规则说明：

  • /<target> <prompt> 等同于 /<target> send <prompt>
  • send 会粘贴并发送
  • send 成功后默认会自动最小化目标 IDE
  • 如需发送后保留窗口，可用 /<target> nc <prompt> 或 /<target> send nc <prompt>
  • paste 只粘贴，不自动回车
  • open 用于拉起目标 IDE
  • focus 会切到目标窗口，并尝试命中聊天输入区
  • minimize 只最小化目标 IDE
  • screenshot 会先打开或激活目标 IDE，再回传截图
  • /shot 仍然只回传当前桌面截图

常用示例：

/codex 帮我检查最近一次改动的风险
/codex nc 帮我检查最近一次改动的风险
/vscode open
/cursor open
/trae paste 先别发送，我要手动确认
/antigravity screenshot

快速回复

  • 当机器人刚转发一条支持远程操作的 IDE 通知后，授权用户发来的下一条非命令私聊会直接按 send 发送到该 IDE
  • 当前支持快速回复的通知来源为 Codex、Code（映射到 vscode）、Cursor、Trae、CodeBuddy、Antigravity
  • 保留指令集仍优先按原逻辑处理，不会被快速回复接管，包括 ping、菜单、/help、/status、/shot、暂停通知、恢复通知 和所有 /<target> ... 命令
  • 快速回复是一次性的；无论下一条消息是命令还是非命令，都会消耗这次目标记忆，只是只有非命令消息才会真正发送到刚才那条通知对应的 IDE

校准与兼容性

桌面自动化依赖窗口布局和输入框定位。只要你改了 IDE 面板布局、缩放、侧边栏位置，优先校准，不建议直接改脚本。

本地校准网页

项目启动后可访问：

http://127.0.0.1:<ADMIN_CONTROL_PORT + 1>/calibration/

校准页支持：

  • Analyze 当前目标窗口
  • 预览候选输入区
  • 试跑 focus / paste
  • 保存草稿配置回正式配置文件

配置文件

这个文件适合调整：

  • 输入区的大致区域比例
  • 输入框尺寸阈值
  • 特定 IDE 的 composerSearch
  • 坐标兜底用的 clickFallback

批处理入口

startup/calibrate-desktop-automation.bat
startup/calibrate-desktop-automation.bat antigravity calibrate y

PowerShell 脚本入口

powershell -File .\scripts\calibrate-desktop-automation.ps1 -TargetApp codex -Mode analyze
powershell -File .\scripts\calibrate-desktop-automation.ps1 -TargetApp vscode -Mode analyze
powershell -File .\scripts\calibrate-desktop-automation.ps1 -TargetApp cursor -Mode calibrate
powershell -File .\scripts\calibrate-desktop-automation.ps1 -TargetApp trae -Mode analyze
powershell -File .\scripts\calibrate-desktop-automation.ps1 -TargetApp traecn -Mode calibrate
powershell -File .\scripts\calibrate-desktop-automation.ps1 -TargetApp codebuddy -Mode analyze
powershell -File .\scripts\calibrate-desktop-automation.ps1 -TargetApp codebuddycn -Mode calibrate
powershell -File .\scripts\calibrate-desktop-automation.ps1 -TargetApp antigravity -Mode analyze

说明：

  • analyze 只扫描当前窗口，输出候选输入区和推断配置
  • calibrate 会把推断出的 composerSearch 写回配置文件
  • -TargetApp 可用值：codex|vscode|cursor|trae|traecn|codebuddy|codebuddycn|antigravity
  • 应用尚未打开时，可配合 -OpenIfMissing -LaunchCommand <命令> 使用

兼容性建议

  • Codex: 相对稳定，默认优先匹配底部编辑器容器
  • VS Code / Cursor / Trae / Trae CN / Antigravity: 可用，但依赖聊天面板仍位于窗口右下区域，建议校准后使用
  • CodeBuddy / CodeBuddy CN: 适配一般，除了候选匹配还依赖坐标兜底点击，建议保守使用

安全说明

  • 不要提交真实 .env
  • 不要把各平台 token、app secret、用户 ID 或本机绝对路径写死进代码
  • 如果凭据已泄露，先在对应平台侧轮换后再继续使用

About

Windows NapCat QQ notification forwarder

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages