1. 项目概述OnionClaw一个为AI智能体打开暗网大门的工具箱如果你是一名安全研究员、威胁情报分析师或者正在构建一个需要从暗网获取信息的AI智能体那么你肯定遇到过这样的困境如何让程序自动化、匿名地访问那些以.onion结尾的隐藏服务手动操作Tor浏览器不仅效率低下更无法集成到自动化的工作流中。这正是OnionClaw要解决的核心问题。它不是一个简单的Tor代理封装而是一个完整的、为AI智能体设计的暗网访问与情报收集工具包。简单来说OnionClaw赋予你的AI助手特别是基于OpenClaw框架的智能体七项关键能力检查Tor连接状态、切换匿名身份、探测暗网搜索引擎健康度、执行多引擎聚合搜索、抓取任意.onion页面内容、利用大语言模型LLM分析抓取到的情报以及一键运行从搜索到分析的完整调查流水线。它基于SICRY引擎构建集成了18个暗网搜索引擎和一套名为“Robin”的OSINT开源情报处理流程。你可以把它当作一个独立的命令行工具来用也可以无缝集成到OpenClaw中让你的AI智能体在对话中直接调用这些暗网能力。这个工具的价值在于它将原本复杂、手动的暗网调查工作变成了可编程、可扩展的自动化流程。对于防御性安全研究这意味着你能更快地发现数据泄露、监控勒索软件团伙的动态对于红队演练这意味着更高效的攻击面侦察。但正如其文档中毫不避讳地指出的这种“AI智能体 Tor网络 全自动化”的能力组合是一把极其锋利的双刃剑它在提升合法研究效率的同时也大幅降低了自动化恶意活动的技术门槛。理解这一点是负责任地使用OnionClaw的前提。2. 核心架构与设计思路拆解2.1 分层架构从命令行到暗网节点的清晰路径OnionClaw的设计非常模块化理解其架构有助于你更有效地使用和定制它。整个工具可以看作自上而下的四层结构第一层用户交互层这是你直接接触的部分包括七个独立的Python脚本check_tor.py,search.py等以及OpenClaw的技能接口。这一层负责解析你的命令参数并将任务分发给核心引擎。作为用户你大部分时间都在和这一层打交道。第二层命令封装层即各个.py脚本本身。它们的主要职责是参数处理、错误捕获和结果格式化如漂亮的终端输出或纯净的JSON。它们本身不包含复杂的网络或逻辑而是调用下一层的统一接口。第三层SICRY引擎层这是整个工具的“大脑”和“肌肉”所有繁重的工作都在sicry.py这个文件中完成。它由作者从另一个项目SICRY™中引入并捆绑。这一层实现了所有核心功能连接管理维护与Tor SOCKS5代理默认127.0.0.1:9050和控制端口9051的通信。搜索引擎集成管理那18个暗网搜索引擎的URL、解析规则和健康状态。智能处理包含查询优化、结果过滤、批量抓取和LLM分析等高级功能。状态持久化使用SQLite数据库来缓存搜索结果、记录引擎状态和管理监控任务。这避免了重复查询提升了效率。第四层Tor网络层这是实际的匿名通信层。OnionClaw通过SOCKS5协议将HTTP请求发送给本地Tor客户端由Tor网络通过三层中继节点路由到目标.onion服务或经过出口节点访问明网。renew.py脚本则通过Tor的控制协议向Tor进程发送信号来重建电路从而更换出口IP实现身份轮换。这种分层设计的好处是显而易见的功能核心高度内聚在sicry.py中易于维护和更新而上层的脚本可以根据不同使用场景CLI工具 vs. AI技能灵活定制互不干扰。2.2 双模式运行独立工具与AI技能的巧妙平衡OnionClaw提供了两种使用模式这体现了其设计的前瞻性1. 独立命令行工具模式这是最基础、最灵活的使用方式。你只需要Python环境和Tor就能在终端里执行所有调查命令。这种模式适合脚本化与集成将OnionClaw命令嵌入到你的自动化脚本或CI/CD流程中。快速验证与测试在集成到更复杂系统前快速测试某个.onion站点的可达性或某个搜索词的有效性。资源受限环境在没有部署OpenClaw的服务器或容器内运行。2. OpenClaw技能模式这是其作为“AI智能体工具”定位的集中体现。通过将整个OnionClaw目录复制到OpenClaw的技能文件夹AI智能体在会话中就能“理解”并调用暗网相关的指令。当用户提出“搜索暗网上关于X公司的数据泄露”或“检查这个.onion网站”时OpenClaw能自动关联并触发OnionClaw技能。注意技能模式依赖于OpenClaw的上下文理解能力。安装后你需要启动一个新的OpenClaw会话技能才会被加载。现有的会话不会自动识别新添加的技能。这种双模式设计确保了工具的普适性。研究人员可以从简单的CLI开始熟悉工作流而开发者则可以轻松地将其能力赋予AI智能体构建更强大的自动化调查系统。2.3 核心工作流Robin OSINT流水线解析pipeline.py脚本封装了名为“Robin”的完整OSINT流水线这是OnionClaw自动化能力的精髓。理解这个流水线的每一步你就能明白一次完整的调查背后发生了什么健康检查首先调用check_tor()确保Tor代理可用。这是所有后续操作的基础。引擎探测运行check_search_engines()快速测试所有18个搜索引擎的当前可用性。暗网服务极不稳定这一步能避免向已下线的引擎发送请求节省大量时间。查询优化使用LLM如果配置了将你输入的自然语言查询如“find recent ransomware attacks targeting hospitals in 2026”精炼成不超过5个关键词的搜索串如“ransomware hospital 2026”。暗网搜索引擎通常对简短关键词的反应更好。并行搜索使用上一步得到的关键词并发地向所有可用的搜索引擎发起搜索请求。结果会自动去重合并成一个统一的列表。结果过滤再次利用LLM对上一步得到的所有结果可能是几十上百条进行相关性排序筛选出最相关的20条数量可配置。这步至关重要它模拟了分析师从海量结果中快速定位高价值信息的过程。批量抓取并发地抓取过滤后结果中每个URL的页面内容。OnionClaw会处理Tor网络带来的延迟和连接不稳定性。情报分析将抓取到的所有文本内容汇总送入LLM并按照你指定的分析模式如ransomware模式生成结构化的OSINT报告。这个流水线的巧妙之处在于它的优雅降级。即使你没有配置LLM API密钥第3、5、7步也会被跳过工具仍然可以完成Tor检查、引擎探测、搜索和抓取这些核心功能并将原始结果输出给你。这保证了工具在只有Tor的基础环境下依然可用。3. 环境配置与核心工具实操详解3.1 Tor服务的安装与深度配置OnionClaw的命脉是Tor。仅仅apt install tor可能不够尤其是你需要使用renew.py进行身份轮换时。基础安装仅SOCKS5代理对于大多数Linux发行版安装系统包管理器提供的Tor即可。安装后Tor服务通常会自行启动并在后台运行监听9050端口。sudo apt update sudo apt install tor # 检查服务状态 sudo systemctl status tor # 如果未运行则启动 sudo systemctl start tor这种方式简单但通常默认配置只开启SOCKS5代理9050端口没有开启控制端口因此renew.py命令将无法工作。高级配置启用控制端口为了使用身份轮换功能你需要让Tor开启控制端口并启用Cookie认证。最安全便捷的方式是创建一个自定义的Tor配置临时运行不与系统Tor服务冲突。# 创建一个临时目录存放Tor数据 mkdir -p /tmp/onionclaw_tor_data # 创建自定义配置文件 cat /tmp/onionclaw_torrc EOF SocksPort 9050 ControlPort 9051 CookieAuthentication 1 DataDirectory /tmp/onionclaw_tor_data EOF # 使用自定义配置启动Tor进程 tor -f /tmp/onionclaw_torrc 这段配置做了三件事1) 在9050端口提供SOCKS5代理2) 在9051端口开启控制接口3) 使用Cookie认证无需密码4) 将数据目录指向一个临时位置。启动后你需要在OnionClaw的.env文件中设置TOR_DATA_DIR/tmp/onionclaw_tor_data这样renew.py才能找到认证Cookie。实操心得我强烈建议使用这种自定义配置的方式而不是修改系统Tor的配置。这样做有几个好处一是完全独立不会影响系统其他可能依赖Tor的服务二是权限清晰数据目录你可以完全控制三是关闭方便直接pkill -f “tor -f /tmp/onionclaw_torrc”即可不留痕迹。3.2 Python依赖与项目初始化OnionClaw的Python依赖相对轻量。除了基本的requests库关键依赖是requests[socks]支持SOCKS5代理的扩展和stemTor控制协议库。# 进入项目目录 cd OnionClaw # 安装依赖建议使用虚拟环境 pip install requests[socks] beautifulsoup4 python-dotenv stem接下来是配置环境变量。.env文件是控制OnionClaw行为的关键。# 复制示例配置文件 cp .env.example .env # 编辑配置文件 nano .env你的.env文件至少需要配置Tor部分。一个最小化的配置如下TOR_SOCKS_HOST127.0.0.1 TOR_SOCKS_PORT9050 TOR_CONTROL_HOST127.0.0.1 TOR_CONTROL_PORT9051 TOR_DATA_DIR/tmp/onionclaw_tor_data # 必须与你启动Tor时设置的DataDirectory一致如果你打算使用ask.py或pipeline.py的分析功能还需要配置LLM。例如使用OpenAILLM_PROVIDERopenai OPENAI_API_KEYsk-your-api-key-here或者为了完全本地化且免费可以使用Ollama需先本地安装并运行Ollama服务LLM_PROVIDERollama OLLAMA_MODELllama3.2 # 或其他你本地部署的模型3.3 七大命令实战指南与避坑要点1.check_tor.py- 连接健康诊断这是你的“点火开关”。在任何操作前先运行它。python3 check_tor.py如果看到✓ Tor active和你的出口IP说明一切正常。如果失败首先检查Tor进程是否在运行以及TOR_SOCKS_PORT是否与Tor实际监听的端口一致。常见错误是防火墙阻止了本地回环地址的通信或者有其他程序占用了9050端口。2.renew.py- 匿名身份切换器这个命令通过向Tor控制端口发送NEWNYM信号让你获得一个新的出口IP。这在长时间爬取或需要避免被目标站点关联时非常有用。python3 renew.py注意事项NEWNYM信号并不会立即让你所有现有连接使用新电路。Tor会为新连接使用新电路。对于已经建立的连接比如一个长时间的下载可能仍会使用旧电路。最彻底的方式是重启Tor进程但renew.py在大多数场景下已足够。3.check_engines.py- 搜索引擎探针暗网搜索引擎的可用性变化莫测。这个命令会逐一ping通那18个引擎并给出延迟和状态。python3 check_engines.py输出会以清晰的表格显示哪些引擎是活的哪些超时了。在进行大规模搜索前运行此命令并记下ALIVE的引擎名称。你可以将这些名称用于search.py的--engines参数以提升搜索效率和成功率。# 使用缓存结果避免每次等待 python3 check_engines.py --cached 10 # 如果10分钟内有缓存则直接使用4.search.py- 多引擎聚合搜索这是信息收集的起点。其强大之处在于并发查询和自动去重。# 基本搜索 python3 search.py --query bitcoin mixer review 2026 # 使用特定引擎更快更稳 python3 search.py --query credential dump --engines Ahmia Tor66 Ahmia-clearnet # 限制结果数量 python3 search.py --query 某公司 data breach --max 25核心技巧暗网搜索引擎的索引质量和语法支持远不如Google。使用简短、精准的关键词组合避免自然语言长句。例如用“ransomware healthcare leak”而非“I want to find information about recent ransomware leaks in the healthcare sector”。组合2-4个关键词通常效果最佳。5.fetch.py- 页面内容抓取器获得URL后你需要获取实际内容。fetch.py会通过Tor网络获取页面并提取标题、正文文本和链接。python3 fetch.py --url http://example.onion # 提取页面中的所有链接用于深度爬取 python3 fetch.py --url http://example.onion --links # 仅输出JSON格式便于管道传递 python3 fetch.py --url http://example.onion --json如果返回的status是0通常意味着该.onion服务当前无法访问下线、不稳定或屏蔽了你的出口节点。可以尝试过段时间再试或者使用renew.py更换出口节点后重试。6.ask.py- LLM情报分析员这是将原始数据转化为情报的关键一步。你需要为它提供文本内容直接输入或从文件读取并指定分析模式。# 分析抓取到的文本文件 python3 ask.py --query LockBit --mode ransomware --file ./scraped_data.txt # 使用自定义分析指令 python3 ask.py --query cryptocurrency theft --mode threat_intel --content $(cat data.txt) --custom 重点分析提到的钱包地址和交易模式四种分析模式threat_intel,ransomware,personal_identity,corporate预设了不同的分析框架和输出结构能极大提升报告的相关性。7.pipeline.py- 全自动调查流水线这是终极武器将上述所有步骤串联起来。python3 pipeline.py --query 某科技公司 source code leak --mode corporate --out ./investigation_report.md运行后你可以泡杯咖啡等待它自动完成从搜索到生成Markdown报告的全过程。--scrape参数控制抓取页面的并发数网络状况不好时可以调低如--scrape 5。--clear-cache参数可以强制忽略之前缓存的搜索结果和页面内容获取最新数据。4. 典型应用场景与实战流程4.1 场景一企业数据泄露监控自动化日常任务假设你负责某公司“Acme Corp.”的安全监控需要定期检查是否有公司凭证或源代码在暗网上被交易或泄露。手动单次调查流程# 1. 启动独立Tor实例避免干扰系统Tor mkdir -p /tmp/acme_tor_data tor -f (echo -e SocksPort 9052\nControlPort 9053\nCookieAuthentication 1\nDataDirectory /tmp/acme_tor_data) # 2. 配置OnionClaw使用这个新实例 export TOR_SOCKS_PORT9052 export TOR_CONTROL_PORT9053 export TOR_DATA_DIR/tmp/acme_tor_data # 3. 运行完整流水线调查 python3 pipeline.py \ --query Acme Corp password credential source code internal \ --mode corporate \ --max 50 \ --scrape 8 \ --out ./reports/acme_monitor_$(date %Y%m%d).md这个流程会生成一份包含来源链接、泄露资产类型、威胁行为体活动和业务影响评估的结构化报告。自动化与调度你可以将上述命令写入一个Shell脚本并使用cron定时任务如每天凌晨3点执行。为了更隐蔽可以在脚本开头随机睡眠几分钟并确保每次执行后使用renew.py或重启Tor来更换IP。生成的报告可以通过邮件或消息机器人发送给安全团队。4.2 场景二勒索软件事件应急响应在发生勒索软件攻击事件后安全团队需要快速了解攻击者背景、勒索金额、已公布的其他受害者等信息以评估威胁和制定策略。针对性情报收集流程# 1. 快速健康检查 python3 check_tor.py python3 check_engines.py --cached 5 # 2. 针对特定勒索软件团伙进行搜索例如LockBit python3 search.py \ --query LockBit ransomware 2026 victim list data \ --engines Ahmia Tor66 Ahmia-clearnet \ --max 30 ./lockbit_urls.json # 3. 手动筛选高价值URL并抓取假设从结果中选择了3个URL python3 fetch.py --url http://lockbit_leak_site.onion/victims --json victim_page.json python3 fetch.py --url http://lockbit_blog.onion --json blog_page.json # 4. 合并内容并进行深度分析 cat victim_page.json blog_page.json | jq -r .text combined_content.txt python3 ask.py \ --query LockBit ransomware group latest activities and TTPs \ --mode ransomware \ --file combined_content.txt \ --custom 提取所有提到的MITRE ATTCK战术与技术、勒索金额要求、受害者行业、可能的C2基础设施这个流程结合了自动化搜索和人工筛选在保证覆盖面的同时能对关键信息进行更聚焦、更深入的LLM分析快速产出可用于威胁猎杀和IoC威胁指标提取的情报。4.3 场景三个人数字足迹与隐私暴露检查个人可以出于隐私保护目的检查自己的邮箱、用户名、手机号等是否出现在暗网的泄露数据或讨论中。隐私检查流程需格外注意法律与道德边界# 使用个人身份模式该模式会特别关注PII个人身份信息 python3 pipeline.py \ --query john.doeexample.com my_username 1234567890 \ --mode personal_identity \ --scrape 5 \ --max 20重要警告此场景极具敏感性。务必确保1) 你查询的是自己的信息2) 你所在的国家/地区允许此类出于个人安全目的的调查3) 妥善处理并最终删除任何包含他人PII的查询结果。OnionClaw只是一个工具使用它进行未经授权的他人信息搜集可能构成违法。结果解读personal_identity模式的报告会包含“暴露风险评估”部分对发现的信息进行风险分级如高、中、低并给出建议如更改相关密码、启用双因素认证等。5. 高级配置、问题排查与性能调优5.1 性能优化启用Tor连接池默认情况下所有请求都通过单一的Tor SOCKS5代理9050端口。在进行并发搜索或批量抓取时这可能会成为瓶颈。SICRY引擎支持TorPool模式可以启动多个Tor进程每个进程使用不同的SOCKS端口从而实现真正的并发。配置与启用TorPool在.env文件中设置池大小SICRY_POOL_SIZE3 # 建议2-4根据你的CPU和内存资源调整OnionClaw在启动需要并发的任务如pipeline.py中的批量抓取时会自动根据SICRY_POOL_SIZE的值在后台启动多个Tor实例端口号从9050开始递增如9050, 9052, 9054...。请求会被均匀地分配到池中的各个Tor实例每个实例有独立的电路和出口IP。这不仅能提升吞吐量还能进一步增强匿名性因为你的请求来自多个不同的出口节点。注意事项每个Tor实例会消耗约50-150MB内存。设置过大的SICRY_POOL_SIZE可能导致内存不足。建议在性能测试后确定合适的数值。此外频繁创建销毁连接池会增加开销对于长时间运行的后台监控任务保持一个稳定的池更为高效。5.2 常见问题与故障排除手册即使配置正确由于暗网和Tor网络本身的特性你仍会遇到各种问题。下面是一个快速排查指南问题现象可能原因解决方案check_tor.py返回✗ Tor NOT active1. Tor进程未运行。2. 防火墙/安全软件阻止。3..env中SOCKS端口配置错误。1. 运行pgrep tor或sudo systemctl status tor检查。2. 临时关闭防火墙测试或检查规则。3. 确认TOR_SOCKS_PORT与Tor实际监听端口一致 (ss -tlnp | grep :9050)。renew.py返回success: false1. Tor控制端口未开启。2. Cookie认证失败TOR_DATA_DIR路径错误。3. 使用了密码认证但未配置。1. 确保Tor配置中包含ControlPort 9051和CookieAuthentication 1。2. 检查.env中TOR_DATA_DIR是否指向Tor进程使用的DataDirectory。3. 如果使用HashedControlPassword需在.env中设置TOR_CONTROL_PASSWORD。search.py返回结果很少或为空1. 搜索引擎大面积宕机。2. 查询关键词过于宽泛或冷门。3. 网络延迟过高导致超时。1. 运行check_engines.py查看可用引擎用--engines指定活着的引擎。2. 尝试更具体、更短的关键词组合。3. 增加search.py的超时时间需修改sicry.py中的REQUEST_TIMEOUT。fetch.py返回status: 0目标.onion服务当前离线、无法访问或屏蔽了你的出口节点。1. 这是暗网常态尝试其他URL。2. 使用renew.py更换出口IP后重试。3. 通过多个不同的出口节点如TorPool尝试访问。ask.py或pipeline.py报LLM错误1..env中LLM配置错误或API密钥无效。2. 网络问题导致无法连接LLM服务商。3. 本地Ollama服务未运行。1. 仔细检查.env中的LLM_PROVIDER和对应的API_KEY。2. 测试网络连通性。3. 运行ollama serve并确保模型已拉取如ollama pull llama3.2。脚本执行报ModuleNotFoundErrorPython依赖未安装或未安装在当前环境。在项目目录下使用正确的Python环境执行pip install -r requirements.txt如果存在或手动安装列出的依赖。所有操作速度极慢1. Tor网络本身延迟高。2. 出口节点带宽低或被限制。3. 暗网目标服务器响应慢。1. 使用renew.py尝试切换到其他出口节点。2. 对于搜索使用--engines限制为少数响应快的引擎如Ahmia, Ahmia-clearnet。3. 适当调整--scrape并发数避免对单个站点造成过大压力。5.3 与OpenClaw集成的进阶技巧将OnionClaw作为技能集成后你可以通过自然语言指挥AI智能体进行暗网调查。为了让交互更顺畅有几个技巧1. 提供清晰的上下文在向OpenClaw智能体发出指令时尽量明确。例如低效“查一下某公司。”高效“使用onionclaw技能在暗网上搜索关于‘某科技公司’的源代码泄露或凭证交易信息使用corporate分析模式将结果保存到临时文件并总结给我。”2. 利用技能描述SKILL.mdOnionClaw的SKILL.md文件中定义了触发短语。熟悉这些短语如“search the dark web for”, “investigate this .onion site”能帮助你更准确地触发技能。3. 结果后处理OpenClaw智能体可以读取pipeline.py生成的Markdown报告并对其进行总结、翻译或提取特定信息。你可以构建这样的工作流“运行一个关于X的暗网调查生成报告然后从报告中提取所有提到的比特币地址并格式化成一个列表。”4. 技能组合OpenClaw可能还有其他技能如网络扫描、漏洞数据库查询等。你可以让智能体串联多个技能。例如“先使用onionclaw搜索关于Apache Log4j漏洞的暗网讨论然后使用另一个技能检查我们内部系统中是否存在受影响的版本。”最后我必须再次强调工具的双重性。OnionClaw展示了AI与匿名网络结合所带来的强大自动化能力这种能力在安全研究员手中是盾在恶意行为者手中则是矛。在实际使用中请务必严格遵守你所在地区的法律法规仅将其用于授权的安全研究、渗透测试拥有明确书面授权或个人隐私保护。保持对技术的敬畏明确你的行为边界是每一个从业者的基本素养。