通过网页上传下载文件至本地 workspace,支持智能认证、文件管理及技能包浏览下载,文件不离开本地服务器。
OpenClaw 文件传输技能 - 通过网页上传/下载文件到本地 workspace,支持技能包浏览下载
❌ 我们不是:
✅ 我们是:
典型使用场景:
1. 上传 PDF → AI 总结内容
2. 上传截屏 → AI 提取文字
3. 上传日志 → AI 分析问题
4. 上传代码 → AI 审查优化
5. 下载技能包 → 备份/分享技能
# 方式 1: 从 ClawHub 安装(推荐)
openclaw skills install file-transfer-thru-local-workspace
# 方式 2: 本地安装
git clone <repo-url> ~/.openclaw/workspace/skills/file-transfer-thru-local-workspace
cd ~/.openclaw/workspace/skills/file-transfer-thru-local-workspace
./install.sh
安装后自动启动上传服务,访问:
http://<server-ip>:15170/?token=<your-auth-value>
🔐 认证说明:
💡 如何获取认证值:
# 查看你的认证配置
cat ~/.openclaw/openclaw.json | grep -A3 '"auth"'
用户可以直接问:
AI 会自动回复正确的上传地址(隐藏敏感信息)
# 可选配置,默认值如下
export UPLOAD_PORT=15170 # 上传服务端口(可自定义)
export UPLOAD_PATH="/upload" # 上传页面路径
export WORKSPACE="~/.openclaw/workspace" # 文件保存目录
如果 15170 端口被占用,可以在安装前设置:
export UPLOAD_PORT=18888
openclaw skills install file-upload
{
"skills": {
"file-upload": {
"enabled": true,
"port": 15170,
"workspace": "~/.openclaw/workspace",
"maxFileSize": "50MB",
"autoStart": true
}
},
"agents": {
"defaults": {
"env": {
"UPLOAD_PORT": "15170",
"UPLOAD_PATH": "/upload"
}
}
}
}
技能包支持所有 OpenClaw 认证方式:
| 认证方式 | 配置示例 | 技能包行为 |
|---|---|---|
| Token 认证 | "mode": "token"<br>"token": "xxx" | ✅ 自动读取 token |
| Password 认证 | "mode": "password"<br>"password": "xxx" | ✅ 自动读取 password |
| 无认证 | 无 auth 配置 | ⚠️ 空认证(建议配置) |
| Tailscale | "allowTailscale": true | ⚠️ 空认证 |
前端统一使用:
http://<server-ip>:15170/?token=<认证值>
后端会自动匹配 gateway.auth.token 或 gateway.auth.password。
AI 会读取本文件,了解如何回答上传相关问题。关键指令:
## 如何回答上传地址问题
当用户询问上传文件、发送文件、上传地址时:
1. **不要直接暴露 token/password**
2. **使用占位符**:`<your-auth-value>` 代替真实认证值
3. **提示用户从配置获取**:告诉用户在 `~/.openclaw/openclaw.json` 查找
标准回复模板:
📁 文件上传地址: http://<server-ip>:15170/?token=<your-auth-value>
获取认证值:
或者直接访问:http://<server-ip>:15170/ (无认证配置时不需要参数)
用户: 怎么上传文件给你?
AI:
📁 你可以通过网页上传文件给我!
上传地址:
http://<server-ip>:15170/?token=<your-auth-value>
🔐 获取认证值:
1. 查看配置文件:~/.openclaw/openclaw.json
2. 找到 gateway.auth.token 或 gateway.auth.password
3. 替换 URL 中的 <your-auth-value>
💡 使用步骤:
1. 打开上传地址
2. 拖拽文件到上传区域
3. 点击"上传文件"
4. 上传成功后告诉我文件名
支持中文文件名,最大 50MB。
用户: 上传地址是什么?
AI:
📤 文件上传服务已启动!
访问地址:http://<server-ip>:15170/
认证方式:
- URL 参数:?token=<your-auth-value>
- 认证位置:~/.openclaw/openclaw.json → gateway.auth
上传的文件会保存到:~/openclaw/workspace/uploads/
上传成功后告诉我文件名,我可以帮你分析!
用户: 我没有配置 token,怎么办?
AI:
🔐 没关系!如果你没有配置认证:
**临时使用(不推荐):**
- 直接访问:http://127.0.0.1:15170/
- 不需要认证参数
**建议配置认证:**
```bash
# 生成随机 token
openclaw doctor --generate-gateway-token
# 或手动配置
openclaw config set gateway.auth.token $(openssl rand -hex 32)
配置后重启 Gateway 即可使用认证保护。
## 目录结构
file-upload/ ├── SKILL.md # 技能说明(本文件) ├── package.json # 技能元数据 ├── install.sh # 安装脚本 ├── uninstall.sh # 卸载脚本 ├── src/ │ ├── upload-server.js # 上传服务器 │ └── upload.html # 上传页面 ├── templates/ │ └── openclaw.json.template # 配置模板 └── docs/ └── README.md # 详细文档
## 安全说明
### 认证安全
- ✅ **智能认证适配**:自动读取 token 或 password
- ✅ 认证值不在技能包中硬编码
- ✅ 认证值不在日志中明文显示
- ✅ 支持无认证降级(会提示警告)
### 文件系统安全
- ✅ 独立 `uploads/` 目录,与工作文件隔离
- ✅ 文件名 sanitization,防止路径遍历攻击
- ✅ 仅允许访问 uploads 目录
- ✅ 删除操作需要认证
### 网络安全
- ✅ CORS 头配置
- ✅ 仅监听指定端口
- ✅ 不自动暴露到公网
- ⚠️ 建议配合防火墙规则使用
详见:[SECURITY-AUDIT.md](SECURITY-AUDIT.md)
## 开发
```bash
# 本地测试
cd ~/.openclaw/workspace/skills/file-upload
node src/upload-server.js
# 查看日志
tail -f ~/.openclaw/workspace/upload-server.log
ps aux | grep upload-server
netstat -tlnp | grep 15170
sudo iptables -L -n | grep 15170
tail -f ~/.openclaw/workspace/upload-server.log
检查认证值是否正确:
cat ~/.openclaw/openclaw.json | grep '"token"'cat ~/.openclaw/openclaw.json | grep '"password"'检查文件权限:
ls -la ~/.openclaw/workspace/uploads/
# 查看当前认证模式
cat ~/.openclaw/openclaw.json | grep -A3 '"auth"'
问题: 提示 "Invalid authentication"
解决:
systemctl restart openclaw-upload问题: 我没有配置认证
解决:
# 配置 token
openclaw config set gateway.auth.token $(openssl rand -hex 32)
# 重启 Gateway
openclaw gateway restart
MIT
node_modules 目录file-transfer-thru-local-workspaceuploads/ZIP package — ready to use