btpanel_files

BT Panel File Management

BT Panel server file operation tool, providing basic file operation capabilities such as remote file/directory browsing, reading, editing, creation, deletion, and permission management.

Icon Resources

The skill package provides the following icon files, which can be referenced when generating reports:

File	Format	Purpose
`icon/bt-logo.svg`	SVG	Vector icon, suitable for scaling

AI Usage Constraints

This skill is used to query and modify server files. AI should follow these principles:

Confirm before operation: before modifying a file, read the file content first and confirm the scope of modification
Notify before execution: file operations will affect server status; AI should first briefly describe to the user the operation steps about to be executed
Delete with caution: before deleting files/directories, inform the user and confirm the target path
Privacy protection: do not proactively read sensitive files (such as /etc/shadow、.env、config.php and other files containing passwords)
Backup recommendation: before modifying important configuration files, recommend that the user back them up first

Execution Flow Example：

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

BT Panel Related Skill Matrix

The current BT Panel skill package contains 3 interrelated skills:

Skill Name	Description	Dependency Relationship
btpanel	Operations Monitoring Skill	✅ Basic skill, mainly used for resource monitoring, website status checks, service status checks, etc.
btpanel-files	File Management Skill	✅ Provides remote server file assistance services, and can read file lists and contents
btpanel-phpsite	PHP Website Management Skill	✅ Provides remote server PHP website management functionality, and can deploy and manage PHP websites

⚠️ Common Issues

Issue 1: Configuration file does not exist

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

Issue 2: PYTHONPATH is not set

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

Check Command

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

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

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

Server Configuration Management

Important: If there is no server information, you need to add it first

This skill reuses the configuration system of the btpanel skill and uses the bt-config.py tool to manage servers:

# 查看帮助
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

How to Obtain an API Token：

Log in to the BT Panel
Go to "Panel Settings" -> "API Interface"
Click "Get API Token"

Important Notice - SSL Certificate Verification Configuration: When adding a server, AI should ask the user:

"Does your BT Panel use a trusted SSL certificate (such as Let's Encrypt or a commercial CA certificate)?"

✅ Yes(trusted certificate) → use the default configuration, no additional parameters required
⚠️ No(self-signed certificate) → add the --verify-ssl false parameter

Example：

# 自签名证书场景
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

Common Scenarios

Scenario 1: View the directory file list

When the user needs to view the contents of a directory on the server:

# 查看/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

User Intent Recognition：

"See what is in the /www directory" → execute files.py ls /www
"View Nginx configuration file directory" → Execute files.py ls /www/server/nginx/conf
"What files are in this directory" → Execute files.py ls 路径

Scenario 2: Read file contents

When the user needs to view file contents:

# 读取文件
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

User intent recognition：

"Help me check the contents of this file" → Execute files.py cat 路径
"View the last few lines of the log" → Execute files.py cat 路径 -n 50
"What encoding is this file" → Execute files.py cat 路径 -v

Scenario 3: Edit file contents

When the user needs to modify file contents:

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

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

User intent recognition：

"Modify this file, add XXX" → First read the file, then execute files.py edit
"Update the configuration file" → First read the file, then execute after confirmation files.py edit

Important: Before editing a file, you must first read the original content and confirm the modification scope before saving.

Scenario 4: Create directory/file

When the user needs to create a new directory or file:

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

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

User intent recognition：

"Create a new directory" → Execute files.py mkdir 路径
"Create an empty file" → Execute files.py touch 路径

Scenario 5: Delete file/directory

When the user needs to delete a file or directory:

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

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

User intent recognition：

"Delete this file" → Execute after confirming the path files.py rm 路径
"Clean up this directory" → Execute after confirming the path files.py rmdir 路径

Important: The delete operation moves files/directories to the recycle bin, not permanent deletion. However, user confirmation is still required before the operation.

Scenario 6: View/modify file permissions

When the user needs to manage file permissions:

# 查看文件权限
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

User intent recognition：

"View the permissions of this file" → Execute files.py stat 路径
"Modify file permissions to 755" → Execute files.py chmod 755 路径
"Fix this directory's permissions" → Execute after confirming the correct permissions files.py chmod

Version requirements

BaoTa Panel: >= 9.0.0
Python: >= 3.10

Usage

View directory listing

# 查看帮助
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

Read file

# 读取文件内容
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

Edit file

# 直接指定内容
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

