企业官网建设流程全解析

使用 OpenAI Codex CLI 安装与配置 Wren AI：技能发现、环境检查与首次查询完整指南

【免费下载链接】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

本指南介绍如何通过 OpenAI Codex CLI 安装 Wren AI：先借助npx skills add Canner/WrenAI --agent codex安装wren技能发现桩，再在 Codex 中通过自然语言触发 onboarding 工作流，由 Agent 自动完成环境检查、profile 创建、项目脚手架与首次查询。读完本文，你将掌握 Codex 与 Wren AI 的完整对接流程，以及 Wren 技能分发机制与 onboarding 每一步背后的 CLI 原理。

适用前提（Prerequisites）

在开始之前，需要满足两个条件：

• Codex CLI 已安装并完成身份认证：OpenAI Codex CLI 是本文使用的 AI 编码终端，需要保证codex命令可用，并且已登录 OpenAI 账户。
• OpenAI 账户登录：Codex 的认证依赖 OpenAI 账户，未登录时无法正常驱动 Agent 执行多步工作流。

此外，从仓库的 installation.md 与 quickstart.md 可以确认，Wren AI 的通用安装还隐含另外两个前提：Python 3.11+（onboarding 技能在环境检查阶段会用python3 --version校验）以及Node.js / npm（npx命令依赖 npm）。如果这些尚未就绪，建议先补齐再继续。

第一步：为 Codex 安装 wren 技能

执行下面的命令，将 Wren AI 的技能发现桩安装到 Codex 中：

npx skills add Canner/WrenAI --agent codex

这里的关键词是技能发现桩（discovery stub）。仓库的 skills/SKILLS.md 明确说明了这一设计：

This directory ships a single discovery stub (wren/SKILL.md) that an AI client can install. Once the agent reads the stub, it learns to fetch everything else from the CLI on demand.

也就是说，npx skills add只会安装一个名为wren的轻量技能，而不是把全部工作流指南都塞进客户端。真正的流程指南、参考文档和提示词辅助全部内置于wrenCLI 本身（即pip install wrenai安装的 Python 包），因此技能内容始终与已安装的 wrenai 版本一致，不存在技能缓存或版本漂移问题。这一点在 skills/wren/SKILL.md 的 frontmatter 中也能看到：它声明了allowed-tools: Bash(wren:*)，即只允许 Agent 调用wren前缀的命令。

安装时指定--agent codex的作用是让安装器把技能注册到 Codex 的配置目录；如果希望同一份技能对机器上所有 AI 编码客户端（Claude Code、Cursor、Windsurf、Cline 等）都生效，可以改用--agent '*'（见 installation.md）。

仓库的 skills/install.sh 展示了技能安装的另一种等价方式（curl 管道脚本），其逻辑与npx skills add一致：默认安装到$HOME/.claude/skills/，支持--force覆盖，并且优先使用本地克隆目录中的skills/wren/，否则从远端仓库下载。若技能已存在会跳过安装，重复执行时需要--force才会覆盖更新。

第二步：启动 Codex 并触发 onboarding

技能安装完成后，在项目目录中启动 Codex：

codex

然后向 Codex 提出如下请求：

Use the /wren skill to install and set up Wren AI.

这句话会命中wren技能 frontmatter 中声明的触发器之一（'install wren'、'set up wren engine'、'wren onboarding'等，见 skills/wren/SKILL.md），从而让 Agent 拉取并执行onboarding工作流。文档明确说明：该技能会引导 Agent 依次完成环境检查、profile 创建、项目脚手架和首次查询。

注意，installation.md 特别提醒：技能在会话启动时加载，因此安装技能后应新开一个 Codex 会话，再输入上述请求。

第三步：onboarding 工作流实际会做什么

onboarding 技能的主体位于 core/wren/src/wren/skills_content/onboarding/SKILL.md，它并不内嵌完整的操作手册，而是规定 Agent 侧的执行纪律（one step per turn，每次对话只推进一个步骤；绝不在聊天中索要凭证），并在每一步把 Agent 派发到正确的文档或兄弟技能。核心流程如下：

1. 环境预检（Preflight）

Agent 先执行一组只读检查，不询问任何项目信息：

• python3 --version—— 要求 Python 3.11+，版本过低则请用户升级后停止；
• 检查是否处于虚拟环境（sys.prefix != sys.base_prefix），PEP 668 系统上需要python3 -m venv；
• wren --version—— 若已安装则确认版本，避免重复安装；
• pwd—— 记录当前目录。

