作者来自 Elastic Alex Salgado使用 OpenClaw、可组合技能和 agents让你的本地 AI agent 访问 Elasticsearch 数据无需编写自定义代码。Agent Builder 现已正式发布。你可以通过 Elastic Cloud Trial 开始使用并在此查看 Agent Builder 的文档。在最近几周OpenClaw 在 AI 社区讨论中频繁出现特别是在关注 agents、自动化以及本地运行环境的开发者群体中。该项目迅速获得关注这自然引出了一个技术问题它为工程师解决了什么实际问题OpenClaw 是一个用于 AI agents 的自托管网关一个统一的运行时用于协调执行将 agents 视为隔离的进程并使用 skills以 Markdown 文件形式编写的结构化指令作为集成单元。从概念上讲这与我们使用命令行接口CLIs和脚本的方式并没有完全不同但现在它被正式化为以 agent 驱动的 workflows。这也引发了在 Elastic Stack 中的一次实践探索如果我们将 OpenClaw 视为一个编排运行时当 Elasticsearch 作为后端时它会如何表现以及使用 OpenClaw skills 进行集成有多简单让我们使用可组合技能composable skills构建一个集成。解决方案架构在本教程中我们将教 OpenClaw 通过一个自定义的只读技能访问并查询 Elasticsearch 数据然后演示它如何将多个技能组合在一起例如将 Elasticsearch 查询与实时天气数据结合起来生成动态报告。在进入实际操作步骤之前先看看我们要构建的内容。该解决方案由三个集成层组成它们通过 OpenClaw 编排协同工作。第 1 层存储与搜索Elasticsearch数据层运行在 Elasticsearch 上通过start-local启动只需一条命令即可使用 Docker 在本地启动 Elasticsearch 和 Kibana。两个示例索引用于演示不同的使用场景fresh_produce10 个产品支持语义搜索电商场景app-logs-synthetic来自四个服务的 30 条日志记录可观测性场景同一个只读技能可以同时适用于这两个索引无需任何重新配置agent 会检查 mapping并相应地调整查询。第 2 层编排OpenClaw GatewayGateway 接收自然语言请求并加载 Elasticsearch 技能由大语言模型LLM决定需要构建哪些查询。该技能是一个纯SKILL.md文件并包含参考文档这意味着其操作无需任何自定义代码。为了理解 Gateway 如何组织这一过程需要了解 OpenClaw 的两个核心概念Agents独立的 AI 实例每个都有自己的配置、workspace 和技能集合。你可以为不同用途运行多个 agents。Workspace定义 agent 上下文的文件夹包括AGENTS.mdagent 的长期说明、.env凭证以及skills/目录。可以把它理解为 agent 的工作环境。第 3 层技能可组合能力Skills 是写在 Markdown 文件SKILL.md中的结构化指令用于教 agent 如何使用特定工具或 API。它们可以是全局的所有 agents 可用、workspace 专用的或随 OpenClaw 一起提供的。agent 只会按需加载与当前请求相关的技能。本教程使用两个技能Elasticsearch-openclaw自定义本教程构建一个只读技能教 agent 如何使用 curl 对 Elasticsearch 索引进行搜索、过滤、聚合和探索。Weather社区技能用于组合演示一个从外部 API 获取当前天气情况的技能。在教程后续部分我们将演示 OpenClaw 如何在一次请求中组合这两个技能根据实时天气数据查询 Elasticsearch 中的产品而无需任何自定义集成代码。只读设计Read-only by designelasticsearch-openclaw技能在设计上是只读的。它提供用于搜索、过滤和聚合数据的模式但从不执行写入、更新或删除操作。这可以在让 AI agents 访问 Elasticsearch 集群时将安全风险降到最低。即使 agent 环境被攻破你的数据仍然不会被修改或删除。这通过以下方式进行保障技能设计在SKILL.md或参考文件中不包含任何写操作模式。API key 权限本教程使用只读 API key仅包含read和view_index_metadata权限。Agent 指令AGENTS.md明确说明“你可以 SEARCH、FILTER 和 AGGREGATE 数据但绝不能写入、更新或删除。”这种以安全为优先的设计也是为什么基础设施设置如索引创建、数据加载必须手动完成从设计上来说agent 无法替你执行这些操作。先决条件Prerequisites要完成本教程你需要以下条件软件和工具安装并运行Docker DesktopDocker Engine 带 Compose V2。通过start-local在本地运行Elasticsearch。我们将在下一节进行设置Jina API key免费https://jina.ai/embeddings安装OpenClawhttps://openclaw.ai环境设置首先克隆入门项目该项目包含 skill、workspace 配置以及开发工具脚本Dev Tools scriptsgit clone https://github.com/salgado/elasticsearch-openclaw-start-blog cd elasticsearch-openclaw-start-blog该仓库包含elasticsearch-openclaw-start-blog/ ├── devtools_fresh_produce.md ← Creates fresh_produce index (10 products) ├── devtools_app_logs_synthetic.md ← Creates app-logs-synthetic index (30 logs) └── openclaw-workspace-elastic-blog/ ├── AGENTS.md ← Agent briefing ├── .env.example ← Credentials template注意devtools*.md 文件包含以参考文档格式编写的 Kibana Dev Tools 命令。安装 OpenClawOpenClaw 是一个自托管的网关。这意味着你可以完全控制执行和数据但你需要准备本地环境或服务器。我在另一台机器上安装了 OpenClaw因此附上以下免责声明。** 安全与责任免责声明 **由于 OpenClaw 是一个早期阶段、快速发展的开源项目社区已经提出了关于潜在安全漏洞的重要讨论尤其是在令牌处理和第三方脚本执行方面。部署建议隔离环境如果你不是高级基础设施安全用户建议严格在隔离、可控的环境中安装 OpenClaw例如专用虚拟机 [VM]、无 root 权限的 Docker 容器或测试机。避免生产环境使用在项目达到更稳定、经过审计的版本之前不要在包含敏感数据或对公司网络无限制访问的服务器上运行该网关。最小权限原则建议使用权限受限的 Elasticsearch API key只读以降低风险即使环境遭到入侵。网络隔离Elasticsearch 和 OpenClaw 默认绑定到 localhost。除非有特殊原因否则保持默认设置。凭证轮换定期更换 API key。OpenClaw 会在本地存储凭证因此机器的安全性就是防护边界。审计日志启用 Elasticsearch 审计日志以跟踪 OpenClaw 所做的所有 API 调用记录代理访问了什么以及何时访问。保持安装更新。有关安全架构和部署选项的更深入分析请查阅官方 OpenClaw 文档。运行时安装OpenClaw 通过 CLI 管理守护进程和技能隔离。由于这是一个近期项目并且经历过命名变更建议严格按照官方文档操作以确保安装兼容性。# Global gateway installation curl -fsSL https://openclaw.ai/install.sh | bash准备 Elasticsearch 后端在连接任何 agent 运行时之前我们需要一个可用的 Elasticsearch 环境包含可查询的数据以及安全的只读访问层。在接下来的两个部分中我们将使用 start-local 在本地启动 Elasticsearch创建一个包含 semantic_text 和 Jina v5 embeddings 的索引加载示例数据验证语义搜索功能并生成只读 API key。一旦这个基础就绪Elasticsearch 端就完成了我们就可以专注于教 agent 如何使用它。第 1 部分在本地设置 Elasticsearch使用单条命令启动本地 Elasticsearch 和 Kibana 实例curl -fsSL https://elastic.co/start-local | sh完成后Elasticsearch 运行在 http://localhost:9200Kibana 运行在 http://localhost:5601凭据存放在 elastic-start-local/.env 中。第 2 部分在 Kibana Dev Tools 中配置索引打开 http://localhost:5601 → Dev Tools并按顺序运行 devtools_fresh_produce.md。步骤 1将 YOUR_JINA_API_KEY 替换为你实际的 Jina API key免费。步骤 2立即保存编码字段之后无法再检索。Dev Tools 文件中的关键命令包括创建 Jina 推理端点PUT _inference/text_embedding/jina-embeddings-v5 { service: jinaai, service_settings: { api_key: YOUR_JINA_API_KEY, model_id: jina-embeddings-v5-text-small } }使用 semantic_text 创建索引PUT /fresh_produce { mappings: { properties: { name: { type: text, fields: { keyword: { type: keyword } } }, description: { type: text }, category: { type: keyword }, price: { type: float }, stock_kg: { type: float }, on_sale: { type: boolean }, image_url: { type: keyword }, semantic_content: { type: semantic_text, inference_id: jina-embeddings-v5 } } } }semantic_text 字段类型会在索引时自动处理 embedding 生成。使用 bulk API索引示例产品完整 10 个产品数据请参见 devtools_fresh_produce.md。验证 semantic searchGET /fresh_produce/_search { query: { semantic: { field: semantic_content, query: healthy colorful meals } }, size: 3, _source: [name, description, category] }semantic query 类型会在查询端自动处理推理无需指定 model IDs 或 embedding 细节。创建只读 API keyPOST /_security/api_key { name: openclaw-readonly, role_descriptors: { reader: { cluster: [monitor], indices: [ { names: [fresh_produce, app-logs-synthetic], privileges: [read, view_index_metadata] } ] } } }保存响应中的编码值。这是你用于 OpenClaw 配置的 API key。连接到 OpenClaw在 Elasticsearch 后端准备就绪后我们现在可以将其接入 OpenClaw。生态系统中已经存在多种 Elasticsearch 集成从 Elastic 自家的 Model Context Protocol (MCP) 服务器到社区构建的 MCP 服务器。然而大多数都提供完整 CRUD 访问或者为不同的 agent runtime 设计。鉴于这项技术仍处于早期阶段且安全仍是主要关注点我选择构建一个专用 skill简单、只读、为 OpenClaw 专门设计。这种方式确保 agent 可以搜索、过滤和聚合数据但永远不会修改它即使环境被攻破也能将影响范围降到最低。在接下来的章节中我们将配置凭证、安装 skill、创建专用 agent并探索 workspace 如何将一切联系起来。安装 skill 并创建 agent步骤 1配置凭证从克隆的仓库中通过复制环境模板并填写你的 Elasticsearch URL 及只读 API key 来配置凭证cp openclaw-workspace-elastic-blog/.env.example openclaw-workspace-elastic-blog/.env编辑 .env 文件填写这两个值ELASTICSEARCH_URL: http://localhost:9200 (from start-local) ELASTICSEARCH_API_KEY: The encoded value from the read-only API key you created in Part 2 (the POST /_security/api_key response)示例 .env 文件ELASTICSEARCH_URLhttp://localhost:9200 ELASTICSEARCH_API_KEYVnVaRmxLSDRCQxxxxxxxxbGVfa2V5步骤 2从 ClawHub 安装 skillClawHub 是 OpenClaw 的公共 skill 注册中心可以把它想象成 AI agent skill 的 npm。截止本文撰写时ClawHub 已托管超过 3,200 个 skill涵盖从 Slack 和 GitHub 集成到物联网IoT设备自动化的各种功能。在本教程中我们创建了elasticsearch-openclaw这是一个专注于使用semantic_text进行只读查询、聚合和 Elasticsearch 9.x 可观测性的自定义 skill。它已发布在 ClawHub 上可以直接安装。最佳实践仅从可信来源安装 skill确保来源可靠像使用任何包管理器一样在授予 agent 访问权限前先审查内容。elasticsearch-openclawskill 已发布在 ClawHub。建议打开 OpenClaw Web UIhttp://127.0.0.1:18789/并尝试Install the elasticsearch-openclaw skill from https://clawhub.ai/salgado/elasticsearch-openclawOpenClaw 将会从 ClawHub 获取 skill。安装到相应目录。准备好后确认可用。步骤 3创建 agent通过注册一个专用 agent 并为其创建独立 workspace然后重启 gateway 以加载新配置openclaw agents add elasticsearch-agent \ --workspace ~/path/to/elasticsearch-openclaw-start-blog/openclaw-workspace-elastic-blog \ --non-interactive openclaw gateway restart理解 workspace现在 agent 已经运行让我们看看它是如何运作的。AGENTS.mdAGENTS.md 文件是 agent 的永久简报。它定义了 agent 的身份、能力以及行为方式。对于我们的 Elasticsearch agent这个文件会告诉 agent 可用的索引、只读约束以及推荐的查询模式。Skills何时发挥作用无 skill使用elasticsearch-openclawskillAgent 不知道 Elasticsearch 查询语法Agent 知道语义搜索、全文、本地过滤和聚合模式Agent 可能尝试写操作Agent 被指示绝不写入、更新或删除Agent 猜测字段名称和类型Agent 先检查 mappings再构建合适查询使用通用 curl 命令并靠试错使用针对 Elasticsearch 9.x 的结构化查询模板和最佳实践与 agent 一起探索配置好 Elasticsearch 后端并连接 OpenClaw agent就可以看看 agent 实际能做什么了。在接下来的章节中我们将测试自然语言查询、探索 observability 数据并组合多个 skills。在 OpenClaw 中测试打开 OpenClaw Web UI尝试一些自然语言查询。agent 会检查索引 mapping选择合适的查询类型并返回结果。输入示例“Find products that would be good for a healthy summer salad.”返回结果其他可探索的思路索引探索“What indices do I have in Elasticsearch? Show me the fields of fresh_produce.”过滤搜索“Show me all products on sale under $15.”聚合“What’s the average price by category?”可观测性为了展示 skill 在单一用例之外的功能仓库中包含第二个索引app-logs-synthetic包含四个虚拟服务的 30 条合成日志条目由devtools_app_logs_synthetic.md创建。设置日志数据由于 skill 是只读的你需要先填充索引。devtools_app_logs_synthetic.md文件包含五个命令三个用于设置两个用于验证创建 ingest pipeline自动向日志条目添加timestamp。创建索引 mapping定义app-logs-synthetic结构仅经典字段无semantic_text。批量插入日志加载 30 条跨四个服务的合成日志条目。Count 查询验证已索引 30 条文档。示例搜索快速测试以确认数据可查询。执行方法打开 Kibana Dev Toolshttp://localhost:5601 → Dev Tools从 .md 文件复制每个编号块粘贴到 Dev Tools 控制台按 Ctrl/CmdEnter 执行等待成功响应再执行下一块此操作会创建app-logs-synthetic索引并加载示例数据可供查询使用。在 OpenClaw Web UI 中尝试此查询Show me the distribution of HTTP status codes across all services.返回结果其他可探索的思路“How many 500 errors do I have in app-logs-synthetic? Which services are failing?”“Which endpoints have the slowest response times?”“What happened with the payment-service in the last 24 hours?”这是相同的 skill、相同的 agent、相同的设置只是指向不同的数据。Agent 会检查新的索引 mapping调整查询并返回相关结果无需任何重新配置。技能组合实战这正是可组合 skills 的亮点。首先向 agent 提问Install the weather skill.OpenClaw 会搜索 weather skill自动尝试安装并引导你完成整个过程。只需按照屏幕上的说明操作weather skill 不需要新的 API key。完成后尝试以下操作“Find the products on sale in the fresh_produce index that match today’s weather in São Paulo. Generate a nice HTML report with product cards using the image_url field from each document, price, description, and stock. Save it to ~/Desktop/report.html and open it in the browser.”在单次请求中Agent 会串联多个 skills使用weather skill检查当前天气使用Elasticsearch skill对匹配上下文的产品执行混合搜索并利用内置的文件和浏览器工具生成 HTML 报告并打开它。无需自定义集成代码无需 glue 脚本所有操作均由 LLM 在运行时通过 skills 自动组合完成。这就是 OpenClaw 与传统自动化框架的不同之处。你不需要预先编程工作流只需描述期望结果Agent 就会自动完成组合。结论SearchClaw 最初是一个简单实验最终展示了可组合、LLM 驱动的集成在实践中的样子。关键 takeaway 并不是单个工具它们都很熟悉而是方法论。我们没有编写特定应用和硬编码查询而是赋予 Agent 能力让它动态组合解决方案。这就是 OpenClaw 的原生特点可组合、LLM 驱动、本地优先。像任何早期项目一样OpenClaw 应谨慎使用尤其是在安全性和环境隔离方面。本教程中展示的只读 skill 方法是限制风险同时释放 Elasticsearch 数据价值的一种方式。完整代码可在仓库获取可作为自己集成的起点https://github.com/salgado/elasticsearch-openclaw-start-blog。原文https://www.elastic.co/search-labs/blog/openclaw-elasticsearch-ai-agents#testing-in-openclaw