OpenClaw shadcn/ui 技能指南

OpenClaw shadcn/ui 技能概述

shadcn/ui 技能将 OpenClaw 与 shadcn/ui 组件库连接，赋予你的 Agent 在项目中添加、配置和组合无障碍 React 组件的能力。安装完成后，你可以使用自然语言描述来搭建完整的 UI 功能——表单、数据表格、导航、对话框等。

与传统以 npm 包形式发布的组件库不同，shadcn/ui 会将组件源代码直接复制到你的项目中。这意味着你拥有每一行代码的完全控制权，可以自由自定义组件而无需与库的抽象层作斗争。OpenClaw shadcn/ui 技能通过对话交互来处理组件的选择、安装、组合和样式设置，让这一工作流程更加高效。

典型工作流程：

1. 让 OpenClaw 添加一个支持排序和分页的数据表格。
2. Agent 运行 npx shadcn@latest add table 及相关组件，然后根据你指定的列生成表格实现代码。
3. 一个功能完整、符合无障碍标准的数据表格就出现在你的项目中——随时可以自定义。

此技能专为使用 Tailwind CSS 的 React 和 Next.js 项目打造。它可以与 Frontend Design 技能自然搭配，获取布局和用户体验方面的指导，同时也能很好地配合任何设计系统工作流程使用。

shadcn/ui 技能安装前的准备

安装 shadcn/ui 技能之前，请确保你已具备以下条件：

• 已安装并运行 OpenClaw（v1.0+）
• 一个已配置 Tailwind CSS 的 React 或 Next.js 项目
• Node.js v18+ 以及包管理器（npm、pnpm 或 bun）
• 已安装 clawhub CLI 用于技能管理

验证你的环境：

# 检查 OpenClaw 版本
openclaw --version

# 检查 Node.js 版本
node --version

# 验证 Tailwind CSS 已配置
npx tailwindcss --help

如果你要创建新项目，Agent 可以帮助你使用 npx shadcn@latest init 初始化一个预配置了 shadcn/ui 的 Next.js 项目。

如何安装 shadcn/ui 技能

使用单条命令安装 shadcn/ui 技能：

npx clawhub@latest install shadcn-ui

验证安装是否成功：

clawhub list

你应该能在已安装的技能列表中看到 shadcn-ui。

shadcn/ui 技能配置指南

shadcn/ui 技能不需要 API 密钥或外部认证。它直接与你的本地项目文件和 shadcn CLI 配合工作。

项目初始化

如果你的项目尚未配置 shadcn/ui，Agent 可以为你完成初始化：

# 在你的项目中初始化 shadcn/ui
npx shadcn@latest init

这会在项目根目录创建一个 components.json 配置文件，包含以下设置：

| 设置项 | 说明 | |---------|-------------| | style | 组件样式变体（default 或 new-york） | | tailwind.baseColor | 主题基础颜色（slate、gray、zinc 等） | | tailwind.cssVariables | 是否使用 CSS 变量进行主题定制 | | aliases.components | 组件的导入路径别名 | | aliases.utils | 工具函数的导入路径别名 |

主题自定义

通过编辑 CSS 变量或让 Agent 调整颜色来自定义默认主题：

/* 示例：在 globals.css 中自定义主题变量 */
@layer base {
  :root {
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
  }
}

重要提示： shadcn/ui 组件会被复制到你的项目源代码中。你对每个组件拥有完全控制权——没有隐藏的依赖或锁定的抽象层。

shadcn/ui 技能使用示例

1. 添加完整表单

你： "创建一个用户注册表单，包含姓名、邮箱、密码字段和条款复选框。使用 zod 添加验证。"

Agent 会使用 npx shadcn@latest add 安装所需组件（form、input、checkbox、button、label），然后生成一个完整的表单组件，包含 zod schema 验证、错误提示和无障碍标签。表单遵循 React Hook Form 模式，可直接连接到你的 API。

2. 构建数据表格

你： "添加一个用于展示用户的数据表格，包含姓名、邮箱、角色和状态列。支持排序、筛选和分页。"

Agent 会添加 table 组件，并使用 @tanstack/react-table 构建一个功能完善的数据表格。它会生成列定义、筛选控件、排序处理器和分页——全部带有正确的 TypeScript 类型和无障碍属性。

3. 创建仪表盘布局

你： "搭建一个仪表盘布局，包含可折叠侧边栏、顶部导航栏、面包屑导航和主内容区域。"

Agent 会安装 sidebar、navigation-menu、breadcrumb 和 separator 组件，然后将它们组装成一个响应式布局，带有适配移动端的侧边栏切换按钮和正确的语义化 HTML 结构。

4. 添加命令面板

你： "添加一个类似 VS Code 的命令面板，支持 Ctrl+K 快捷键，让用户可以搜索页面和操作。"

Agent 会安装 command 和 dialog 组件，设置键盘快捷键监听器，并创建一个可搜索的命令菜单，包含分组项目、图标和导航处理器。

5. 组合设置页面

你： "构建一个设置页面，包含个人资料、账户、通知和外观四个标签页。在每个标签页内使用卡片对相关选项进行分组。"

Agent 会安装 tabs、card、switch、select 和 separator 组件，然后构建一个完整的设置界面，包含表单字段、开关和下拉选择器，按逻辑分组到各个标签页中。

安全与最佳实践

使用 shadcn/ui 技能时，请遵循以下准则：

• 审查生成的代码。 Agent 会直接在你的项目中生成组件代码。在提交之前，务必审查新文件和更改，尤其是表单处理器和 API 集成部分。
• 验证用户输入。 shadcn/ui 提供的是 UI 组件，而非输入验证。务必使用 zod 或 yup 等库为表单配合服务端验证，并在处理之前对输入进行清理。
• 保持依赖更新。 shadcn/ui 组件依赖 Radix UI 原语和其他包。定期运行 npm audit 并更新存在漏洞的依赖。
• 使用语义化 HTML。 Agent 默认生成无障碍标记，但请验证自定义修改是否保留了 ARIA 属性和键盘导航功能。
• 遵循组件模式。 将 shadcn/ui 组件放在指定的组件目录中（例如 components/ui/）。避免内联修改——通过组合方式进行扩展。查阅安全检查清单获取通用 OpenClaw 指南。

常见错误与故障排除

"components.json not found"

你的项目尚未初始化 shadcn/ui。

# 在你的项目中初始化 shadcn/ui
npx shadcn@latest init

按照提示选择你的样式、基础颜色和导入别名。Agent 也可以帮你完成此操作。

"Module not found: Can't resolve '@/components/ui/button'"

导入路径别名与你的项目配置不匹配。

1. 检查你的 components.json 中配置的别名路径。
2. 确认你的 tsconfig.json 中有匹配的路径别名：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. 如果使用 Next.js，在修改 tsconfig.json 后需要重启开发服务器。

"Tailwind CSS classes not applying"

Tailwind 没有处理组件文件所在的目录。

1. 确认你的 tailwind.config.js 包含了组件路径：

module.exports = {
  content: [
    "./src/components/**/*.{js,ts,jsx,tsx}",
  ],
}

2. 确保 globals.css 导入了 Tailwind 指令（@tailwind base; @tailwind components; @tailwind utilities;）。
3. 重启开发服务器。