What makes 宝塔面板 notable?

1.7K downloads. Trust evidence available

How should 宝塔面板 be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

宝塔面板

宝塔面板 Skill，让 AI Agent 调用宝塔面板能力，管理网站、文件、数据库、Docker、计划任务及服务器环境，完成状态查询、故障排查和安全检查等日常运维操作；支持自动部署宝塔面板与 MCP 服务，并接入 Claude Code、Codex、Cursor、WorkBuddy 等 AI Agent。当用户需要通过 AI 管理服务器、安装宝塔面板或配置宝塔 MCP 服务时使用。

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

1.7k

Updated

Oct 10, 2026

Version

1.0.5

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1.7K downloads reported by the source. Last updated 10/10/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 10, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 10, 2026
Adoption signal: 1.7K downloadsadoption · observed Oct 10, 2026
Latest release: 1.0.5release · observed Aug 21, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s170gq9pc2mwwz5578zzf0kr4s83ngvs:btpanel

Install using `clawhub skill install s170gq9pc2mwwz5578zzf0kr4s83ngvs:btpanel` in an isolated environment before connecting it to live workloads.
No published capability contract is available yet, so validate auth and request/response behavior manually.
Review the upstream CLAWHUB listing at https://clawhub.ai/aapanel/btpanel before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-aapanel-btpanel/snapshot"

Documentation

CLAWHUB

149,259 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

assets/bt-skills/bt-go-project-deploy/SKILL.md

---
name: bt-go-project-deploy
description: >
  在宝塔面板上部署 Go 项目（编译好的二进制，含 Go SDK 版本安装、项目注册、进程启停、域名/外网映射），
  并在项目启动失败时排错。当用户要求把本机编译好的 Go 二进制部署成面板可管理的项目（含 Go SDK 安装、
  端口/运行用户配置、域名绑定），或 Go 项目启动失败/访问异常需要排查根因时使用。
  触发关键词：部署 Go、Go 项目、go build 产物部署、Go 二进制、Gin/Beego/Echo 服务、Go SDK 安装、
  go1.xx、GOPROXY、Go 项目启动失败、error while loading shared libraries、Address already in use。
  日常的启停/状态/日志/改配置/删项目等简单操作不依赖本 SOP，直接按工具描述调用即可。
---

# Go 项目部署与启动排错 SOP

> **停止。执行任何操作前，必须完整阅读本文档。**
> 本 Skill 的工具均指 bt_agent_mcp 插件暴露的 MCP 工具；同一能力在宝塔 AI 内置端可能有不同命名，按当前环境可用工具调用。
> 本 SOP 只覆盖两个主场景：**① 部署 Go 项目（含 Go SDK 安装）；② 项目启动排错**。其他简单操作（状态查看、启停、日志、域名、改配置、删除）不做 SOP，直接使用工具。

---

## 核心规则

1. **先只读侦察，再执行变更** —— 部署前先 `GoProjectInfo` 查是否已存在同名项目、`GoVersion(action=list)` 看 SDK；排错先读日志，不盲目重启。
2. **Go 是编译产物，无源码分析** —— `GoProjectCreate` 不需要分析步骤：给二进制绝对路径 + 端口 + 启动命令（缺省=二进制）直接注册。**不提供 analyze_only。**
3. **Go SDK 安装走 Bash 后台** —— btpygvm 装的是完整预编译包（快），但网络慢仍可能超时：`GoVersion(action=install, version=...)` 返回 `install_command` 后，必须用 `Bash(command=install_command, run_in_background=true)` 后台执行 + `BashStatus(task_id, wait=true)` 轮询；**一次只装一个版本**。
4. **创建即同步启动** —— `GoProjectCreate` 注册后面板同步启动（nohup 脚本 + pid，**无守护、崩了不自愈**）；创建成功 ≠ 进程一定活着，必须 `GoProjectInfo` 核验 `run=true` + 端口在 `listen`。
5. **Go 项目是编译二进制** —— 缺动态库/权限/端口占用是启动失败主因，排错按日志对号入座（场景二）。
6. **改配置即重启** —— `GoProjectModify(action='config')` 面板改完自动 stop+start；改端口后若绑了域名，nginx 反代按新端口重写。
7. **每个任务最多调用 15 次工具**，超出后汇总当前发现并停止。
8. **禁止操作**：删除项目目录/二进制源码、`rm -rf` 项目目录、修改宝塔/插件自身文件、读取插件 `data/` 凭据。

