跳到主要内容
版本：latest

宝塔面板 Skill 安装与使用指引

宝塔面板 Skill 是面向 AI Agent 的安全运维编排工具。它告诉 Agent 应该如何安装和接入宝塔 MCP、如何调用面板能力，以及在执行服务器变更时应遵循哪些检查、确认和验证步骤。

Skill 与 MCP 的关系

MCP 和 Skills 在技术上相互独立，并不是所有 Skill 都依赖 MCP。当前宝塔面板 Skill 选择使用宝塔 MCP 执行面板操作：如果尚未配置 MCP，它会指导 Agent 完成部署和接入；如果已经配置 MCP，它会指导 Agent 安全、准确地调用相关工具。

因此，只配置宝塔 MCP 也可以使用面板工具；安装 Skill 的主要价值是补充标准化的部署、接入、操作和排障流程。仅安装 Skill 并不会让 Agent 自动获得面板访问能力，实际管理面板前仍需完成 MCP 接入。

可以完成哪些任务​

宝塔面板 Skill 会根据当前环境选择工作方式：

  1. 已经配置宝塔 MCP：通过 MCP 查询或管理网站、文件、数据库、Docker、计划任务和服务器环境，并辅助完成故障排查与安全检查。
  2. 已经安装宝塔面板，但尚未配置 MCP：协助部署和初始化宝塔 MCP，再接入当前 Agent。
  3. 尚未安装宝塔面板：在用户确认后，先安装宝塔面板，再部署 MCP 并完成 Agent 接入。

涉及安装面板、升级运行环境、开放端口或写入 Agent 配置等操作时，Agent 应先说明目标和影响，并在获得确认后执行。

安装前准备​

开始前，请确认：

  • 当前 AI Agent 支持 Agent Skills
  • 使用命令行安装时，本机已安装 Node.js 和 npm
  • 如果需要自动部署面板或 MCP，Agent 可以连接目标服务器并获得所需的管理员权限
  • 生产环境的重要网站、数据库和配置已经备份

仅安装 Skill 不会直接修改宝塔面板或服务器；只有在后续向 Agent 下达部署或运维任务并确认执行后，才会产生服务器变更。

方式一：通过 SkillHub 提示词安装（推荐）​

将以下提示词完整发送给需要接入的 AI Agent：

请根据 https://skillhub.cn/install/skillhub.md，安装 @btpanel/btpanel。

Agent 会先按照 SkillHub 的说明准备安装环境，再安装宝塔面板 Skill。安装过程中如果 Agent 请求执行命令或写入 Skills 目录，请核对安装来源和目标目录后再授权。

可在 SkillHub 上的宝塔面板 Skill 查看技能介绍。

方式二：下载 Skill 压缩包​

  1. 打开 SkillHub 上的宝塔面板 Skill
  2. 下载页面提供的 Skill 压缩包
  3. 按照目标 Agent 的 Skill 导入方式选择或解压该文件
  4. 重启或刷新 Agent 会话，确认 btpanel Skill 已被识别

不同 Agent 的导入入口和 Skills 目录可能不同，请以对应 Agent 的说明为准。不要直接用整个压缩包覆盖已有的 Skills 目录。

方式三：通过 Skills CLI 安装​

在终端中执行：

npx skills add aaPanel/btpanel-skills

Skills CLI 会检测支持的 Agent，并提示选择安装目标和使用范围。安装完成后，重启或刷新 Agent 会话。

源码和版本信息可在 aaPanel/btpanel-skills 查看。

验证安装结果​

新建一个 Agent 任务并发送：

检查是否已经识别 btpanel Skill，只说明它能做什么，不要连接服务器或执行任何变更。

如果 Agent 能识别 btpanel 并说明其能力，即表示主 Skill 已安装成功。

接下来可以根据实际场景继续操作：

  • 已配置 MCP：让 Agent 执行服务器状态查询等只读任务
  • 未配置 MCP：让 Agent 先输出宝塔 MCP 部署与接入计划
  • 需要专项能力：让 Agent 列出配套 Skills，再选择需要的项目部署或排障 Skill 安装

配套 Skills​

主 Skill 内置以下配套 Skills。它们用于补充具体场景的标准操作流程，可按需安装，不建议未经确认一次性覆盖 Agent 中已有的同名技能。

Skill主要用途
bt-go-project-deploy部署 Go 二进制项目，安装 Go SDK，并排查启动或访问异常
bt-html-project-deploy部署 HTML、前端构建产物和 SPA，管理伪静态与访问异常
bt-java-project-deploy部署 Spring Boot JAR、配置 JDK 和反向代理，并排查启动问题
bt-node-project-deploy部署 Node.js 或 PM2 项目，管理依赖、域名和启动排障
bt-python-project-deploy部署 Django、Flask、FastAPI 等 Python 项目，管理虚拟环境和依赖
bt-reverse-proxy创建和管理 Nginx 反向代理规则，排查 502、404 等问题
bt-website-troubleshoot诊断网站无法访问、服务启动失败和常见 HTTP 错误

可以向 Agent 发送类似指令：

列出 btpanel 主 Skill 中提供的配套 Skills，只安装 Python 项目部署 Skill，安装前先告诉我目标目录和影响。

首次使用建议​

安装和接入完成后，建议先执行只读任务：

查看服务器、网站和服务的当前状态，只读取信息，不要修改配置。

确认返回结果与目标服务器一致后，再逐步尝试部署或修改操作。涉及删除资源、修改防火墙、重启服务、安装软件或升级运行环境时，应保留人工确认。

安全注意事项​

  • 默认先查询再变更，诊断任务不应自动实施修复
  • 不在聊天、命令、日志或仓库中公开密码、Token、私钥和连接串
  • 公网 MCP 应使用客户端信任且覆盖访问地址的有效 TLS 证书
  • MCP 白名单仅填写 Agent 实际需要的 IP 或最小 CIDR，不要使用 *
  • 安装面板或 MCP 前，确认目标服务器、管理员权限、执行影响和回退方式
  • 安装包校验失败、SSH 主机指纹变化或 TLS 校验失败时，应停止执行而不是绕过检查

相关文档​