CaptchaMesh 是一个开源的人工接管工具，给个人、低频的使用场景用。电脑端保留原来的浏览器会话， 把挑战端到端加密后交给 Android；你在手机上手动完成，结果回到原任务，Agent 接着跑。
| 手动验证控制台 | 连接自检 | 脱敏运行记录 |
|---|---|---|
 |
 |
 |
flowchart LR
A[模式一：电脑 Agent] -->|2Captcha API| B[127.0.0.1 本地桥]
P[模式二：手机点工作流] -->|固定白名单 ID| N[电脑 Node Agent]
N --> A
B -->|端到端密文| H[不可信 Hub]
H -->|密文| P
P --> U[用户手动完成]
U -->|加密结果| H --> B --> A
| 模式 | 谁先启动 | 是否需要手机点工作流 | 用途 |
|---|---|---|---|
| Agent API（默认） | 电脑 Agent | 否 | 已有 Agent 遇到 CAPTCHA 后自动通知手机 |
| 手机工作流（可选） | 手机用户 | 是 | 从手机启动电脑预先登记的固定脚本，再等待它提交 CAPTCHA |
默认模式跑一下 captchamesh start，扫码配对一次就好。Agent 那边调用
http://127.0.0.1:8893 之后，任务会自动到手机上；不用先打开手机的“工作流”页，也不需要活动 run。
只有想“从手机启动电脑脚本”时，才需要配 registrations.json 和 node_agent.py。脚本里照常写
你自己的业务逻辑；CaptchaMesh 仍然只管启动、状态和人工 CAPTCHA 回传。
从 Releases 下载最新 APK，系统要求 Android 10（API 29）以上。首次启动记得允许通知和前台服务权限。 “设置 → 任务提醒”管着两种模式下的 CAPTCHA 到达弹窗；系统声音、震动和通知渠道也从这一页 进 Android 设置改。
从 0.18.x 测试版升到 0.19.0 要先卸掉旧的 debug 签名 APK，装上正式 APK 后重新扫码配对。
签名只迁移这一次：0.19.0 起用固定发布证书，之后直接覆盖安装即可。
电脑端目前只在 Linux 上正式支持，要求 Python 3.11+：
git clone https://github.com/vimalinx/CaptchaMesh.git
cd CaptchaMesh
./install.sh
captchamesh start./install.sh 会把电脑端 CLI 和 captchamesh-adapter Agent Skill 一起装好。Skill 默认装在
${CODEX_HOME:-~/.codex}/skills/captchamesh-adapter，想确认随时可以看：
captchamesh skill status装完之后可以这样确认 Skill 文件确实进了 Codex 的全局目录：
captchamesh skill status
test -f "${CODEX_HOME:-$HOME/.codex}/skills/captchamesh-adapter/SKILL.md" \
&& echo "CaptchaMesh Skill ready"然后开一个新的 Codex 会话，在要接入 CaptchaMesh 的项目目录里输入：
$captchamesh-adapter 检查当前项目的 2captcha-python 接入，使用 Agent API 模式，
把 endpoint 改到本机 CaptchaMesh 并验证，但不要读取或输出真实密钥。
Skill 是全局安装的，但只处理当前会话里你明确指定的项目和任务；不会自动上传到 OpenAI 云端，不会绕过项目授权，也不会在后台跑 CAPTCHA 任务。
也可以在任意项目目录里直接跑安装包自带的检查器，项目里不需要有 .skill/ 目录：
captchamesh skill inspect . --mode agent-api --json重复跑安装器没问题：没动过的 Skill 会正常更新；一旦发现你自己改过 Skill，或者目标目录
不归 CaptchaMesh 管，它会停下来保留原样，不做静默覆盖。从 wheel 安装的用户可以执行
captchamesh skill install 来做这一步。
程序只监听 127.0.0.1:8893。在交互终端里打开打印出来的配对地址，用 App 扫码即可。
服务管理器这类非交互环境不会把配对令牌写进日志，而是给出一个权限 0600 的本机文件路径。
已经在用 2captcha-python 的代码不用改调用方式，换个导入就行：
from captchamesh import TwoCaptcha
solver = TwoCaptcha()
result = solver.turnstile(
sitekey="PUBLIC_SITE_KEY",
url="https://example.com/",
)其他 2Captcha v1/v2 客户端把 API 地址改成 http://127.0.0.1:8893 就行。
captchamesh config --json 默认只返回 API 地址和受限 Key 文件路径，不显示 Key。
配对、连接或任务出错时，可以看脱敏诊断：
captchamesh logs
captchamesh logs --clear诊断文件在 CaptchaMesh 本机状态目录里，权限 0600，上限 256 KiB；只记固定事件、异常类型和
代码位置。异常消息、Key、Token、Cookie、网址、任务内容一概不进。
详细接入方法见 电脑端本地桥 和 2Captcha API 兼容说明。
| 类型 | 手机交互 | 说明 |
|---|---|---|
| 图片文字 | 原生输入 | 支持文本、数字和常用约束 |
| 坐标点击 | 原生画布 | 返回一个或多个点击坐标 |
| 图片网格 | 原生网格 | 返回选中的图片序号 |
| 旋转题 | 原生旋钮 | 返回角度 |
| Turnstile / hCaptcha / reCAPTCHA | 挑战组件 | 保留同一任务所需上下文 |
| FunCaptcha / GeeTest | 挑战组件 | 支持对应 v2 任务映射 |
| DataDome | 挑战组件 | 要求匹配的代理和 User-Agent |
| Amazon WAF | 挑战组件 | 支持 jsapiScript 或双脚本模式 |
任务的上下文可以带上同一次操作需要的 Cookie、User-Agent、请求头、localStorage 和无鉴权 HTTP(S) 代理。字段定义、结果格式和明确不支持的部分见 兼容能力矩阵。
CAPTCHA token 通常绑着浏览器状态、网络出口和短期上下文，所以中间要有电脑端桥，它负责：
- 不动 Agent 原来的浏览器和业务流程；
- 任务格式转换和端到端加密都在本机完成；
- 提供常用的 2Captcha API v1/v2 兼容端点；
- 同时接多个 Agent 任务并持久跟踪，手机任务列表里直接点选切换；切回原生图片任务时，已输入的答案、坐标、格子或角度都还在，回传按
taskId隔离； - 结果只在本机数据库里短期保存，权限
0600。
Hub 只转发密文和必要的路由元数据；配对密钥只存在电脑和 Android Keystore 里。
网页挑战共用 Android WebView 的 Cookie 和代理环境，一次只能开一个；处理网页挑战期间，仍可切去看已经打开的原生图片任务。
先备好 Python 3.11+、JDK 17 和 Android SDK 35，然后运行：
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt build bandit pip-audit
./tools/test_all.sh如果装了 Gitleaks，还可以再跑完整安全门：
./tools/test_all.sh --security脚本会依次验证 Python 协议与安全回归、发布包边界、安装后的命令行、依赖漏洞、Android 单测/Lint/APK 构建，外加可选的 Git 历史密钥扫描。人工端到端、无线 ADB、通知和 Hub 部署 测试在完整测试指南。
每次 push 和 pull request，GitHub Actions 也会把 Python 3.11、Python 3.14 和 Android 各测一遍。
cd app-src
./gradlew --no-daemon :app:testDebugUnitTest :app:lintDebug :app:assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk开发时可以走 USB 或无线 ADB：
adb reverse tcp:8890 tcp:8890日常使用用不上 ADB，推荐电脑端生成的一次性二维码，详见 Android 安装与连接。
碰到崩溃、后台断连或任务失败，打开 App 的“记录”页点“复制诊断”。复制出来的只有 版本、异常类型和 CaptchaMesh 自己的栈帧，可以直接贴到私有 Issue；Key、Token、 Cookie、网址和任务内容都不在里面。完整排查步骤见Android 安装与连接。
cp registrations.example.json registrations.json在本机 registrations.json 里登记固定的 cwd 和命令数组；这个文件不进 Git，手机那边也只能
选到登记过的 id。node_agent.py 跑起来之后，手机“工作流”页可以启动、查看、停止这些脚本。
脚本碰到 CAPTCHA 时，走的还是同一个手机人工验证界面。接入方式见
两种模式与工作流接入，协议和失败语义在
工作流节点协议。
| 组件 | 状态 | 最低环境 |
|---|---|---|
| Android App | 支持 | Android 10 / API 29 |
| Linux 电脑端 | 支持 | Python 3.11+ |
| Linux Hub | 支持 | Ubuntu、systemd、HTTPS 隧道 |
| macOS 电脑端 | 实验性 | Python 3.11+，尚未纳入 CI |
| Windows / WSL | 未验证 | 原生 Windows 暂不支持 |
| iOS | 不支持 | 暂无客户端 |
Hub 只应该监听 127.0.0.1，对外走 HTTPS 反向隧道；别把 8890 直接暴露到公网。
从 Releases 下载独立 Hub 包，在 Ubuntu 或
Debian 服务器上跑下面这一条命令，安装器会问你要域名和 Cloudflare Tunnel token：
sudo ./deploy/hub/install.sh --domain mesh.example.com依赖安装、隔离账户、生成 Key、systemd 服务和 /healthz 检查都是它自己来；再跑一遍就是
保留数据的升级。完整步骤、非交互安装和加密备份见 Hub 部署说明。
公益 Hub 解不了任务正文，但邮箱 ID、方向、时间、密文大小这些路由元数据它看得到。
- 配对能力令牌放在 URL fragment 里，不进 HTTP 请求路径，页面加载完就从地址栏清除。
- 本机状态目录
0700，密钥、数据库和非交互配对文件0600。 - 密钥文件拒绝符号链接、硬链接和其他非普通文件。
- 通知、普通日志、脱敏诊断和默认配置输出里没有 Key、Cookie、挑战正文或答案。
- 回调、SOCKS、带认证代理和任意远程命令，默认一律拒绝。
- 发布前 CI 会检查 wheel/sdist，见到本机文件、私有标记或异常归档成员直接判失败。
安全问题请通过 SECURITY.md 私下报告。CaptchaMesh 只该用在你有权运行的个人 工作流上，并且遵守目标服务的条款和适用法律。
| 文档 | 内容 |
|---|---|
| 完整测试指南 | 自动、人工、Android、Hub 和发布验收 |
| 电脑端本地桥 | 安装、配对、Agent 接入和生命周期 |
| Android 安装与连接 | APK、通知、二维码和 ADB |
| 端到端加密中继 | 信任模型、密钥和 Hub 可见信息 |
| 挑战协议 v3 | 任务字段和类型化结果 |
| 2Captcha 兼容层 | v1/v2 端点与题型矩阵 |
| 两种模式与工作流接入 | 默认 Agent API 与可选手机工作流的选择和接入 |
| 工作流节点协议 | 本机白名单工作流 |
有接入经验、兼容性反馈或使用建议，欢迎到 Linux.do 上聊。 也谢谢 Linux.do 给独立开发者和开源项目提供交流的地方。
| 路径 | 内容 |
|---|---|
app-src/ |
Android App 源码 |
captchamesh_cli.py / local_bridge.py |
电脑端命令行和本机桥 |
broker.py / broker_asgi.py |
Hub 与路由 |
relay_protocol.py |
端到端加密信封协议 |
challenge_protocol.py |
挑战与结果协议 |
twocaptcha_compat.py |
2Captcha API v1/v2 翻译层 |
node_agent.py |
可选的白名单工作流节点 |
.skill/captchamesh-adapter/ |
Agent 接入 Skill |
deploy/hub/ |
自托管 Hub 配置 |
想参与的话，贡献指南、社区行为准则和
支持说明都在这。当前版本 0.19.8，MIT License。