---

# 场景一：部署 Go 项目

## Step 0 —— 预检
1. 确认任务确为"部署 Go 项目"（非排错/运维）。
2. 确认有编译好的**可执行二进制**（`go build` 产物，Linux 目标平台），拿到绝对路径。
3. 确认**端口**（应用监听，10-65535）与**运行用户**（默认 www）。
4. 需要外网域名访问时，确认 Nginx 已安装；否则只能本机/内网访问。

## Step 1 —— Go SDK 确认 / 安装
1. `GoVersion(action='list')`：看 `data.installed` 是否已有可用 Go、`data.used` 当前版本。
2. 没有可用版本 → `GoVersion(action='list')` 的 `data.available` 挑一个稳定版（每项含 `install_command`），再调 `GoVersion(action='install', version=<go1.xx>)` 拿该版本的 install_command。
3. **用 Bash 后台执行**：`Bash(command=<install_command>, run_in_background=true)` → 得到 task_id → `BashStatus(task_id, wait=true)` 轮询到完成（预编译包下载+解压，通常几十秒到几分钟）。
4. 完成后 `GoVersion(action='list')` 确认该版本在 `installed`；需要时 `GoVersion(action='use', version=...)` 切换当前版本；拉依赖慢可 `GoVersion(action='goproxy', goproxy=<源>)` 设置 GOPROXY。

## Step 2 —— 创建项目（注册 + 启动）
调用 `GoProjectCreate(project_name=..., project_exe=<二进制绝对路径>, port=<端口>, ...)`：
- **必填**：`project_name`（字母/数字/下划线）、`project_exe`、`port`。
- **可选**：`project_cmd`（缺省=二进制本身）、`run_user`（默认 www）、`domains`（给则自动开启外网映射，'域名' 或 '域名:端口'）、`env_list`（`[{"k","v"}]`，如 `[{"k":"PORT","v":"9000"}]`，**字符串 "K=V" 会被 schema 拒**）、`env_file`、`is_power_on`（默认 true）、`ps`、`release_firewall`（需外网访问时 true）。

> 返回"创建成功"= 已注册并尝试启动；`data.project` 含 run/listen 运行态。