2. 分支选择：demo 还是自己的数据库

Agent 会询问你是先用内置的jaffle_shop示例（约 30 秒、无需数据库），还是连接自有数据库。选 demo 则直接跳转到 quickstart.md；选自有库则继续。

3. 收集项目名与数据库类型

只问两件事：项目名（将创建~/<name>/并进入）和数据库类型（如postgres、mysql、bigquery、snowflake、clickhouse、trino、duckdb等）。此时仍不询问任何凭证。

4. 创建工作区与.env模板

这一批操作会创建~/<project>/、安装wrenai[<ds>,main]，并生成一份空.env模板。关键命令是：

wren docs connection-info <ds> --format md

该命令通过内省数据源连接器的 Pydantic schema 实时输出真实的连接字段列表，因此永远不会与实际实现脱节（onboarding 技能明确禁止 Agent 凭空发明字段名）。以 PostgreSQL 为例，生成的.env骨架为：

POSTGRES_HOST= POSTGRES_PORT=5432 POSTGRES_DATABASE= POSTGRES_USER= POSTGRES_PASSWORD=

凭证只通过.env传递，用户在自己的编辑器中填写，Agent 全程看不到任何密钥值。

5. 创建连接 profile

Agent 会把/tmp/conn.yml中的每个字段写成${VAR}占位符（与上一步.env的键一一对应），然后执行：

wren profile add <project> --from-file /tmp/conn.yml

profile 是 Wren AI 对数据库连接信息的封装（类似 dbt profiles，见 quickstart.md 的 Step 4，它还支持--ui浏览器表单与--interactive交互式两种创建方式）。校验自动执行，CLI 会静默覆盖已存在的 profile。

6. 脚手架项目并绑定 profile

wren context init --empty # 拒绝覆盖已存在的 wren_project.yml wren context set-profile <project>

wren context init会生成项目目录结构（models/、views/、relationships.yml、knowledge/等）；wren context set-profile则把profile: <project>和data_source: <ds>写进wren_project.yml，将项目与连接确定性绑定——此后无论全局激活哪个 profile，该项目（含 SDK 调用）都不会被wren profile switch意外改道。

7. 生成 MDL 并完成首次查询

Agent 会先拉取generate-mdl技能完成 MDL（建模定义语言）生成，再运行wren context validate与wren context build，最后根据发现的数据表给出 2～3 个自然语言示例问题作为首次查询建议。onboarding 就此收尾，日后的日常查询由usage技能接管。

技能分发机制：wren skills命令是怎么工作的

整个 Codex 对接体验依赖wren skills子命令族，其实现位于 core/wren/src/wren/skills_cli.py 与 core/wren/src/wren/skills_delivery.py：

• wren skills list—— 枚举全部可用工作流指南。实现通过resources.files("wren") / "skills_content"遍历包内目录，从每个技能的SKILL.mdfrontmatter 读取description作为摘要，并列出其references/与scripts/下的资源；
• wren skills get <name>—— 打印指定技能的SKILL.md主指南到 stdout；加--full会按文件名排序追加所有references/*.md；加--script <s>则输出随技能打包的脚本源码（例如dlt-connector的introspect_dlt）；
• 未命中的技能名会抛出SkillNotFoundError并以退出码 1 提示可用名称。

技能内容作为 wheel 内的包数据分发，位于core/wren/src/wren/skills_content/<name>/（如onboarding/、usage/、generate-mdl/、dlt-connector/、enrich-context/、genbi/），这正是“指南永远匹配已安装 CLI 版本”这一承诺的代码级实现。仓库根目录的 skills/index.json 则是对外发布清单，其中将wren标记为discovery-stub。

技能安装后的一线命令速查

技能发现桩安装完成后，Codex（或任何支持技能调用的 AI 客户端）即可在会话中按需驱动以下命令（完整清单见 skills/SKILLS.md 与 skills/wren/SKILL.md）：

下一步

• Quickstart（使用示例数据） —— 用内置jaffle_shop数据集完整走一遍：安装wrenai[memory,main]、创建 DuckDB profile、生成 MDL、查询与 GenBI 部署；
• 连接你的数据库 —— 将 Wren AI 指向真实数据库，含各数据源的连接字段说明与完整故障排查手册；
• 若你想了解技能从“安装”到“按需取用”的完整交付模型与每个指南的职责，可阅读 Skills 参考。

【免费下载链接】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