aapanel/btpanel_files

宝塔面板文件管理

宝塔面板服务器文件操作工具，提供远程文件/目录浏览、读取、编辑、创建、删除、权限管理等基本文件操作能力。

图标资源

技能包提供以下图标文件，可在生成报告时引用：

| 文件 | 格式 | 用途 | |------|------|------| | icon/bt-logo.svg | SVG | 矢量图标，适合缩放 |

AI 使用约束

本技能用于查询和修改服务器文件，AI 应遵循以下原则：

1. 操作前确认：修改文件前先读取文件内容，确认修改范围
2. 执行前告知：文件操作会影响服务器状态，AI 应先向用户简述即将执行的操作步骤
3. 谨慎删除：删除文件/目录前需告知用户，并确认目标路径
4. 隐私保护：不主动读取敏感文件（如 /etc/shadow、.env、config.php 等含密码的文件）
5. 备份建议：修改重要配置文件前，建议用户先备份

执行流程示例：

AI: 我将为您执行以下操作：
    1. 读取配置文件 /www/server/nginx/conf/nginx.conf
    2. 修改指定配置项
    3. 保存文件
    正在获取数据，请稍候...
    [执行命令]
    [展示结果和修改内容]

宝塔面板相关技能矩阵

当前宝塔面板技能包，共包含 3 个相互关联的技能：

| 技能名称 | 描述 | 依赖关系 | |---------------------|------|-----------------------------------| | btpanel | 运维监控技能 | ✅ 基础技能，主要用于资源监控、网站状态检查、服务状态检查等 | | btpanel-files | 文件管理技能 | ✅ 提供远程服务器文件辅助服务，可以读取文件列表和内容 | | btpanel-phpsite | PHP 网站管理技能 | ✅ 提供远程服务器 PHP 网站管理功能，能够部署和管理php网站 |

⚠️ 常见问题

问题 1: 配置文件不存在

错误：未找到配置文件
解决：运行 python3 bt-config.py add 添加服务器配置

问题 2: PYTHONPATH 未设置

# 运行脚本前需要设置
export PYTHONPATH=/path/to/btpanel-skills/src:$PYTHONPATH

检查命令

# 检查 bt_common 模块
python3 -c "from bt_common.bt_client import BtClient; print('✅ 模块正常')"

# 检查配置文件
ls -la ~/.openclaw/bt-skills.yaml

# 测试连接
python3 {baseDir}/scripts/monitor.py --server "你的服务器名"

---

服务器配置管理

重要: 没有服务器信息时需要先添加

本技能复用 btpanel 技能的配置系统，使用 bt-config.py 工具管理服务器：

# 查看帮助
python3 {baseDir}/scripts/bt-config.py -h

# 添加服务器
python3 {baseDir}/scripts/bt-config.py add -n prod-01 -H https://panel.example.com:8888 -t YOUR_TOKEN

# 列出服务器
python3 {baseDir}/scripts/bt-config.py list

# 删除服务器
python3 {baseDir}/scripts/bt-config.py remove prod-01

获取 API Token 的方法：

1. 登录宝塔面板
2. 进入「面板设置」->「API 接口」
3. 点击「获取 API Token」

重要提示 - SSL 证书验证配置： 添加服务器时，AI 应询问用户：

"您的宝塔面板是否使用了受信任的 SSL 证书（如 Let's Encrypt、商业 CA 证书）？"

• ✅ 是（受信任证书）→ 使用默认配置，无需额外参数
• ⚠️ 否（自签名证书）→ 添加 --verify-ssl false 参数

示例：

# 自签名证书场景
python3 {baseDir}/scripts/bt-config.py add -n prod-01 -H https://panel.example.com:8888 -t YOUR_TOKEN --verify-ssl false

# 受信任证书场景（默认）
python3 {baseDir}/scripts/bt-config.py add -n prod-01 -H https://panel.example.com:8888 -t YOUR_TOKEN

常用场景

场景一：查看目录文件列表

当用户需要查看服务器某个目录的内容时：

# 查看/www 目录
python3 {baseDir}/scripts/files.py ls /www

# 查看指定目录
python3 {baseDir}/scripts/files.py ls /www/server/nginx/conf

# 带分页查看
python3 {baseDir}/scripts/files.py ls /www/wwwlogs -p 2 -r 100

用户意图识别：