## Step 3 —— 启动验证（强制）
1. `GoProjectInfo(project_name=...)`：`run=true`、端口在 `listen`。
2. 用返回的 `log_files` 里应用日志路径（`/www/wwwlogs/go/<name>.log`）调 filesystem `Read` 看尾部无致命异常（`error while loading shared libraries`/`Address already in use`/`bind: addre

assets/bt-skills/bt-html-project-deploy/SKILL.md

---
name: bt-html-project-deploy
description: >
  在宝塔面板上管理 Html(静态)项目：创建静态站点（域名 + 网站根目录）、把前端构建产物部署到站点目录、
  编辑伪静态 rewrite 配置（SPA try_files / 自定义 location / 缓存）、改域名/网站根目录/运行目录/启停，
  并在静态站点访问异常（404 / SPA 刷新 404 / 伪静态不生效 / 目录权限）时排错。
  当用户要求把前端静态页面（HTML/SPA/单页应用）挂到域名上，或静态站点访问异常需要排查时使用。
  触发关键词：静态网站、HTML项目、部署前端、SPA、单页应用、伪静态、rewrite、运行目录、静态站 404、
  SPA 404、BT-Html-Project-Deploy。
  日常的查看/启停/改备注等简单操作不依赖本 SOP，直接按工具描述调用即可。
---

# Html(静态)项目运维 SOP

> **停止。执行任何操作前，必须完整阅读本文档。**
> 本 Skill 的工具均指 bt_agent_mcp 插件暴露的 MCP 工具；同一能力在宝塔 AI 内置端可能有不同命名，按当前环境可用工具调用。
> 本 SOP 覆盖三个主场景：**① 创建静态项目；② 配置编辑（伪静态 rewrite / 主 conf）；③ 静态站点访问异常排错**。其他简单操作（状态查看、启停、改备注、绑删域名、改目录、运行目录、删除）不做 SOP，直接使用工具。

---

## 核心规则

1. **先只读侦察，再执行变更** —— 操作前先 `HtmlProjectInfo`（site_name 留空）列项目找到站点名（可能带 `_<端口>` 后缀），再 `HtmlProjectInfo(site_name=...)` 看当前域名/路径/运行目录/SSL；排错先读日志，不盲目重写配置。
2. **静态站点本质 = 网站根目录 + nginx/apache conf + rewrite 文件** —— nginx 主 conf 在 `/www/server/panel/vhost/nginx/html_<name>.conf`（模板渲染产物），**伪静态 rewrite 文件在 `/www/server/panel/vhost/rewrite/html_<name>.conf`（面板官方自定义配置入口，被主 conf include）**。
3. **改配置优先写 rewrite 文件** —— SPA `try_files`、自定义 `location`、静态资源缓存等写 rewrite 文件（面板创建的注释即引导"请将伪静态规则或自定义NGINX配置填写到此处"）；**只有确实要改 listen/root/自定义 server 段才动主 conf，且改前必须 filesystem `Read` 留基线**（面板 SSL/域名/改目录操作会重写覆盖主 conf）。
4. **域名/路径/启停/运行目录走 `HtmlProjectModify`** —— 面板方法同步 domain 表与 nginx/apache server_name；**不要用 filesystem 直接改主 conf 来加域名**，会与面板不同步。
5. **创建即生效** —— `HtmlProjectCreate` 成功即写 nginx/apache 配置 + 建目录（目录不存在自动创建）+ 非 80 端口放行防火墙 + 重载服务；返回的 `site_name_hint` 仅供参考，**实际站点名以 `HtmlProjectInfo` 列表返回的 name 为准**（主域名重名会带 `_<端口>`）。
6. **每个任务最多调用 15 次工具**，超出后汇总当前发现并停止。
7. **禁止操作**：`rm -rf` 站点根目录外的路径、修改宝塔/插件自身文件、读取插件 `data/` 凭据、直接写 nginx 主 conf 来改域名（走 Modify）。

---

# 场景一：创建静态项目

## Step 0 —— 预检
1. 确认任务确为"创建 Html(静态)项目"。
2. 拿到**要对外暴露的域名**（可带 `:端口`，非 80 端口会成为监听端口）与**网站根目录**（绝对路径，目录不存在会自动创建；也可指向已有前端目录）。
3. 确认 Nginx/Apache 已安装（静态站依赖 web 服务）。

## Step 1 —— 调用创建
`HtmlProjectCreate(domains=[...], path=...)`：
- **必填**：`domains`（list，首项为主域名，如 `'example.com'` 或 `'example.com:8080'`）、`path`（网站根目录绝对路径，如 `/www/wwwroot/demo.example.com`）。
- **可选**：`ps`（备注）、`type_id`（项目分类，默认 0）。

> 返回"创建成功"= 已写 nginx/apache 配置 + 建目录 + 放行端口 + 重载。`site_name_hint` 仅供参考。

## Step 2 —— 部署静态文件
1. 把前端构建产物（如 `dist/` 下文件）上传到站点根目录 `path`：
   - 文件已在本机：用文件上传（PrepareUpload 分块上传）到站点目录，或用 filesystem 移动。
   - 远端构建：先下载到本机再上传，或直接把站点 `path` 指到已有构建目录。
2. 确认 `index.html` 已在根目录（或运行目录，见场景二 set_run_path）。

## Step 3 —— 验证（强制）
1. `HtmlProjectInfo`（site_name 留空）确认站点出现，记下真实 `name`。
2. `HtmlProjectInfo(site_name=...)` 看域名/路径/SSL。
3. 访问域名验证首页正常返回。

- 全通过 → 按"完成汇报"收尾。
- 访问异常 → 转场景三排错。

---

# 场景二：配置编辑（伪静态 rewrite / 主 conf）

## Step 0 —— 拿基线与现状
1. `HtmlProjectInfo(site_name=...)`：拿到 `rewrite_file`（伪静态/自定义入口）、`config_file`（nginx 主 conf）、`apache_config_file` 路径，以及当前域名/路径/运行目录。
2. filesystem `Read` `rewrite_file` 与 `config_file` 看当前配置。

## Step 1 —— 改配置（优先 rewrite 文件）
按「常用静态站点 nginx 配置速查」（见文末）在 **rewrite 文件*

assets/bt-skills/bt-java-project-deploy/SKILL.md

---
name: bt-java-project-deploy
description: >
  在宝塔面板上部署 Java jar 项目（Spring Boot），并在项目启动失败时排错。
  当用户要求把本机已有的 jar 包部署成面板可管理的 Java 项目（含 JDK、Nginx 代理/域名），
  或 Java 项目启动失败/访问异常需要排查根因时使用。
  触发关键词：部署 Java、jar 包部署、Spring Boot 部署、Java 项目创建、
  Java 项目启动失败、jar 起不来、jar 启动报错、502、访问异常、JDK 版本不匹配。
  日常的启停/状态/日志/改配置等简单操作不依赖本 SOP，直接按工具描述调用即可。
---

# Java 项目部署与启动排错 SOP

> **停止。执行任何操作前，必须完整阅读本文档。**
> 本 Skill 的工具均指 bt_agent_mcp 插件暴露的 MCP 工具；同一能力在宝塔 AI 内置端可能有不同命名，按当前环境可用工具调用。
> 本 SOP 只覆盖两个主场景：**① 部署 Java 项目；② 项目启动排错**。其他简单操作（状态查看、启停、日志、域名、改配置、删除）不做 SOP，直接使用工具。

---

## 核心规则

1. **先只读侦察，再执行变更** —— 部署前必须完成 jar 分析；排错先读日志，不盲目重启。
2. **创建后必须验证启动** —— "创建成功"不算完，必须确认进程存活 + 监听端口 + 日志无致命错误；验证失败即转入场景二。
3. **删除项目属高风险**，必须先获得用户明确确认；启停/重启/改配置属中风险，操作前说明影响。
4. **JDK 匹配** —— Spring Boot 3.x 需 JDK 17+，Boot 2.x 需 JDK 8/11；安装或切换前先检测本机 JDK。
5. **端口唯一性** —— 创建/改端口前检查占用。
6. **域名可访问 = 三件事** —— ① `add_domain` 写入 `server_name`；② `bind_extranet` 开启外网框架（生成 conf 骨架，**不含反代**）；③ `add_proxy(proxy_port=应用端口)` 真正注入 `proxy_pass http://127.0.0.1:port`。**漏掉 ③ 会访问 403**。创建时带 `domains` 会完成 ①② 并尝试自动建 ③，但**必须验证**（`proxy_list` 或 grep `proxy_pass`），缺失即补 `add_proxy`。
7. **每个任务最多调用 15 次工具**，超出后汇总当前发现并停止。
8. **禁止操作**：删除 jar 源文件、`rm -rf` 项目目录、修改宝塔/插件自身文件、读取插件 `data/` 凭据。