Create directory/file

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

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

Delete file/directory

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

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

View/modify permissions

# 查看权限
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

Parameter description

Global parameters

Parameter	Description	Default value
`--server`, `-s`	Specify server name	Default server

ls command parameters

Parameter	Description	Default value
`path`	Directory path	/www
`--page`, `-p`	Page number	1
`--rows`, `-r`	Number of items per page	500

cat command parameters

Parameter	Description	Default value
`path`	File path	Required
`--lines`, `-n`	Show the last N lines	All
`--verbose`, `-v`	Show file information	No

edit command parameters

Parameter	Description	Default value
`path`	File path	Required
`content`	File content	Read from stdin
`--file`, `-f`	Read content from a local file	None
`--encoding`, `-e`	File encoding	utf-8

mkdir command parameters

Parameter	Description	Default Value
`path`	Directory path	Required

touch command parameters

Parameter	Description	Default Value
`path`	File path	Required

rm command parameters

Parameter	Description	Default Value
`path`	File path	Required

rmdir command parameters

Parameter	Description	Default Value
`path`	Directory path	Required

stat command parameters

Parameter	Description	Default Value
`path`	File path	Required

chmod command parameters

Parameter	Description	Default Value
`access`	Permission code (e.g., 755, 644)	Required
`path`	File path	Required
`--user`, `-u`	Owner username	Current user
`--group`, `-g`	User group name	Current group
`--recursive`, `-R`	Recursively set permissions for subdirectories and files	No

Feature Description

Directory Browsing

Supports paginated browsing of large directories
Displays detailed information of files/directories (name, size, permissions, owner, modification time)
Automatically distinguishes directories and files
Supports URL-encoded paths (automatically handles paths containing spaces and special characters)

File Reading

Supports reading large files
Supports specifying the number of lines to display (similar to the tail command)
Returns metadata such as file encoding, size, and read-only status
Automatically detects file encoding

File Editing

Supports directly specifying content to save
Supports reading content from a local file
Supports reading content from standard input
Concurrency protection: checks whether the file has been modified when saving (via the st_mtime parameter)

Directory/File Management

Create empty directory
Create empty file
Delete file (move to recycle bin)
Delete directory (move to recycle bin)

Permission Management

View file permissions (permission code, owner)
Modify file permission code
Modify file owner
Modify file user group
Recursively set permissions for directories and subfiles

Notes

Path Security: All path parameters are automatically URL-encoded, supporting paths containing spaces and special characters
Delete Operation: Deleting files/directories moves them to the recycle bin, not permanent deletion. For permanent deletion, you need to empty the recycle bin in the BT Panel
Concurrency Protection: When saving a file, it automatically checks whether the file has been modified by other processes, and prompts if there is a conflict
Permission requirements: The corresponding read and write permissions are required for the target path; otherwise, the operation will fail
Sensitive files: Some system files may not be readable or modifiable due to permission restrictions
File size limit: Files that are too large may cause read/save timeouts; processing in batches is recommended
File download API: BT Panel /files?action=DownloadFile API must pass the filename parameter; otherwise, an HTTP 500 error is returned. The script has automatically extracted the file name from the URL, so there is no need to specify it manually

Response format

Directory list response

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

File content response

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

Permission information response

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

Configuration instructions

The skill package reuses the configuration system of the btpanel skill; the configuration file location is:

Global configuration:~/.openclaw/bt-skills.yaml
Local configuration:config/servers.local.yaml
Default configuration:config/servers.yaml

Configuration example：

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

About this skill

Icon Resources

AI Usage Constraints

BT Panel Related Skill Matrix

⚠️ Common Issues

Check Command

Server Configuration Management

Common Scenarios

Scenario 1: View the directory file list

Scenario 2: Read file contents

Scenario 3: Edit file contents

Scenario 4: Create directory/file

Scenario 5: Delete file/directory

Scenario 6: View/modify file permissions

Version requirements

Usage

View directory listing

Read file

Edit file

Create directory/file

Delete file/directory

View/modify permissions

Parameter description

Global parameters

ls command parameters

cat command parameters

edit command parameters

mkdir command parameters

touch command parameters

rm command parameters

rmdir command parameters

stat command parameters

chmod command parameters

Feature Description

Directory Browsing

File Reading

File Editing

Directory/File Management

Permission Management

Notes

Response format

Directory list response

File content response

Permission information response

Configuration instructions