• "看看/www 目录下有什么" → 执行 files.py ls /www
• "查看 Nginx 配置文件目录" → 执行 files.py ls /www/server/nginx/conf
• "这个目录有哪些文件" → 执行 files.py ls 路径

场景二：读取文件内容

当用户需要查看文件内容时：

# 读取文件
python3 {baseDir}/scripts/files.py cat /www/test.txt

# 读取文件最后 50 行
python3 {baseDir}/scripts/files.py cat /www/logs/error.log -n 50

# 读取并显示文件信息
python3 {baseDir}/scripts/files.py cat /www/server/nginx/conf/nginx.conf -v

用户意图识别：

• "帮我看看这个文件内容" → 执行 files.py cat 路径
• "查看日志最后几行" → 执行 files.py cat 路径 -n 50
• "这个文件是什么编码" → 执行 files.py cat 路径 -v

场景三：编辑文件内容

当用户需要修改文件内容时：

# 直接修改文件内容
python3 {baseDir}/scripts/files.py edit /www/test.txt "新内容"

# 从本地文件读取内容并保存
python3 {baseDir}/scripts/files.py edit /www/test.txt -f ./local-file.txt

用户意图识别：

• "修改这个文件，加上 XXX" → 先读取文件，再执行 files.py edit
• "更新配置文件" → 先读取文件，确认后执行 files.py edit

重要：编辑文件前必须先读取原内容，确认修改范围后再保存。

场景四：创建目录/文件

当用户需要创建新目录或文件时：

# 创建目录
python3 {baseDir}/scripts/files.py mkdir /www/newdir

# 创建文件
python3 {baseDir}/scripts/files.py touch /www/test.txt

用户意图识别：

• "新建一个目录" → 执行 files.py mkdir 路径
• "创建一个空文件" → 执行 files.py touch 路径

场景五：删除文件/目录

当用户需要删除文件或目录时：

# 删除文件
python3 {baseDir}/scripts/files.py rm /www/test.txt

# 删除目录
python3 {baseDir}/scripts/files.py rmdir /www/olddir

用户意图识别：

• "删除这个文件" → 确认路径后执行 files.py rm 路径
• "清理这个目录" → 确认路径后执行 files.py rmdir 路径

重要：删除操作会将文件/目录移动到回收站，非永久删除。但操作前仍需用户确认。

场景六：查看/修改文件权限

当用户需要管理文件权限时：

# 查看文件权限
python3 {baseDir}/scripts/files.py stat /www/test.txt

# 修改文件权限
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt

# 修改权限并设置所有者
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt -u www -g www

# 递归修改目录权限
python3 {baseDir}/scripts/files.py chmod 755 /www/wwwroot -R

用户意图识别：

• "查看这个文件的权限" → 执行 files.py stat 路径
• "修改文件权限为 755" → 执行 files.py chmod 755 路径
• "把这个目录权限改对" → 确认正确权限后执行 files.py chmod

版本要求

• 宝塔面板: >= 9.0.0
• Python: >= 3.10

用法

查看目录列表

# 查看帮助
python3 {baseDir}/scripts/files.py -h

# 列出目录内容
python3 {baseDir}/scripts/files.py ls /www

# 指定页码和每页数量
python3 {baseDir}/scripts/files.py ls /www/wwwlogs -p 2 -r 100

# 指定服务器
python3 {baseDir}/scripts/files.py ls /www --server prod-01

读取文件

# 读取文件内容
python3 {baseDir}/scripts/files.py cat /www/test.txt

# 读取文件最后 N 行
python3 {baseDir}/scripts/files.py cat /www/logs/error.log -n 100

# 读取并显示详细信息
python3 {baseDir}/scripts/files.py cat /www/test.txt -v

编辑文件

# 直接指定内容
python3 {baseDir}/scripts/files.py edit /www/test.txt "Hello World"

# 从本地文件读取内容
python3 {baseDir}/scripts/files.py edit /www/test.txt -f ./content.txt

# 从标准输入读取
cat ./content.txt | python3 {baseDir}/scripts/files.py edit /www/test.txt

创建目录/文件

# 创建目录
python3 {baseDir}/scripts/files.py mkdir /www/newdir

# 创建文件
python3 {baseDir}/scripts/files.py touch /www/test.txt

删除文件/目录

# 删除文件
python3 {baseDir}/scripts/files.py rm /www/test.txt

# 删除目录
python3 {baseDir}/scripts/files.py rmdir /www/olddir

查看/修改权限

# 查看权限
python3 {baseDir}/scripts/files.py stat /www/test.txt