---

# 场景一：部署 Java 项目

## Step 0 —— 预检
1. 确认任务确为"部署新 Java 项目"（非排错/运维）。
2. 需要外网域名访问时，确认 Nginx 已安装；否则只能本机/内网访问。
3. （可用 todo 工具时）建任务列表：定位 jar → 分析 → JDK → 创建 → 验证。

## Step 1 —— 定位 jar 包
- 用户直接给出 jar 绝对路径，或：
- 用文件工具 `Glob(pattern='**/*.jar')` / `LS(path=...)` 在服务器上定位 jar（排除运行目录与 `lib/` 依赖库）。
- **校验**：路径存在、是普通文件、非敏感目录（`/etc`、`/boot`、插件 `data/` 等）。
- 记录 jar 绝对路径与所在目录（jar_path）。

## Step 2 —— 分析 jar（部署前必须）
调用 `JavaProjectCreate(jar_path=..., analyze_only=true)`（只读，不创建）。返回：
1. 是否 Spring Boot 可执行 jar（jar_info）。
2. **应用端口**（`application.yml/properties` 的 `server.port`，或命令行/环境变量覆盖）。
3. 实际生效的配置文件路径与优先级（config_files）。
4. **启动前隐患清单**（tips：数据库/中间件连通性、账号密码疑似错误、profile 缺失等）。

**决策**：
- 解析不出端口 → 询问用户指定，并在创建时显式传 `port`。
- 隐患清单含阻断级（error）→ 向用户说明，确认是否继续。

## Step 3 —— JDK 确认 / 安装
1. `JavaJdk(action='list')` 检测本机 JDK（name/path/operation：0 未装 1 已装 2 系统 3 安装中）。
2. 按 Spring Boot 版本定所需 JDK（Boot3→17+，Boot2→8/11）。
3. 已有 → 记录 path；无 → 询问用户后 `JavaJdk(action='install', version=...)`（异步，用 list 轮询 operation=3→1）。

