使用 OpenHands 安装与配置 Wren AI开源编码 Agent 驱动的语义 SQL 层上手指南【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAIWren AIGenBI为 AI Agent 提供了一个开源的、受治理的 text-to-SQL 上下文层可将自然语言问题转化为可信的 SQL、图表与仪表盘覆盖 PostgreSQL、MySQL、BigQuery、Snowflake、ClickHouse、Redshift、Databricks 等 20 数据源。本文以仓库内docs/core/get_started/quickstart-with-agent/openhands.md为核心骨架讲解如何在 All-Hands 开源的编码 AgentOpenHands中接入 Wren AI通过一条命令安装wren技能skill发现桩再让 OpenHands 驱动/wren工作流完成环境检查、连接配置、项目脚手架与首次查询。读完本文你将掌握 OpenHands Wren AI 的完整安装链路、技能分发机制的底层原理以及接入真实数据库的下一步路径。前置条件在开始之前请确认你的环境满足以下要求OpenHands已安装并完成认证OpenHands 是 All-Hands 开源编码 Agent可在其官方文档中查看安装方式。Docker 运行时OpenHands 的典型运行方式依赖 Docker 运行时请提前就绪。从仓库的安装文档与快速入门可知被驱动的wrenCLI 还需要Python 3.11环境wrenai包通过 pip 安装这部分会在后续的 onboarding 流程中由 Agent 自动完成检查与安装。安装文档docs/core/get_started/installation.md强调整个过程只需安装一个技能发现桩discovery stubwren它会被安装到你的 Agent 技能目录对 Claude Code 是~/.claude/skills/wren/SKILL.md对 OpenHands 则通过npx skills add ... --agent openhands安装。真正的技能工作流指南并不在安装目录里而是随wrenaiPython 包分发由 CLI 按需输出——这正是本文后半部分要展开的分发机制。安装 Wren 技能在原文档的安装流程中第一步是为 OpenHands 安装 Wren 技能npx skills add Canner/WrenAI --agent openhands这条命令会从 Canner/WrenAI 仓库获取skills/wren/SKILL.md发现桩并以 OpenHands 作为目标 Agent 完成安装。--agent openhands用于指定目标 Agent若安装了多个 AI 编码 Agent 并希望全部生效可将参数改为--agent *见 docs/core/get_started/installation.md。除了npx skills add仓库还提供了一等价的安装脚本 skills/install.sh。该脚本支持两种来源从本地克隆仓库安装./install.sh会检测BASH_SOURCE判断是否来自本地克隆从 GitHub 拉取安装curl -fsSL install.sh 地址 | bash默认拉取main分支的skills/wren目录支持--force参数覆盖已存在的安装可用环境变量WREN_SKILLS_BRANCH与CLAUDE_SKILLS_DIR分别覆盖分支与目标目录。安装完成后只会出现一个名为wren的技能这是预期行为自 Wren0.8起onboarding、usage、generate-mdl、dlt-connector、enrich-context等完整工作流指南不再作为独立技能安装而是内置在wrenCLI 中由发现桩在需要时通过wren skills get name按需拉取参见 docs/core/reference/skills.md。仓库中的发现桩内容skills/wren/SKILL.md展示了它如何教会Agent 使用 CLI它列出wren skills list/get、wren docs connection-info、wren ask --guided|--direct等命令并明确说明工作流指南存在于wrenCLI 内部因此始终与已安装的 wrenai 版本匹配无技能缓存、无版本漂移。启动 OpenHands 并运行 onboarding技能安装完成后启动 OpenHandsopenhands然后在对话中向 Agent 提出Use the /wren skill to install and set up Wren AI.这正是原文档给出的核心交互方式。这条指令会触发/wren技能的 onboarding 流程——技能会引导 Agent 依次完成环境检查、连接配置profile、项目脚手架scaffolding以及首次查询全部在一个对话流程内完成。如果你更熟悉中文提问也可以等价地表达为使用 /wren 技能安装并配置 Wren AI。Agent 的技能路由机制discovery stub 的 description 字段定义了触发词包括 install wren、set up wren engine、connect a new database 等均会路由到 onboarding 工作流。onboarding 技能在幕后做了什么/wren技能在 OpenHands 中的实际执行逻辑由仓库中内置的技能内容 core/wren/src/wren/skills_content/onboarding/SKILL.md 定义。它在 Agent 侧强制约束执行规则并把程序性细节、各数据源注意事项与故障排查手册交给对应文档而非复制到技能内。其工作流大致如下模式约定Agent 侧规则每轮只做一步每个编号步骤独占一轮对话Agent 只询问该步骤所需的信息然后执行命令、确认、再进入下一步严禁一次性收集项目名 数据库类型 凭据。绝不在聊天中索要凭据host、port、user、password、token 一律通过.env文件传递由用户在编辑器中填写Agent 永不看到明文值。构建 MDL 之前禁止查询数据库Agent 必须先运行wren skills get generate-mdl生成语义模型层否则对未建模表的查询必然失败。不得臆造连接字段名必须运行wren docs connection-info ds从实时 Pydantic schema 内省真实字段。预检只读检查Agent 先执行只读的环境检查并汇报python3 --version—— 要求 Python 3.11版本过旧则请用户升级并停止检查虚拟环境python3 -c import sys; print(sys.prefix ! sys.base_prefix)PEP 668 系统建议创建 venvwren --version—— 已安装则确认后再重装pwd—— 记录当前工作目录。分支选择示例数据还是自有数据库Agent 会询问先体验内置的jaffle_shop示例约 30 秒、无需数据库还是连接你自己的数据库选择demo→ 指向 快速入门文档结束本技能选择自有数据库→ 继续后续步骤。步骤 1收集项目名 数据库类型这两项是唯一需要提前收集的信息一起询问以便用户一次性回答。Agent 会建议常见数据源postgresAurora PostgreSQL 用、mysqlAurora MySQL 用、bigquery、snowflake、clickhouse、trino、duckdb等。步骤 2创建工作区与.envAgent 批量执行mkdir -p ~/project cd ~/project pip install wrenai[ds,main] wren docs connection-info ds --format md其中最后一条命令通过内省连接器生成.env模板字段键格式为DS_FIELDUPPER_SNAKE值为空。以 postgres 为例POSTGRES_HOST POSTGRES_PORT5432 POSTGRES_DATABASE POSTGRES_USER POSTGRES_PASSWORD若项目是 git 仓库建议将.env加入.gitignore并设置chmod 600 .env。随后 Agent 告知用户.env路径请用户填好所有值并回复 done。步骤 3创建连接 profile用户回复 done 之后Agent 编写/tmp/conn.yml每个字段使用${VAR}占位符与.env键对应datasource: ds host: ${DS_HOST} port: ${DS_PORT} # … 每个字段一行字段来自 wren docs connection-info ds然后执行wren profile add project --from-file /tmp/conn.yml验证自动运行。任何警告都按 连接指南 的 troubleshooting 章节定位症状缺失密钥、驱动认证失败、ValidationError、主机不可达等。注意CLI 会静默覆盖同名 profile没有--force标志。步骤 3.5 与 3.6脚手架项目并绑定 profilewren context init --empty wren context set-profile projectwren context init --empty会拒绝覆盖已有的wren_project.yml并创建标准项目结构models/、views/、relationships.yml、knowledge/rules sql以及AGENTS.md。wren context set-profile则把profile:与data_source:取自刚验证过的 profile保证正确写入wren_project.yml从而让项目对连接具有确定性解析——此后无论全局激活哪个 profile该项目查询都不会被意外重定向。步骤 4生成 MDL交接给 generate-mdl 技能Agent 必须先构建 MDL 才能查询数据因此运行wren skills get generate-mdl并跟随其指引完成表内省、类型归一化与 YAML 生成随后回到本流程执行wren context validate wren context build并汇报模型数量与验证告警。generate-mdl技能的七阶段流程连接 → 发现 → 归一化 → 脚手架 → 验证 → 索引 → 迭代在 docs/core/reference/skills.md 有完整描述类型归一化可通过wren utils parse-type或 Python 的wren.type_mapping.parse_type()完成。步骤 5开始提问Agent 根据已发现的表给出 23 个自然语言问题建议例如针对订单表上个月有多少订单按总额排名前 5 的客户是谁然后将日常查询交接给wren skills get usage技能。至此OpenHands 会话中的完整 onboarding 即告完成。Wren 技能的底层分发机制理解/wren技能为什么总是与已安装版本匹配需要看仓库中的实现细节发现桩skills/wren/SKILL.md是约 50 行的轻量文件frontmatter 中声明name: wren、allowed-tools: Bash(wren:*)正文教会 Agent指南从 CLI 按需获取。这就是npx skills add Canner/WrenAI --agent openhands安装的全部内容。按需输出skills_cli.py 实现wren skills list与wren skills get name后者支持--full内联references/*.md与--script name打印内置脚本。真正的取数逻辑在 skills_delivery.py 中通过importlib.resources定位wren/skills_content/name/SKILL.md并返回内容技能不存在时抛出SkillNotFoundError。随 wheel 分发技能包目录core/wren/src/wren/skills_content/onboarding、usage、generate-mdl、enrich-context、dlt-connector、genbi 等通过 Hatchling 的 wheel artifacts glob 打进wrenai包因此pip install wrenai后技能内容与 CLI 版本天然一致。CI 内容守卫测试 test_served_content_guard.py 会扫描所有服务内容skills_content、ask_templates与发现桩中出现的每个wren cmd调用对照真实 CLI 命令树校验子命令与--flag是否真实存在——防止文档/技能教 Agent 运行不存在的命令。测试中test_command_tree_loaded断言了skills get、docs connection-info、ask --guided、ask --direct等命令与标志的注册。这套单桩 按需取指南的模型解决了早期版本的痛点此前每个技能以独立 markdown 文件夹安装到~/.claude/skills/等目录存在打包内容与 CLI 版本漂移以及Agent 无需也要全部预加载两个问题详见 docs/core/reference/skills.md。常见问题与排查要点如果在 OpenHands 驱动/wren技能时遇到问题onboarding 技能明确要求不要自行携带错误手册而是将 连接指南 的 troubleshooting 章节呈现给用户。该手册覆盖的典型症状包括wren: command not foundCLI 未安装或 venv 未激活pip install ... externally-managed-environmentPEP 668 系统需先建 venv缺失密钥导致的MissingSecretError驱动认证失败、PydanticValidationError/ 未知数据源连接被拒 / 防火墙 / 云数据库 IP 白名单wren context validate的告警类别。若遇到手册之外的错误让 Agent 将错误信息连同官方文档呈现给用户并反馈 issue 即可。下一步完成 OpenHands 中的 onboarding 后你可以按需推进使用示例数据快速入门用内置的jaffle_shop数据集端到端走一遍wren context init、MDL 生成、自然语言查询、cube 与 GenBI 仪表盘流程全程无需云数据库与 Docker连接你的数据库把 Wren AI 指向真实数据库。流程与数据源无关——安装连接器 extra如pip install wrenai[postgres,bigquery,main]→wren profile add创建 profile →wren context set-profile绑定项目 → 生成 MDL → 开始查询深入了解技能体系查看 技能参考文档 中 onboarding、usage、generate-mdl、enrich-context、dlt-connector、genbi 六个技能各自的触发条件与工作流。整个过程中OpenHands或其他任意 AI 编码 Agent都只是驾驶员真正干活的是随wrenai包分发、由wren skills get name按需取出的工作流指南与wrenCLI 本身。这也意味着——无论你用的是 OpenHands、Claude Code、Cursor 还是 Codex安装步骤都收敛为同一条npx skills add Canner/WrenAI --agent name之后把控制权交给 Agent 即可。【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
使用 OpenHands 安装与配置 Wren AI：开源编码 Agent 驱动的语义 SQL 层上手指南
使用 OpenHands 安装与配置 Wren AI开源编码 Agent 驱动的语义 SQL 层上手指南【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAIWren AIGenBI为 AI Agent 提供了一个开源的、受治理的 text-to-SQL 上下文层可将自然语言问题转化为可信的 SQL、图表与仪表盘覆盖 PostgreSQL、MySQL、BigQuery、Snowflake、ClickHouse、Redshift、Databricks 等 20 数据源。本文以仓库内docs/core/get_started/quickstart-with-agent/openhands.md为核心骨架讲解如何在 All-Hands 开源的编码 AgentOpenHands中接入 Wren AI通过一条命令安装wren技能skill发现桩再让 OpenHands 驱动/wren工作流完成环境检查、连接配置、项目脚手架与首次查询。读完本文你将掌握 OpenHands Wren AI 的完整安装链路、技能分发机制的底层原理以及接入真实数据库的下一步路径。前置条件在开始之前请确认你的环境满足以下要求OpenHands已安装并完成认证OpenHands 是 All-Hands 开源编码 Agent可在其官方文档中查看安装方式。Docker 运行时OpenHands 的典型运行方式依赖 Docker 运行时请提前就绪。从仓库的安装文档与快速入门可知被驱动的wrenCLI 还需要Python 3.11环境wrenai包通过 pip 安装这部分会在后续的 onboarding 流程中由 Agent 自动完成检查与安装。安装文档docs/core/get_started/installation.md强调整个过程只需安装一个技能发现桩discovery stubwren它会被安装到你的 Agent 技能目录对 Claude Code 是~/.claude/skills/wren/SKILL.md对 OpenHands 则通过npx skills add ... --agent openhands安装。真正的技能工作流指南并不在安装目录里而是随wrenaiPython 包分发由 CLI 按需输出——这正是本文后半部分要展开的分发机制。安装 Wren 技能在原文档的安装流程中第一步是为 OpenHands 安装 Wren 技能npx skills add Canner/WrenAI --agent openhands这条命令会从 Canner/WrenAI 仓库获取skills/wren/SKILL.md发现桩并以 OpenHands 作为目标 Agent 完成安装。--agent openhands用于指定目标 Agent若安装了多个 AI 编码 Agent 并希望全部生效可将参数改为--agent *见 docs/core/get_started/installation.md。除了npx skills add仓库还提供了一等价的安装脚本 skills/install.sh。该脚本支持两种来源从本地克隆仓库安装./install.sh会检测BASH_SOURCE判断是否来自本地克隆从 GitHub 拉取安装curl -fsSL install.sh 地址 | bash默认拉取main分支的skills/wren目录支持--force参数覆盖已存在的安装可用环境变量WREN_SKILLS_BRANCH与CLAUDE_SKILLS_DIR分别覆盖分支与目标目录。安装完成后只会出现一个名为wren的技能这是预期行为自 Wren0.8起onboarding、usage、generate-mdl、dlt-connector、enrich-context等完整工作流指南不再作为独立技能安装而是内置在wrenCLI 中由发现桩在需要时通过wren skills get name按需拉取参见 docs/core/reference/skills.md。仓库中的发现桩内容skills/wren/SKILL.md展示了它如何教会Agent 使用 CLI它列出wren skills list/get、wren docs connection-info、wren ask --guided|--direct等命令并明确说明工作流指南存在于wrenCLI 内部因此始终与已安装的 wrenai 版本匹配无技能缓存、无版本漂移。启动 OpenHands 并运行 onboarding技能安装完成后启动 OpenHandsopenhands然后在对话中向 Agent 提出Use the /wren skill to install and set up Wren AI.这正是原文档给出的核心交互方式。这条指令会触发/wren技能的 onboarding 流程——技能会引导 Agent 依次完成环境检查、连接配置profile、项目脚手架scaffolding以及首次查询全部在一个对话流程内完成。如果你更熟悉中文提问也可以等价地表达为使用 /wren 技能安装并配置 Wren AI。Agent 的技能路由机制discovery stub 的 description 字段定义了触发词包括 install wren、set up wren engine、connect a new database 等均会路由到 onboarding 工作流。onboarding 技能在幕后做了什么/wren技能在 OpenHands 中的实际执行逻辑由仓库中内置的技能内容 core/wren/src/wren/skills_content/onboarding/SKILL.md 定义。它在 Agent 侧强制约束执行规则并把程序性细节、各数据源注意事项与故障排查手册交给对应文档而非复制到技能内。其工作流大致如下模式约定Agent 侧规则每轮只做一步每个编号步骤独占一轮对话Agent 只询问该步骤所需的信息然后执行命令、确认、再进入下一步严禁一次性收集项目名 数据库类型 凭据。绝不在聊天中索要凭据host、port、user、password、token 一律通过.env文件传递由用户在编辑器中填写Agent 永不看到明文值。构建 MDL 之前禁止查询数据库Agent 必须先运行wren skills get generate-mdl生成语义模型层否则对未建模表的查询必然失败。不得臆造连接字段名必须运行wren docs connection-info ds从实时 Pydantic schema 内省真实字段。预检只读检查Agent 先执行只读的环境检查并汇报python3 --version—— 要求 Python 3.11版本过旧则请用户升级并停止检查虚拟环境python3 -c import sys; print(sys.prefix ! sys.base_prefix)PEP 668 系统建议创建 venvwren --version—— 已安装则确认后再重装pwd—— 记录当前工作目录。分支选择示例数据还是自有数据库Agent 会询问先体验内置的jaffle_shop示例约 30 秒、无需数据库还是连接你自己的数据库选择demo→ 指向 快速入门文档结束本技能选择自有数据库→ 继续后续步骤。步骤 1收集项目名 数据库类型这两项是唯一需要提前收集的信息一起询问以便用户一次性回答。Agent 会建议常见数据源postgresAurora PostgreSQL 用、mysqlAurora MySQL 用、bigquery、snowflake、clickhouse、trino、duckdb等。步骤 2创建工作区与.envAgent 批量执行mkdir -p ~/project cd ~/project pip install wrenai[ds,main] wren docs connection-info ds --format md其中最后一条命令通过内省连接器生成.env模板字段键格式为DS_FIELDUPPER_SNAKE值为空。以 postgres 为例POSTGRES_HOST POSTGRES_PORT5432 POSTGRES_DATABASE POSTGRES_USER POSTGRES_PASSWORD若项目是 git 仓库建议将.env加入.gitignore并设置chmod 600 .env。随后 Agent 告知用户.env路径请用户填好所有值并回复 done。步骤 3创建连接 profile用户回复 done 之后Agent 编写/tmp/conn.yml每个字段使用${VAR}占位符与.env键对应datasource: ds host: ${DS_HOST} port: ${DS_PORT} # … 每个字段一行字段来自 wren docs connection-info ds然后执行wren profile add project --from-file /tmp/conn.yml验证自动运行。任何警告都按 连接指南 的 troubleshooting 章节定位症状缺失密钥、驱动认证失败、ValidationError、主机不可达等。注意CLI 会静默覆盖同名 profile没有--force标志。步骤 3.5 与 3.6脚手架项目并绑定 profilewren context init --empty wren context set-profile projectwren context init --empty会拒绝覆盖已有的wren_project.yml并创建标准项目结构models/、views/、relationships.yml、knowledge/rules sql以及AGENTS.md。wren context set-profile则把profile:与data_source:取自刚验证过的 profile保证正确写入wren_project.yml从而让项目对连接具有确定性解析——此后无论全局激活哪个 profile该项目查询都不会被意外重定向。步骤 4生成 MDL交接给 generate-mdl 技能Agent 必须先构建 MDL 才能查询数据因此运行wren skills get generate-mdl并跟随其指引完成表内省、类型归一化与 YAML 生成随后回到本流程执行wren context validate wren context build并汇报模型数量与验证告警。generate-mdl技能的七阶段流程连接 → 发现 → 归一化 → 脚手架 → 验证 → 索引 → 迭代在 docs/core/reference/skills.md 有完整描述类型归一化可通过wren utils parse-type或 Python 的wren.type_mapping.parse_type()完成。步骤 5开始提问Agent 根据已发现的表给出 23 个自然语言问题建议例如针对订单表上个月有多少订单按总额排名前 5 的客户是谁然后将日常查询交接给wren skills get usage技能。至此OpenHands 会话中的完整 onboarding 即告完成。Wren 技能的底层分发机制理解/wren技能为什么总是与已安装版本匹配需要看仓库中的实现细节发现桩skills/wren/SKILL.md是约 50 行的轻量文件frontmatter 中声明name: wren、allowed-tools: Bash(wren:*)正文教会 Agent指南从 CLI 按需获取。这就是npx skills add Canner/WrenAI --agent openhands安装的全部内容。按需输出skills_cli.py 实现wren skills list与wren skills get name后者支持--full内联references/*.md与--script name打印内置脚本。真正的取数逻辑在 skills_delivery.py 中通过importlib.resources定位wren/skills_content/name/SKILL.md并返回内容技能不存在时抛出SkillNotFoundError。随 wheel 分发技能包目录core/wren/src/wren/skills_content/onboarding、usage、generate-mdl、enrich-context、dlt-connector、genbi 等通过 Hatchling 的 wheel artifacts glob 打进wrenai包因此pip install wrenai后技能内容与 CLI 版本天然一致。CI 内容守卫测试 test_served_content_guard.py 会扫描所有服务内容skills_content、ask_templates与发现桩中出现的每个wren cmd调用对照真实 CLI 命令树校验子命令与--flag是否真实存在——防止文档/技能教 Agent 运行不存在的命令。测试中test_command_tree_loaded断言了skills get、docs connection-info、ask --guided、ask --direct等命令与标志的注册。这套单桩 按需取指南的模型解决了早期版本的痛点此前每个技能以独立 markdown 文件夹安装到~/.claude/skills/等目录存在打包内容与 CLI 版本漂移以及Agent 无需也要全部预加载两个问题详见 docs/core/reference/skills.md。常见问题与排查要点如果在 OpenHands 驱动/wren技能时遇到问题onboarding 技能明确要求不要自行携带错误手册而是将 连接指南 的 troubleshooting 章节呈现给用户。该手册覆盖的典型症状包括wren: command not foundCLI 未安装或 venv 未激活pip install ... externally-managed-environmentPEP 668 系统需先建 venv缺失密钥导致的MissingSecretError驱动认证失败、PydanticValidationError/ 未知数据源连接被拒 / 防火墙 / 云数据库 IP 白名单wren context validate的告警类别。若遇到手册之外的错误让 Agent 将错误信息连同官方文档呈现给用户并反馈 issue 即可。下一步完成 OpenHands 中的 onboarding 后你可以按需推进使用示例数据快速入门用内置的jaffle_shop数据集端到端走一遍wren context init、MDL 生成、自然语言查询、cube 与 GenBI 仪表盘流程全程无需云数据库与 Docker连接你的数据库把 Wren AI 指向真实数据库。流程与数据源无关——安装连接器 extra如pip install wrenai[postgres,bigquery,main]→wren profile add创建 profile →wren context set-profile绑定项目 → 生成 MDL → 开始查询深入了解技能体系查看 技能参考文档 中 onboarding、usage、generate-mdl、enrich-context、dlt-connector、genbi 六个技能各自的触发条件与工作流。整个过程中OpenHands或其他任意 AI 编码 Agent都只是驾驶员真正干活的是随wrenai包分发、由wren skills get name按需取出的工作流指南与wrenCLI 本身。这也意味着——无论你用的是 OpenHands、Claude Code、Cursor 还是 Codex安装步骤都收敛为同一条npx skills add Canner/WrenAI --agent name之后把控制权交给 Agent 即可。【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考