# 修改权限
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt

# 修改权限并设置所有者
python3 {baseDir}/scripts/files.py chmod 755 /www/test.txt -u www -g www

# 递归修改目录权限
python3 {baseDir}/scripts/files.py chmod 755 /www/wwwroot -R

参数说明

全局参数

| 参数 | 说明 | 默认值 | |------|------|--------| | --server, -s | 指定服务器名称 | 默认服务器 |

ls 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | path | 目录路径 | /www | | --page, -p | 页码 | 1 | | --rows, -r | 每页显示数量 | 500 |

cat 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | path | 文件路径 | 必填 | | --lines, -n | 显示最后 N 行 | 全部 | | --verbose, -v | 显示文件信息 | 否 |

edit 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | path | 文件路径 | 必填 | | content | 文件内容 | 从 stdin 读取 | | --file, -f | 从本地文件读取内容 | 无 | | --encoding, -e | 文件编码 | utf-8 |

mkdir 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | path | 目录路径 | 必填 |

touch 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | path | 文件路径 | 必填 |

rm 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | path | 文件路径 | 必填 |

rmdir 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | path | 目录路径 | 必填 |

stat 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | path | 文件路径 | 必填 |

chmod 命令参数

| 参数 | 说明 | 默认值 | |------|------|--------| | access | 权限码（如 755, 644） | 必填 | | path | 文件路径 | 必填 | | --user, -u | 所有者用户名 | 当前用户 | | --group, -g | 用户组名 | 当前组 | | --recursive, -R | 递归设置子目录和文件 | 否 |

功能特性说明

目录浏览

• 支持分页浏览大目录
• 显示文件/目录的详细信息（名称、大小、权限、所有者、修改时间）
• 自动区分目录和文件
• 支持 URL 编码路径（自动处理含空格和特殊字符的路径）

文件读取

• 支持大文件读取
• 支持指定显示行数（类似 tail 命令）
• 返回文件编码、大小、只读状态等元信息
• 自动检测文件编码

文件编辑

• 支持直接指定内容保存
• 支持从本地文件读取内容
• 支持从标准输入读取内容
• 并发保护：保存时检查文件是否被修改（通过 st_mtime 参数）

目录/文件管理

• 创建空目录
• 创建空文件
• 删除文件（移动到回收站）
• 删除目录（移动到回收站）

权限管理

• 查看文件权限（权限码、所有者）
• 修改文件权限码
• 修改文件所有者
• 修改文件用户组
• 递归设置目录及子文件权限

注意事项

1. 路径安全：所有路径参数会自动进行 URL 编码，支持含空格和特殊字符的路径

2. 删除操作：删除文件/目录会移动到回收站，非永久删除。如需永久删除需在宝塔面板中清空回收站

3. 并发保护：保存文件时会自动检查文件是否被其他进程修改，如有冲突会提示

4. 权限要求：需要对目标路径有相应的读写权限，否则操作会失败

5. 敏感文件：部分系统文件可能因权限限制无法读取或修改

6. 文件大小限制：过大的文件可能导致读取/保存超时，建议分批处理

7. 文件下载 API：宝塔面板 /files?action=DownloadFile API 必须传递 filename 参数，否则返回 HTTP 500 错误。脚本已自动从 URL 提取文件名，无需手动指定

响应格式

目录列表响应

{
  "dir": [
    {"nm": "目录名", "sz": "大小", "mt": "时间戳", "acc": "权限", "user": "所有者"}
  ],
  "files": [
    {"nm": "文件名", "sz": "大小", "mt": "时间戳", "acc": "权限", "user": "所有者", "rmk": "备注"}
  ],
  "path": "/www",
  "page": "页码信息"
}

文件内容响应

{
  "status": true,
  "only_read": false,
  "size": 639,
  "encoding": "utf-8",
  "data": "文件内容",
  "st_mtime": "1753161154"
}

权限信息响应

{
  "chmod": "755",
  "chown": "www:www"
}

配置说明

技能包复用 btpanel 技能的配置系统，配置文件位置：

• 全局配置：~/.openclaw/bt-skills.yaml
• 本地配置：config/servers.local.yaml
• 默认配置：config/servers.yaml

配置示例：

servers:
  - name: prod-01
    host: https://panel.example.com:8888
    token: YOUR_API_TOKEN
    disabled: false

global:
  timeout: 30
  thresholds:
    cpu: 80
    memory: 85
    disk: 90