## Step 4 —— 创建项目（注册）
调用 `JavaProjectCreate(project_name=..., jar_path=..., port=..., [domains=...])`。
创建前确认参数：`project_name`（1-20 字符、不重复）、jar 路径、JDK 路径（缺省自动选已装）、`run_user`（默认 www）、端口（**检查未被占用**）、启动命令（缺省自动拼 `{jdk}/bin/java -jar ... --server.port=<port>`）。
**外网映射决策**：
- 要域名访问 → `domains=['域名']`（或 `['域名:端口']`），创建时绑定域名并开启外网框架（`server_name`）。创建工具会**尝试**自动建反代（`proxy_path` 默认 `'/'` 全站，可改如 `'/api'`；`proxy_path=''` 关闭）。
  **创建后必须验证反代已注入**：`JavaProjectModify(action='proxy_list')` 应有 `proxy_port`，或 grep `proxy_pass` `java_<name>.conf`。缺失 → `JavaProjectModify(action='add_proxy', proxy_port=应用端口, proxy_dir='/')` 补齐，否则访问 403。
- 仅本机 → 不传 domains（`bind_extranet=0`）。

## Step 5 —— 启动验证（强制）
创建后调用 `JavaProjectInfo(project_name=...)` 依次确认：
1. 进程存活（有 pid）。
2. 应用端口在 `listen` 列表。
3. 用返回

assets/bt-skills/bt-node-project-deploy/SKILL.md

---
name: bt-node-project-deploy
description: >
  在宝塔面板上部署 Node.js 项目（nodejs/general/pm2 三种类型，含 Nginx 域名/反代），
  并在项目启动失败或访问异常时排错。
  当用户要求把本机已有的 Node 项目目录部署成面板可管理的项目（含 node 版本、依赖安装、
  Nginx 代理/域名、pm2 守护），或 Node 项目启动失败/访问异常需要排查根因时使用。
  触发关键词：部署 Node、Node 项目部署、nodejs 部署、npm 项目部署、PM2 部署、
  Node 项目启动失败、npm 起不来、Node 报错、502、访问异常、pm2 errored、Cannot find module。
  日常的启停/状态/日志/改配置等简单操作不依赖本 SOP，直接按工具描述调用即可。
---

# Node.js 项目部署与启动排错 SOP

> **停止。执行任何操作前，必须完整阅读本文档。**
> 本 Skill 的工具均指 bt_agent_mcp 插件暴露的 MCP 工具；同一能力在宝塔 AI 内置端可能有不同命名，按当前环境可用工具调用。
> 本 SOP 只覆盖两个主场景：**① 部署 Node 项目；② 启动排错**。其他简单操作（状态查看、启停、日志、域名、改配置、删除）不做 SOP，直接使用工具。

---

## 核心规则

1. **先只读侦察，再执行变更** —— 部署前必须完成项目分析；排错先读日志，不盲目重启。
2. **创建后必须验证启动** —— "创建成功"不算完，必须确认进程存活 + 监听端口 + 日志无致命错误；验证失败即转入场景二。
3. **删除项目属高风险**，必须先获得用户明确确认；启停/重启/改配置属中风险，操作前说明影响。
4. **Node 版本匹配** —— 创建前用 `NodeVersion(action='list')` 检测已装版本；`package.json` 的 `engines.node` 不符时优先换已装版本或安装。
5. **端口唯一性** —— 创建/改端口前检查占用；**绑外网必须有端口**（`bind_extranet` 依赖 `port`）。
6. **绑域名 = 自动反代** —— Node 的反代由 nginx 模板按 `project_config.port` 自动生成（`proxy_pass http://127.0.0.1:{port}`），**无独立反代步骤**。访问异常时核对：`NodeProjectInfo` 的 `listen`（实际监听端口）vs 配置端口（反代目标）是否一致，不一致 = 502。
7. **依赖先行** —— nodejs 类型缺 `node_modules` 启动必失败。创建时 `install_deps=true` 或创建后装依赖再启动。
8. **每个任务最多调用 15 次工具**，超出后汇总当前发现并停止。
9. **禁止操作**：删除项目目录/源码、`rm -rf` 项目目录、修改宝塔/插件自身文件、读取插件 `data/` 凭据。

