1. 项目概述为你的AI助手装上本地深度研究引擎如果你正在使用OpenClaw或者ClawHub这类AI智能体平台并且对它们的研究能力有更高的要求——比如需要一份带详细引用的行业报告、一个结构严谨的文献综述或者是对某个技术话题进行多轮、深入的迭代探索——那么你很可能已经对云端研究服务的速度、成本或隐私性感到过困扰。今天要聊的这个项目local-deep-research-skill就是为了解决这个问题而生的。它本质上是一个“技能插件”能让你的OpenClaw智能体直接调用一个运行在你本地机器上的、功能强大的深度研究服务Local Deep Research, LDR。简单来说它把“研究”这个任务从云端搬回了你的电脑。你不再需要担心API调用次数、网络延迟或是敏感查询数据离开本地环境。整个研究流程从问题拆解、多轮搜索、信息综合到生成带引用的报告全部在你掌控的硬件和网络环境中完成。这对于需要处理专有信息、进行竞品分析、撰写学术材料或单纯追求极致隐私和可控性的开发者与研究者来说是一个游戏规则的改变者。无论你是AI应用开发者、技术分析师还是学术工作者只要你有让AI进行“真·深度研究”的需求这个技能都值得你花时间部署和调优。2. 核心架构与工作原理拆解2.1 LDR与OpenClaw的协同模式要理解这个技能的价值首先得厘清Local Deep Research (LDR)服务和OpenClaw智能体之间的关系。它们并非一体而是典型的“服务端-客户端”或“引擎-控制器”架构。LDR服务端/引擎这是一个独立的后台研究服务。你可以把它想象成一个驻扎在你本地的“研究专员”。它内置了大型语言模型LLM例如通过Ollama本地部署的模型的推理能力以及对接搜索引擎如SearXNG进行信息获取的模块。当收到一个研究课题时LDR会执行一个复杂的多周期流程先理解问题生成搜索查询获取网页内容分析、提炼信息然后基于已有发现提出新的、更深入的问题如此循环直至达到预设的深度或信息饱和。最终它会整理所有发现生成结构化的报告并附上准确的引用来源。这一切都跑在localhost:5000默认这样的本地端口上。OpenClaw Skill客户端/控制器这就是本项目一个为OpenClaw智能体编写的“技能”。它的角色是“调度员”和“通信兵”。OpenClaw智能体本身并不具备直接与LDR服务对话的能力。这个技能为智能体提供了标准的接口Actions当用户对智能体说“请深度研究一下量子计算的近期突破”时智能体会调用这个技能的start_research动作。技能随后会代表智能体通过HTTP请求与本地运行的LDR服务进行通信提交任务、查询进度、并取回最终的研究报告。这种解耦带来了巨大的灵活性。你可以独立升级LDR的研究算法或模型而不影响智能体技能的逻辑反之你也可以改进技能的通信或错误处理机制而不必改动核心研究引擎。2.2 技能执行流程与数据流转一次完整的研究请求在系统内部是如何流转的下面我们拆解这个闭环流程触发与指令解析用户在OpenClaw的对话界面中输入触发指令例如“research this topic: Web3 privacy solutions in 2024”。OpenClaw的智能体识别到关键词如“deep research”并决定调用local-deep-research-skill。参数封装与认证技能接收到智能体传递过来的研究主题query以及其他可选参数如输出语言、研究模式。技能脚本ldr-research.sh首先会处理认证问题。如果LDR服务启用了登录认证脚本会读取环境变量中的用户名和密码向LDR的登录端点/auth/login发起一个模拟浏览器登录的请求。这个过程会获取一个会话Cookie和CSRF令牌用于后续所有API调用的身份验证。这里的安全性至关重要所有凭证仅存在于你的本地环境变量或配置文件中绝不会发送到任何远程服务器。任务提交携带认证信息技能向LDR的API端点例如$LDR_BASE_URL/api/research/start发送一个POST请求提交研究任务。LDR服务接收请求后会进行校验然后将其放入任务队列并立即返回一个唯一的research_id。这个ID是后续跟踪该任务的唯一凭证。异步研究与状态轮询LDR开始异步执行研究任务。此时技能可以通过get_status动作定期使用research_id向LDR查询任务状态如“queued”, “running”, “completed”, “failed”。对于需要阻塞等待结果的场景技能提供了poll_until_complete动作它会以一定的间隔持续检查状态直到任务完成或超时。结果获取与交付当状态变为“completed”时技能调用get_result动作向LDR请求最终的研究报告。LDR返回一个结构化的数据通常包含报告标题、执行摘要、详细内容、完整的引用列表URL、标题、摘要以及使用的搜索词等元数据。技能将这个结果格式化后返回给OpenClaw智能体。最终呈现OpenClaw智能体接收技能返回的结构化数据并将其以友好、易读的格式如Markdown呈现给用户。用户便获得了一份由本地AI生成的、带可靠引用的深度研究报告。整个流程中所有的数据原始查询、爬取的网页内容、中间思考过程、最终报告都只在你的本地网络localhost中传输实现了研究过程的完全私有化。3. 环境准备与部署实操指南3.1 前置条件与依赖检查在安装技能之前必须确保基础环境就绪。这就像盖房子前要打好地基。第一确保LDR服务已就绪这是核心依赖。你需要先按照 LDR官方仓库 的指南成功在本地部署并运行LDR服务。推荐使用Docker Compose方式因为它能一键拉起LLM如Ollama、搜索引擎SearXNG和LDR应用本身省去大量配置麻烦。部署完成后务必在浏览器中访问http://127.0.0.1:5000或你自定义的端口确认LDR的Web界面可以正常打开并且各项服务LLM, Search状态健康。你可以通过curl http://127.0.0.1:5000/health命令快速检查API健康状态。第二安装系统命令行工具技能的执行脚本ldr-research.sh是一个Bash脚本它依赖两个非常常见的命令行工具curl和jq。curl用于发送HTTP请求与LDR API交互。jq用于解析LDR返回的JSON格式数据提取research_id、状态、报告内容等信息。 在Ubuntu/Debian系统上安装命令是sudo apt-get install curl jq。在macOS上如果安装了Homebrew可以使用brew install curl jq。请务必在安装技能前确认这两个工具已存在且可用。第三OpenClaw环境准备你需要一个已经安装并配置好的OpenClaw环境。确保OpenClaw具有执行本地shell脚本的权限因为技能最终是通过调用这个Bash脚本来工作的。同时OpenClaw的运行环境需要能够访问你运行LDR服务的主机网络通常就是localhost。3.2 技能安装与配置详解满足了前置条件现在可以安装和配置技能本身了。安装技能通常有两种方式。一是通过ClawHub技能市场直接搜索并安装“Local Deep Research”技能。二是手动安装将本技能仓库克隆或下载到你的OpenClaw的技能目录下例如~/.openclaw/skills/或项目指定的技能路径。确保目录结构被正确放置。环境变量配置核心步骤这是连接技能和LDR服务的关键。你需要设置一些环境变量告诉技能如何找到并登录你的LDR服务。强烈建议使用项目级的.env文件来管理并确保该文件被添加到.gitignore中绝对不要提交到版本库。创建一个名为.env的文件在技能根目录下内容参考如下# LDR服务的基础URL如果LDR运行在本机默认端口则无需修改 LDR_BASE_URLhttp://127.0.0.1:5000 # 如果你的LDR设置了登录认证则必须配置以下两项 LDR_SERVICE_USERyour_ldr_username LDR_SERVICE_PASSWORDyour_strong_password_here # 可选设置默认的研究模式detailed详细报告或 quick快速摘要 LDR_DEFAULT_MODEdetailed # 可选设置默认输出语言例如 zh 代表中文 LDR_DEFAULT_LANGUAGEzh # 可选设置默认搜索工具 LDR_DEFAULT_SEARCH_TOOLauto关于认证的深度解析LDR使用的是基于Web会话的认证Session CSRF而不是简单的HTTP Basic Auth。这意味着技能脚本需要模拟一个完整的浏览器登录流程GET 登录页面获取会话Cookie和嵌入在HTML表单中的CSRF令牌。POST 用户名、密码以及CSRF令牌到登录接口。 脚本ldr-research.sh已经封装了这个逻辑。你只需要提供正确的用户名和密码即可。务必为这个技能创建一个专用的LDR用户账号例如openclaw_bot而不是使用你的个人主账号。这样做的好处是权限隔离方便未来进行凭证轮换或审计也不会影响你通过浏览器正常使用LDR。配置加载顺序脚本会按照以下顺序寻找配置系统环境变量优先级最高。技能目录下的.env文件。LDR的全局配置目录~/.config/local_deep_research/config/.env。 你可以根据你的管理习惯选择其中一种。我个人的实践是在开发机器上使用LDR的全局配置在部署服务器上使用技能目录下的.env文件并通过环境或配置管理工具注入敏感信息。3.3 首次运行测试与验证配置完成后不要急于在OpenClaw中直接使用。先进行手动测试确保链路通畅。你可以直接运行技能提供的Bash脚本进行测试cd /path/to/local-deep-research-skill ./scripts/ldr-research.sh start_research 测试主题人工智能在医疗影像诊断中的最新进展如果一切正常脚本会输出一个JSON其中包含research_id。例如{research_id: abc123def456, status: queued, message: Research task submitted successfully.}拿到research_id后你可以用以下命令检查状态./scripts/ldr-research.sh get_status abc123def456当状态变为completed后使用以下命令获取结果./scripts/ldr-research.sh get_result abc123def456如果能看到结构化的研究报告输出恭喜你技能到LDR的通道已经打通。如果在任何一步出现连接错误、认证失败或JSON解析错误请根据错误信息回头检查LDR服务状态、网络连通性以及环境变量配置。4. 高级使用技巧与参数调优4.1 研究模式与输出语言的选择LDR技能提供了两个关键参数来定制研究行为mode模式和language语言。理解它们的不同场景能让你获得更符合预期的结果。研究模式 (mode)detailed(默认): 完整研究模式。LDR会执行多轮通常3-5轮的迭代搜索与分析旨在生成一份内容全面、结构清晰、引用详实的报告。报告通常包含执行摘要、详细分析、关键要点总结和完整的参考文献列表。这是进行严肃的竞品分析、技术调研或文献综述时的首选。缺点是耗时较长占用计算资源较多。quick: 快速摘要模式。LDR会执行较少轮次可能1-2轮的研究生成一个简洁的概述或摘要侧重于核心事实和结论引用可能不如详细模式完整。适用于当你只需要对一个话题有一个快速、大致的了解或者作为进一步深入研究的起点。速度更快资源消耗更少。实操建议在OpenClaw中触发技能时你可以通过自然语言指定模式例如“请用快速模式调研一下Rust编程语言在区块链领域的应用”。如果技能解析到了“快速”关键词可能会自动选用quick模式。更精确的做法是在开发自定义工作流时通过技能的输入参数显式指定mode。输出语言 (language)这是一个非常强大的功能。你可以通过--language参数或在配置中设置LDR_DEFAULT_LANGUAGE指定最终报告的输出语言。例如--language zh会要求LDR用中文生成报告--language ja对应日文--language es对应西班牙文等。背后的原理这通常不是简单的翻译。当指定非英语输出时能力强的LLM如DeepSeek、Qwen等会在信息综合和写作阶段直接用目标语言进行思考和输出。这意味着报告的逻辑组织、表达方式会更符合目标语言的习惯而不仅仅是英译中。这对于需要向非英语团队或客户呈现结果时特别有用。配置示例如果你想默认让所有研究都产出中文详细报告可以在.env文件中设置LDR_DEFAULT_MODEdetailed LDR_DEFAULT_LANGUAGEzh4.2 与OpenClaw工作流的深度集成这个技能的价值不仅仅在于单独执行一个研究命令更在于它能作为一环嵌入到更复杂的OpenClaw智能体工作流中。场景一自动化报告生成流水线。你可以创建一个智能体其工作流是1) 接收用户一个模糊的需求如“帮我分析一下新能源汽车电池的下一代技术”。2) 智能体先调用一个“问题澄清”技能与用户对话将模糊需求转化为具体的研究问题列表如“固态锂电池的能量密度现状”、“钠离子电池的成本与供应链”、“氢燃料电池在商用车领域的进展”。3) 针对每个具体问题并行或串行调用local-deep-research-skill获取深度报告。4) 最后调用一个“报告合成”技能将多份研究报告整合、去重、润色生成一份最终的综合性分析报告交付给用户。场景二实时问答的知识增强。构建一个知识库问答智能体。当用户提出一个复杂、需要最新外部知识的问题时例如“OpenAI最近发布的o1模型在数学推理上相比之前的模型具体提升了多少”智能体可以先调用本技能进行快速研究mode: quick获取最新的、带引用的信息。然后基于这些新鲜出炉的资料再生成给用户的最终答案并附上信息来源。这使得智能体的回答不再是基于陈旧的训练数据而是具备了“联网搜索”和“深度消化”的能力。技术实现要点在OpenClaw的技能定义文件SKILL.md或skill.json中你需要正确定义技能的输入输出模式Input/Output Schema。这确保了智能体能正确地将参数传递给ldr-research.sh脚本并能解析脚本返回的JSON结果。通常输出结果中会包含report_content、citations等字段智能体可以提取这些字段并以美观的格式渲染。4.3 性能优化与资源管理在本地运行深度研究计算资源是必须考虑的因素。LDR的后端LLM和搜索引擎都可能消耗大量CPU、内存和网络IO。LLM模型选型LDR通常通过Ollama来接入本地LLM。模型的选择直接影响研究质量和速度。追求质量选择大型的、推理能力强的模型如qwen2.5:72b、llama3.1:70b或deepseek-coder:33b如果研究偏重代码/技术。这些模型能更好地进行复杂推理、信息综合和高质量写作但需要强大的GPU和大量内存。平衡速度与质量中型模型如qwen2.5:7b、llama3.2:3b或gemma2:9b是不错的选择。它们在大多数主题上能提供合格的研究报告且推理速度更快资源要求更低。纯速度导向对于quick模式或简单主题可以使用更小的模型如phi3:mini。你需要根据你的硬件条件和质量要求进行测试和权衡。搜索引擎配置LDR默认或推荐使用SearXNG。SearXNG是一个元搜索引擎聚合了Google、Bing、DuckDuckGo等多个结果。你需要在其配置中仔细选择实例或自定义搜索引擎。一个稳定、快速且尊重隐私的SearXNG实例对研究结果的及时性和相关性至关重要。如果自建SearXNG需确保其网络通畅并能稳定访问目标搜索引擎。并发与队列管理如果你的OpenClaw智能体可能同时触发多个研究任务需要注意LDR服务的任务队列处理能力。默认配置可能只支持单个任务顺序执行。你可以查阅LDR文档看是否支持配置工作线程数或并发任务数以避免任务堆积。在智能体端也可以设计逻辑对并发的深度研究请求进行排队或优先级管理。5. 故障诊断与常见问题实录即使准备充分在实际操作中仍可能遇到各种问题。下面是我在部署和使用过程中遇到的一些典型情况及解决方法希望能帮你少走弯路。5.1 连接与认证类问题问题现象运行脚本时立即报错Connection refused或Failed to connect to 127.0.0.1 port 5000。排查思路这明确指向LDR服务未运行或网络不可达。解决步骤首先在终端执行docker ps如果用Docker运行或检查LDR的进程确认服务是否在运行。使用curl -v http://127.0.0.1:5000/health命令查看详细的连接过程。如果被拒绝检查防火墙设置如ufw或firewalld是否屏蔽了5000端口。在本地开发环境下通常需要开放本地回环地址的端口。确认LDR_BASE_URL环境变量设置是否正确。如果你修改了LDR的默认端口这里的URL也必须相应更新。问题现象脚本执行到登录步骤时失败提示Login failed或Could not extract CSRF token。排查思路这是最常见的认证问题原因在于LDR的登录页面结构可能发生变化或者凭证错误。解决步骤手动验证凭证打开浏览器访问$LDR_BASE_URL/auth/login用你配置的LDR_SERVICE_USER和LDR_SERVICE_PASSWORD手动登录一次。确保账号密码绝对正确且该账号有权限使用研究API。检查CSRF令牌提取脚本使用grep和sed从登录页面HTML中提取一个名为csrf_token的隐藏字段值。如果LDR前端更新导致字段名或HTML结构变化这个提取逻辑就会失效。你可以临时在脚本中添加echo $login_page来打印获取到的登录页面HTML检查其中是否存在input typehidden namecsrf_token value...这样的标签。查看LDR服务日志LDR的应用日志通常会记录登录尝试。通过docker logs ldr_container_name查看是否有相关错误信息例如“无效的用户名或密码”。环境变量加载问题确保脚本运行的环境确实加载了你设置的.env文件。可以在脚本开头加一行env | grep LDR来打印所有LDR相关的环境变量确认其值是否正确。5.2 研究任务执行类问题问题现象任务成功提交拿到了research_id但长时间处于queued或running状态永不完成。排查思路问题出在LDR服务内部的任务执行环节。可能是LLM服务挂掉搜索引擎无响应或者任务本身遇到了死循环。解决步骤检查LLM服务如果LDR使用Ollama运行ollama list查看模型是否已拉取并用ollama run model-name简单测试模型能否正常对话。查看Ollama日志是否有错误。检查搜索引擎服务访问SearXNG的Web界面如果独立部署尝试进行一次搜索看是否正常返回结果。如果SearXNG配置了外部搜索引擎且网络不通会导致LDR无法获取信息而卡住。查看LDR任务日志LDR应该提供了查看具体任务日志的途径可能是Web界面上的一个“Tasks”页面或者通过API查询任务详情。日志中会显示研究进行到了哪一步是在“生成搜索词”阶段卡住还是在“分析网页内容”阶段失败。任务超时设置技能脚本中的poll_until_complete函数有一个超时时间。如果研究任务确实非常复杂可能需要调大这个超时值。同时LDR服务本身也可能有任务执行超时设置需要检查其配置。问题现象任务失败状态为failed返回的错误信息模糊。排查思路需要获取更详细的错误信息。解决步骤使用get_result动作即使任务失败有时也会有部分结果或错误信息尝试获取更多内容。直接调用LDR的API。用curl或httpie工具向$LDR_BASE_URL/api/research/status/research_id发送请求查看原始返回的JSON里面可能包含更详细的error字段。研究查询词Query问题过于宽泛、模糊或带有特殊字符的查询可能导致LLM生成无效的搜索词或者搜索引擎返回无关结果使得研究流程无法推进。尝试将一个复杂问题拆分成几个更具体、明确的小问题分别研究。5.3 脚本与依赖类问题问题现象运行脚本时报错jq: command not found或curl: command not found。解决如前所述安装缺失的依赖包。在极少数情况下如果脚本通过特定用户如www-data运行需要确保该用户的PATH环境变量包含这些工具的路径或者使用工具的绝对路径如/usr/bin/curl。问题现象脚本执行权限不足报Permission denied。解决确保scripts/ldr-research.sh文件具有可执行权限。执行chmod x scripts/ldr-research.sh。问题现象JSON解析错误例如jq: parse error。排查思路这通常是因为LDR API返回的不是有效的JSON可能是遇到了HTTP错误页面如5xx错误或网络问题导致返回了HTML。解决步骤在脚本中在调用curl命令后、jq命令前可以先将其输出重定向到一个临时文件或者用echo $response打印出来检查其内容。确保curl命令正确跟随了重定向使用-L参数并且正确处理了HTTP状态码脚本中应检查$http_code。6. 安全实践与生产环境部署建议将这样一个涉及本地API调用和潜在敏感研究的系统用于生产环境安全是重中之重。以下是一些关键的安全加固建议。网络隔离与访问控制虽然LDR默认运行在localhost但在多用户或服务器环境中需要严格限制对5000端口的访问。防火墙规则配置主机防火墙只允许OpenClaw服务所在的主机或容器IP访问LDR的5000端口。禁止从公网或其他无关内网段访问。反向代理与认证可以考虑在LDR服务前部署一个反向代理如Nginx并配置额外的HTTP Basic认证或IP白名单。这样即使LDR本身的认证被绕过也还有一层防线。同时为Nginx配置SSL/TLS加密本地服务间的通信虽然在内网但纵深防御是好的实践。凭证管理绝对不要在代码、配置文件除非是.env且已被.gitignore或聊天记录中硬编码用户名和密码。使用密钥管理服务在生产环境中将LDR_SERVICE_USER和LDR_SERVICE_PASSWORD存储在专业的密钥管理服务中如Hashicorp Vault、AWS Secrets Manager或Azure Key Vault。在启动OpenClaw或调用技能前通过环境从这些服务动态注入凭证。定期轮换凭证为技能专用的LDR服务账号设置强密码并制定定期轮换的策略。技能脚本安全审计ldr-research.sh脚本拥有执行网络请求和解析数据的权限。在将其用于重要环境前建议进行代码审查。检查命令注入风险脚本中所有用户输入如研究主题query在拼接进curl命令或其它命令前是否经过了适当的转义或引用确保使用printf的%q格式或类似技术对参数进行安全处理防止恶意输入导致命令注入。最小权限原则运行OpenClaw和该技能的系统用户应仅拥有完成其功能所必需的最小权限。避免使用root用户运行。LDR服务自身安全别忘了保护LDR本身。及时更新定期关注LDR和其依赖组件Ollama, SearXNG的安全更新并及时打补丁。审查LDR配置检查LDR的配置文件关闭不必要的功能或API端点。确保其使用的LLM模型来源可信。日志与监控启用LDR的详细日志并集中收集和分析。监控异常的研究请求模式、频繁的认证失败等这些可能是攻击迹象。数据隐私与留存LDR生成的研究报告和缓存的网页数据可能包含敏感信息。你需要制定数据留存和清理策略。报告存储明确研究报告存储在哪里是只在OpenClaw的会话中还是会持久化到数据库存储多久以及如何加密。缓存清理LDR可能会缓存爬取的网页内容以提升速度。定期清理这些缓存或者配置不缓存敏感域名的内容。部署这样一个本地深度研究系统就像搭建一个私人的数字图书馆和研究团队。它赋予了你的AI智能体强大的、私有的信息获取与消化能力。从环境搭建、配置调试到安全加固每一步都需要细心和耐心。但一旦跑通你会发现它为自动化研究、智能分析和知识管理带来的效率提升是巨大的。最重要的是你完全掌控了数据和流程这在今天这个时代本身就是一种宝贵的价值。