MySearch Proxy
MySearch Proxy 是一套给 AI 助手准备的统一搜索栈。
它把原本分散的 4 件事收成了同一个仓库：
mysearch/- 真正可安装的 MySearch MCP
skill/- 给 Codex / Claude Code 的 skill 与安装说明
openclaw/- 给 OpenClaw / ClawHub 的独立 skill bundle
proxy/- 给团队或公开部署使用的控制台与代理层
支持的搜索能力：
- Tavily
- Firecrawl
- Exa
- 可选 X / Social
目标很简单：
- 让本地 AI 助手先用起来
- 让 OpenClaw 直接装上去
- 让团队共享一套统一搜索后端
- 让调用方尽量少关心底层 provider 差异
项目入口：
- GitHub： skernelx/MySearch-Proxy
- Docker Hub： skernelx/mysearch-proxy
- ClawHub： clawhub.ai/skernelx/mysearch
为什么做这个项目
很多搜索类项目只解决其中一小段：
- 只给一个
web_search - 只会搜，不会抓正文
- 只会调官方 API，不方便接自建网关
- 只给 prompt，不给真正能安装的运行时
- 只做 key 面板，不解决 AI 如何调用
MySearch Proxy 选择直接把整条链补齐：
上游 provider / 聚合网关
-> Tavily / Firecrawl / Exa / X / Social
MySearch Proxy
-> 控制台、Token、额度同步、兼容代理接口
MySearch MCP / Codex Skill / OpenClaw Skill
-> 给 Codex、Claude Code、OpenClaw、其他 Agent 直接使用
推荐架构
当前最推荐的是 proxy-first：
上游 provider
-> MySearch Proxy
-> 生成 MySearch 通用 token
-> MySearch MCP / OpenClaw skill / 其他 Agent
这条路的好处很直接：
- 客户端只需要一组
MYSEARCH_PROXY_* - Tavily / Firecrawl / Exa 不再散落到每台机器
- 可以统一管理 token、调用统计和额度同步
- OpenClaw、本地 Codex、团队代理都能复用同一套配置
如果你暂时还没有 Proxy，也可以让 mysearch/ 或 openclaw/ 直接连官方
provider。
最新优化（v0.1.11）
这次版本重点是把 provider 健康状态从“只看有没有 key”升级成“能看出 key 是不是活着”，并把 docs / resource 路由对失效 provider 的自保补齐；上一版 config-first、Python 3.10 兼容和 Firecrawl 域名过滤回退继续保留。
-
配置入口收口：
MySearchruntime 现在会优先读取~/.codex/config.toml的mcp_servers.mysearch.env。install.sh会先继承宿主已注册的MYSEARCH_*，再用mysearch/.env只补缺省值。- OpenClaw wrapper 现在会优先读取
openclaw.json的skills.entries.mysearch.env。 .env继续支持，但明确只保留给本地单仓调试兜底，不再是推荐主路径。- 读取宿主 config 时不再强依赖 Python 3.11 的
tomllib，对 Python 3.10 会自动回退到轻量解析。
-
文档 / 资源类结果重排：
docs / github / pdf / resource / tutorial的 blended 结果现在会优先官方域名和官方文档路径。- 显式传了
include_domains时，会进一步把命中域名的结果稳定放到前面。 reddit / arxiv / researchgate / medium / youtube这类明显第三方页面不再轻易抢前几条。citations会跟随重排后的结果顺序，避免前排已经修正但引用顺序还是旧的。- Firecrawl 如果在
site:domain query这一跳返回空结果，会自动做一轮无site:的 Firecrawl 检索，再在客户端按域名过滤，优先把结果留在 Firecrawl 链路里，而不是立刻退回 Tavily。
-
Provider 健康检查与路由自保：
health现在除了available_keys，还会返回每个 provider 的live_status、live_error、last_checked_at。- 例如
Tavily key 已失效 / 被停用，现在会明确显示成auth_error，而不是只看起来像“有 key 可用”。 - docs / resource / balanced 路由会跳过
auth_error的 provider，不再把失效的 Tavily 当成发现阶段主路由。 - Firecrawl 的域名 fallback 也会跳过
auth_error的 Tavily，避免本来已经切开主路由，最后又在 fallback 阶段被 401 绊倒。
-
路由与参数稳定性：
- MCP 入口现在兼容单字符串形式的
sources、include_domains、formats等参数。 - 显式指定
provider时，不会再被balanced策略偷偷混成hybrid。
- MCP 入口现在兼容单字符串形式的
-
抓取质量修复：
extract_url(auto)现在会识别更多假正文，并按需回退。- 已覆盖
linux.doanti-bot 提示、验证码挑战页、GitHub blob 页面壳等场景。 - GitHub 公开仓库
blob页面在auto模式下会优先改写到 raw 地址直接抓正文。
-
社交结果一致性：
- 日期过滤后如果没有命中，
results / citations / answer会保持一致，不再残留旧内容。
- 日期过滤后如果没有命中，
-
Social / X fallback：
social/search现在支持主模型结果过少或上游报错时自动 fallback。- 返回里新增 元信息，能直接看到实际选中的模型、fallback 是否触发，以及每轮尝试结果数。
新增运行时参数：
MYSEARCH_MAX_PARALLEL_WORKERS=4
MYSEARCH_SEARCH_CACHE_TTL_SECONDS=30
MYSEARCH_EXTRACT_CACHE_TTL_SECONDS=300
说明：
- 终端里单次 CLI 调用通常是新进程，内存缓存不会跨进程复用。
- 常驻服务模式下缓存才会持续生效。
从哪里开始
按你的使用场景直接走：
- 只想让本机 Codex / Claude Code 先用起来： 看 mysearch/README.md
- 想让 AI 自动理解怎么安装和使用： 看 skill/README.md
- 想给 OpenClaw / ClawHub 安装独立搜索 skill： 看 openclaw/README.md
- 想部署控制台、管理 key / token / 额度： 看 proxy/README.md
5 分钟快速开始
路线 A：本机直接安装 MySearch MCP
cd /path/to/MySearch-Proxy
python3 -m venv venv
优先把配置直接放进宿主 config：
Codex：~/.codex/config.toml的mcp_servers.mysearch.envOpenClaw：openclaw.json的skills.entries.mysearch.env.env：只建议本地单仓调试时作为兜底
推荐最小配置：
MYSEARCH_PROXY_BASE_URL=https://your-mysearch-proxy.example.com
MYSEARCH_PROXY_API_KEY=mysp-...
安装：
./install.sh
install.sh 现在会优先继承宿主已有配置，再用 mysearch/.env 只补缺省值。
验收：
python3 skill/scripts/check_mysearch.py --health-only
python3 skill/scripts/check_mysearch.py --web-query "OpenAI latest announcements"
路线 B：先部署 Proxy，再让所有客户端复用
mkdir -p mysearch-proxy-data
docker run -d \
--name mysearch-proxy \
--restart unless-stopped \
-p 9874:9874 \
-e ADMIN_PASSWORD=change-me \
-v $(pwd)/mysearch-proxy-data:/app/data \
skernelx/mysearch-proxy:latest
部署后：
- 登录控制台
- 添加 Tavily / Firecrawl / Exa / Social 上游配置
- 创建 MySearch 通用 token
- 把这个 token 填给
mysearch/.env或 OpenClaw skill env
目录说明
mysearch/
真正可运行的 MCP 服务。
提供 4 个工具：
searchextract_urlresearchmysearch_health
支持：
stdiostreamableHTTPsse
详细说明见： mysearch/README.md
skill/
这层不是 MCP 实现，而是给 AI 助手看的安装与使用说明。
适合：
- Codex 自动安装
- Claude Code 按 README + SKILL 完成接线
详细说明见： skill/README.md
openclaw/
这是单独打包的 OpenClaw skill bundle。
特点：
- 自带 runtime
- 可本地安装
- 可发布到 ClawHub
- 推荐通过 skill env 注入
MYSEARCH_PROXY_*
详细说明见： openclaw/README.md
proxy/
这是整套系统的控制台与代理层。
负责：
- Provider key 池
- MySearch token 池
- 调用统计
- 官方额度同步
/social/search兼容入口
详细说明见： proxy/README.md
路由策略
MySearch 默认不是“所有问题都塞给一个 provider”。
当前推荐理解方式：
web / news- 优先 Tavily
docs / github / pdf / pricing / changelog- 优先 Firecrawl
- 普通网页补充发现
- 可回退 Exa
social- 走 xAI 或兼容
/social/search
- 走 xAI 或兼容
extract_url- 优先 Firecrawl，失败或正文为空时回退 Tavily extract
research- 先搜索，再抓取正文，再可选补 Social / X
适合哪些场景
- 本地开发助手的默认搜索入口
- OpenClaw 的默认搜索 skill
- 多个 Agent 共用的一套统一搜索后端
- 你已经有 Tavily / Firecrawl / xAI 上游，想统一收口
文档地图
- 总体架构： docs/mysearch-architecture.md
- MCP： mysearch/README.md
- OpenClaw： openclaw/README.md
- Proxy： proxy/README.md
- Codex / Claude Code skill： skill/README.md
当前公开页面
- Docker Hub： skernelx/mysearch-proxy
- ClawHub： clawhub.ai/skernelx/mysearch
下图是公开页面的历史截图，实时状态请以线上页面为准：