---

# 场景一：部署 Node 项目

## Step 0 —— 预检
1. 确认任务确为"部署新 Node 项目"（非排错/运维）。
2. 确定**项目类型**：`nodejs`（package.json scripts）/ `general`（直接指定启动文件）/ `pm2`（守护+cluster+自愈）。
3. 需要外网域名访问时，确认 Nginx 已安装；否则只能本机/内网访问。

## Step 1 —— 定位项目目录
- 用户给出 `project_cwd`（项目根，含 package.json），或：
- 用文件工具 `Glob(pattern='**/package.json')` / `LS(path=...)` 定位（排除 `node_modules`、`dist`、`build` 等构建目录）。
- **校验**：目录存在、含 `package.json`（nodejs/pm2 必需；general 可没有）、非敏感目录（`/etc`、`/boot`、插件 `data/` 等）。

## Step 2 —— 分析项目（部署前必须）
调用 `NodeProjectCreate(project_cwd=..., analyze_only=true)`（只读，不创建）。返回：
1. `package.json` 的 `name/version`、`engines.node`、`dependencies` 数量。
2. `scripts` 启动项列表（nodejs 类型的 `project_script` 从这里选）。
3. `node_modules` 是否存在（缺 → 需先装依赖）。
4. `port`/`port_hints`：从入口文件启发式探测的端口（仅供参考）。

**决策**：
- nodejs 类型：确认启动脚本名（`start`/`dev`/自定义），即 `project_script`。
- pm2 类型：确认入口文件（js 或 ecosystem 配置）与 `cluster` 实例数。
- 无端口或启发式不准 → 询问用户，创建时显式传 `port`（绑外网必需）。

## Step 3 —— Node 版本确认 / 安装
1. `NodeVersion(action='list')` 检测已装版本与可用包管理器（npm/yarn/pnpm）。
2. 若返回 `plugin_installed=false`：nodejs 版本管理器插件未装，**先调 `SoftwareInstall(name='nodejs')` 安装插件**（可再用 `SoftwareList(name='nodejs')` 查进度），装完继续。
3. 需要新装版本时，用 `NodeVersion(action='online', lts_only=true, page=...)` 浏览可安装版本（按版本从新到旧排序、本地分页，`lts_only=false` 看全部；每项 `installed` 标记是否已装），从中挑选稳定版。
4. 对照 `engines.node`（无则默认 LTS）。
5. 已装 → 记录版本号（如 `v20.15.0`）；无 → 询问用户后 `NodeVersion(action='install', version=..., install_pm2=<pm2 类型时 true>)`（插件安装，较慢，装完用 list 确认）。

## Step 4 —— 创建项目（注册）
调用 `NodeProjectCreate(project_type=..., project_name=..., project_cwd=..., nodejs_version=..., ...)`。
按类型传参：
- **nodejs**：`project_script`（scripts key，如 `'start'`

assets/bt-skills/bt-python-project-deploy/SKILL.md

---
name: bt-python-project-deploy
description: >
  在宝塔面板上部署 Python 项目（uwsgi/gunicorn/command 三种运行方式，含虚拟环境配置、
  Python 版本安装、requirements 依赖、Nginx 域名/反代），并在环境准备或启动失败时排错。
  当用户要求把本机已有的 Python 项目目录部署成面板可管理的项目（含 Python 版本安装、
  虚拟环境创建、pip 依赖、uwsgi/gunicorn 托管或自定义命令启动），或 Python 项目
  启动失败/访问异常/环境准备失败需要排查根因时使用。
  触发关键词：部署 Python、Python 项目部署、django/flask/fastapi/sanic 部署、
  uvicorn/gunicorn/uwsgi、虚拟环境 venv、pip install、Python 项目启动失败、
  ImportError、ModuleNotFoundError、502、访问异常、celery、关联进程、requirements。
  日常的启停/状态/日志/改配置/装包等简单操作不依赖本 SOP，直接按工具描述调用即可。
---

# Python 项目部署与启动排错 SOP

> **停止。执行任何操作前，必须完整阅读本文档。**
> 本 Skill 的工具均指 bt_agent_mcp 插件暴露的 MCP 工具；同一能力在宝塔 AI 内置端可能有不同命名，按当前环境可用工具调用。
> 本 SOP 只覆盖两个主场景：**① 部署 Python 项目；② 环境准备/启动排错**。其他简单操作（状态查看、启停、日志、域名、改配置、装包、删除）不做 SOP，直接使用工具。

