---
title: "宝塔面板 Skill 安装与使用指引"
description: "介绍宝塔面板 Skill 的作用、与宝塔 MCP 的关系，以及通过 SkillHub、压缩包或 Skills CLI 安装和验证的方法。"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.bt.cn/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

:::info 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：

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

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

可在 [SkillHub 上的宝塔面板 Skill](https://skillhub.cn/skills/btpanel/btpanel) 查看技能介绍。

## 方式二：下载 Skill 压缩包

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

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

## 方式三：通过 Skills CLI 安装

在终端中执行：

```bash
npx skills add aaPanel/btpanel-skills
```

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

源码和版本信息可在 [aaPanel/btpanel-skills](https://github.com/aaPanel/btpanel-skills) 查看。

## 验证安装结果

新建一个 Agent 任务并发送：

```text
检查是否已经识别 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 发送类似指令：

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

## 首次使用建议

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

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

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

## 安全注意事项

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

## 相关文档

- [Agent 接入宝塔 MCP 与使用 Skills](/ai-ops/agent/panel-integration)
- [宝塔 MCP 安装指引](/ai-ops/mcp/installation)
- [使用 Codex 接入宝塔 MCP](/ai-ops/agent/panel-integration/codex-mcp)
- [使用 WorkBuddy 接入宝塔 MCP](/ai-ops/agent/panel-integration/workbuddy-mcp)
- [使用 Claude Code 接入宝塔 MCP](/ai-ops/agent/panel-integration/claude-code-mcp)
- [使用 TRAE 接入宝塔 MCP](/ai-ops/agent/panel-integration/trae-mcp)
- [使用 DeepSeek Harness 接入宝塔 MCP](/ai-ops/agent/panel-integration/deepseek-harness-mcp)
- [通过 Hermes 与 OpenClaw 消息通道接入宝塔 MCP](/ai-ops/agent/panel-integration/hermes-openclaw-mcp)

Source: https://docs.bt.cn/ai-ops/agent/panel-integration/skill-installation/index.mdx