---

## 核心规则

1. **先只读侦察，再执行变更** —— 部署前必须完成项目分析；排错先读日志，不盲目重启。
2. **创建成功 ≠ 启动成功** —— Python 创建项目后环境准备（装依赖+生成启动脚本+尝试启动）是**后台异步**的。必须用 `PythonProjectInfo` 轮询 `prep_status` 到 `complete`，再核验进程存活 + 监听端口 + 日志无致命错误；`prep_status=failure` 立即转场景二。**这是本场景最容易栽的坑。**
3. **建项目前必须有虚拟环境** —— 面板要求 `python_bin` 是已托管的 venv/conda（`can_use_directly`）。部署顺序：版本 → 环境 → 项目。
4. **Python 版本安装走 Bash 后台** —— 源码编译极慢（10-30 分钟），不得用同步工具卡住；必须 `Bash(run_in_background=true)` + `BashStatus` 轮询。
5. **删除项目保留虚拟环境** —— venv 与项目非强绑定（可复用/共享），删除不删 venv（面板语义）；如需移除单独用 `PythonEnv(action='remove')`。删除本身仍高风险（停进程/清配置/删记录），先确认。
6. **绑域名 = 外网映射 + 反代** —— `add_domain` 只写域名，需 `bind_extranet` 生成 nginx 配置（proxy 到 127.0.0.1:port）；path→port 反代（`add_proxy`）**必须先开启外网映射**。
7. **每个任务最多调用 15 次工具**，超出后汇总当前发现并停止。
8. **禁止操作**：删除项目目录/源码、`rm -rf` 项目目录、修改宝塔/插件自身文件、读取插件 `data/` 凭据。

---

# 场景一：部署 Python 项目

## Step 0 —— 预检
1. 确认任务确为"部署新 Python 项目"（非排错/运维）。
2. 确定**运行方式 `stype`**：`uwsgi` / `gunicorn` / `command`（直跑，python 文件方式已并入 command）。
3. 确认**协议**：`wsgi`（Flask/Django 传统）/ `asgi`（FastAPI/Sanic/uvicorn）。
4. 需要外网域名访问时，确认 Nginx 已安装；否则只能本机/内网访问。

## Step 1 —— 定位项目目录
- 用户给出 `project_path`（项目根，含 `*.py`），或：
- 用文件工具 `Glob(pattern='**/*.py')` / `LS(path=...)` 定位（排除 `node_modules`、`dist`、`.venv`、`venv` 等）。
- **校验**：目录存在、含入口 `*.py`（或 `requirements.txt`）、非敏感目录（`/etc`、`/boot`、插件 `data/` 等）。

## Step 2 —— 分析项目（部署前必须）
调用 `PythonProjectCreate(project_path=..., analyze_only=true)`（只读，不创建）。返回：
1. `framework`：django/flask/sanic/fastapi 等（按 requirement/入口代码识别）。
2. `runfile`：入口文件、`xsgi`（wsgi/asgi）、`call_app`（可调用对象名）。
3. `requirement_path`：requirements 文件（缺 → 需先补）。
4. `has_venv` / `port` / `port_hints`：目录是否自带 venv、启发式端口（仅供参考）。

**决策**：
- 选 `stype`：Django/Flask 传统 → `gunicorn`（或 `uwsgi`）；FastAPI/Sanic → `gunicorn` + `xsgi='asgi'`；无框架/自写 socket → `command`（`project_cmd='{python_bin} -u {runfile} {parm}'`）。
- 确认 `rfile`（启动文件绝对路径）与 `call_app`（app/application，或自动探测）。
- 无端口或启发式不准 → 询问用户，创建时显式传 `port`（uwsgi/gunicorn 必填；command 可空）。

## Step 3 —— Python 版本确认 / 虚拟环境准备
1. `PythonVersion(action='list')` 查看已装 Python 版本与当前默认；返回含 `install_hint`。
2. 需要新版本时 `PythonVersion(action='online', ...)` 浏览可安装版本（每项含 `install_command`），**用 Bash 后台安装**：
   - `Bash(command=<install_command>, run_in_background

Github ReposUpdated 9h agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.