夜雨聆风
OpenClaw USB 便携版(从零制作完全教程)
这两天看便携版的openclaw挺好玩的，也研究着做了一个，有需要的，可以按照这个步骤，自己做一个试试哦！
一、什么是 OpenClaw USB 便携版
OpenClaw 是一个开源的 AI 智能助手网关，支持接入多种大语言模型（DeepSeek、OpenAI、Claude 等），提供 Web 控制面板和丰富的插件生态。
USB 便携版的核心思路是：将 Node.js 运行环境、OpenClaw 程序、所有配置文件、工作空间数据全部放在同一个目录中，通过环境变量将程序的数据目录重定向到便携目录内，实现”即插即用、拔走无痕”。
核心优势
·完全便携：所有文件在一个文件夹内，拷贝到 U 盘即可在任何 Windows 电脑上运行
·数据隔离：不会在宿主电脑上留下任何配置或数据痕迹
·即插即用：插入 U 盘，双击 start.bat，浏览器自动打开，立即可用
·配置独立：每台电脑上的使用互不干扰，API Key 和对话记录随身携带
·无需管理员权限：不需要安装任何软件，不需要修改系统环境变量
工作原理
关键技巧在于设置两个环境变量：
·HOME — 指向便携目录中的 openclaw 文件夹，使程序将配置文件、日志、数据都写入便携目录
·USERPROFILE — 同样指向便携目录中的 openclaw 文件夹，确保 Node.js 的缓存和全局配置也留在便携目录内
通过这两个环境变量，OpenClaw 会认为便携目录就是”用户主目录”，所有数据自然就保存在 U 盘上了。
二、准备工作
硬件要求
·一个 U 盘（建议 8GB 以上，USB 3.0 更佳）
·一台 Windows 10 或 Windows 11 电脑
需要准备的信息
·DeepSeek API Key（或其他 AI 提供商的 API Key）
·获取方式：访问 https://platform.deepseek.com 注册并创建 API Key
提示：DeepSeek 新用户通常有免费额度，足够日常使用。
需要下载的文件
·Node.js Windows 二进制包（约 30MB）
·下载地址：https://nodejs.org/dist/v22.19.0/node-v22.19.0-win-x64.zip
注意：必须下载 .zip 格式的二进制包，不要下载 .msi 安装包。便携版不需要安装。
三、目录结构总览
完成后的 USB 便携版目录结构如下：
U盘:\openclaw-portable\├── node\ # Node.js 便携版（从 zip 解压）│ ├── node.exe # Node.js 主程序│ ├── npm.cmd # npm 包管理器│ └── node_modules\ # npm 全局模块│├── openclaw\ # OpenClaw 主目录（也是模拟的 HOME）│ ├── .openclaw\ # 配置目录│ │ ├── openclaw.json # 主配置文件│ │ └── agents\main\agent\│ │ └── auth-profiles.json # API Key 存储│ ├── node_modules\ # OpenClaw 依赖包│ │ └── @qingchencloud\│ │ └── openclaw-zh\│ │ └── openclaw.mjs # 入口文件│ └── logs\ # 运行日志（自动生成）│├── workspace\ # 工作空间（AI 生成的文件存放处）│├── gateway.bat # 网关启动脚本├── start.bat # 一键启动脚本（推荐使用）├── stop.bat # 停止脚本└── README.md # 说明文档
核心要点：openclaw 目录同时扮演两个角色——既是 OpenClaw 程序的安装目录，也是模拟的用户主目录（HOME）。
四、第一步：获取 Node.js 便携版
步骤 1：下载 Node.js 二进制包
访问 https://nodejs.org/dist/v22.19.0/ ，下载 node-v22.19.0-win-x64.zip 文件。
步骤 2：解压到便携目录
将下载的 zip 文件解压，把解压出来的 node-v22.19.0-win-x64 文件夹中的全部内容，复制到 U 盘的 openclaw-portable\node\ 目录下。
注意：是复制文件夹里面的内容（node.exe、npm.cmd 等），不是复制整个文件夹。最终 node.exe 的路径应为 U:\openclaw-portable\node\node.exe。
步骤 3：验证 Node.js 是否可用
打开命令提示符（cmd），切换到 U 盘的 node 目录，运行以下命令验证：
cd /d U:\openclaw-portable\nodenode.exe --version
如果输出 v22.19.0，说明 Node.js 便携版准备成功。
五、第二步：安装 OpenClaw 到便携目录
这一步需要将 OpenClaw 安装到便携目录中。由于我们要让所有文件都留在便携目录内，需要先设置环境变量，再执行安装。
步骤 1：打开命令提示符并设置环境变量
以管理员身份打开命令提示符（非必须，但建议），执行以下命令：
REM 假设 U 盘盘符为 U:，请根据实际情况修改set "PORTABLE=U:\openclaw-portable"set "HOME=%PORTABLE%\openclaw"set "USERPROFILE=%PORTABLE%\openclaw"set "PATH=%PORTABLE%\node;%PATH%"
重要：U 盘在不同电脑上的盘符可能不同（U:、E:、F: 等）。后续的启动脚本会自动处理盘符问题，这里手动设置只是为了安装。
步骤 2：安装 OpenClaw
在同一个命令提示符窗口中，执行 npm 安装命令：
REM 切换到 openclaw 目录cd /d %PORTABLE%\openclawREM 安装 OpenClaw（中文版）npm install @qingchencloud/openclaw-zh
安装过程可能需要几分钟，请耐心等待。安装完成后，检查以下文件是否存在：
dir "%PORTABLE%\openclaw\node_modules\@qingchencloud\openclaw-zh\openclaw.mjs"如果显示该文件存在，说明安装成功。
步骤 3：创建必要目录
继续在命令提示符中执行：
REM 创建工作空间目录mkdir "%PORTABLE%\workspace"REM 创建日志目录mkdir "%PORTABLE%\openclaw\logs"
六、第三步：配置 AI 模型（以 DeepSeek 为例）
OpenClaw 的主配置文件位于 openclaw\.openclaw\openclaw.json。如果该文件不存在，需要手动创建。以下是完整的配置模板。
步骤 1：创建配置目录
在 U 盘的 openclaw-portable\openclaw\ 下创建 .openclaw 文件夹（注意前面有个点）。
步骤 2：创建主配置文件
{"agents": {"defaults": {"workspace": "__PORTABLE_DIR__\\workspace","models": {"deepseek/deepseek-v4-flash": {"alias": "DeepSeek"}},"model": {"primary": "deepseek/deepseek-v4-flash"}}},"gateway": {"mode": "local","auth": {"mode": "token","token": "你的自定义Token（建议用随机字符串）"},"port": 18789,"bind": "loopback","tailscale": {"mode": "off","resetOnExit": false},"controlUi": {"allowInsecureAuth": true}},"session": {"dmScope": "per-channel-peer"},"tools": {"profile": "coding"},"plugins": {"entries": {"deepseek": {"enabled": true}}},"models": {"mode": "merge","providers": {"deepseek": {"baseUrl": "https://api.deepseek.com","api": "openai-completions","models": [{"id": "deepseek-v4-flash","name": "DeepSeek V4 Flash","reasoning": true,"input": ["text"],"cost": {"input": 0.14,"output": 0.28,"cacheRead": 0.028,"cacheWrite": 0},"contextWindow": 1000000,"maxTokens": 384000,"compat": {"supportsReasoningEffort": true,"supportsUsageInStreaming": true,"maxTokensField": "max_tokens"},"api": "openai-completions"}]}}},"auth": {"profiles": {"deepseek:default": {"provider": "deepseek","mode": "api_key"}}}}
说明：配置文件中的 __PORTABLE_DIR__ 是一个占位符，启动脚本会自动替换为实际的 U 盘路径。这样无论 U 盘在哪个盘符下都能正常工作。
七、第四步：配置 API Key
API Key 存储在独立的认证配置文件中，与主配置分离，便于管理和更换。
步骤 1：创建认证配置目录
在 openclaw\.openclaw\ 下依次创建 agents\main\agent\ 目录结构。
步骤 2：创建 auth-profiles.json
在 agent 目录中创建 auth-profiles.json 文件，内容如下（将 your-api-key 替换为你的真实 Key）：
{"version": 1,"profiles": {"deepseek:default": {"type": "api_key","provider": "deepseek","key": "sk-你的DeepSeek-API-Key"}}}
安全提醒：API Key 是敏感信息，请勿分享给他人。USB 便携版的所有数据都在 U 盘上，拔走 U 盘后不会在电脑上留下 Key。
八、第五步：编写启动脚本
启动脚本是整个便携版的核心。它负责设置环境变量、替换路径占位符、启动网关、打开浏览器。需要创建三个脚本文件。
8.1 gateway.bat — 网关启动脚本
@echo offchcp 65001 >nultitle OpenClaw Portable Gatewayset "PORTABLE_DIR=%~dp0"set "NODE_PATH=%PORTABLE_DIR%node"set "NODE_EXE=%NODE_PATH%\node.exe"set "OPENCLAW_JS=%PORTABLE_DIR%openclaw\node_modules\@qingchencloud\openclaw-zh\openclaw.mjs"REM 设置环境变量，将 HOME 指向便携目录set "USERPROFILE=%PORTABLE_DIR%openclaw"set "HOME=%PORTABLE_DIR%openclaw"set "PATH=%NODE_PATH%;%PATH%"REM 替换配置文件中的路径占位符set "CONFIG=%PORTABLE_DIR%openclaw\.openclaw\openclaw.json"if exist "%CONFIG%" (powershell -NoProfile -Command "(Get-Content '%CONFIG%' -Raw) -replace '__PORTABLE_DIR__\\\\', '%PORTABLE_DIR:\=\\%\\\\' | Set-Content '%CONFIG%' -Encoding UTF8 -Force")REM 创建工作空间if not exist "%PORTABLE_DIR%workspace" mkdir "%PORTABLE_DIR%workspace"echo ========================================echo OpenClaw Portable - Direct Startecho ========================================echo.REM 检查端口是否已被占用netstat -ano | findstr ":18789" >nulif %errorlevel% equ 0 (echo 端口 18789 已被占用！echo 正在打开 Web 面板...start http://127.0.0.1:18789echo.pauseexit /b 0)echo 正在启动 OpenClaw 网关...echo.REM 启动网关"%NODE_EXE%" "%OPENCLAW_JS%" gateway --port 18789 --allow-unconfigured run
8.2 start.bat — 一键启动脚本
在 openclaw-portable 根目录创建 start.bat：
@echo offtitle OpenClaw Portableset "PORTABLE_DIR=%~dp0"set "TOKEN=你的Token（与 openclaw.json 中保持一致）"echo ========================================echo OpenClaw Portable - 一键启动echo ========================================echo.echo 正在启动网关...start "OpenClaw Gateway" "%PORTABLE_DIR%gateway.bat"echo 等待 45 秒让网关完成启动...timeout /t 45 /nobreak >nulecho 正在打开 Web 面板...start http://127.0.0.1:18789/?token=%TOKEN%echo.echo ========================================echo OpenClaw 正在启动...echo ========================================echo.echo Web 面板: http://127.0.0.1:18789echo Token: %TOKEN%echo.echo 如果页面没有加载，请等待 30 秒后刷新。echo.pause
8.3 stop.bat — 停止脚本
在 openclaw-portable 根目录创建 stop.bat：
@echo offchcp 65001 >nultitle OpenClaw Portable - Stopecho ========================================echo 正在停止 OpenClaw Portableecho ========================================echo.taskkill /f /im node.exe 2>nulecho 所有 OpenClaw 进程已终止。echo.pause
脚本工作原理
·%~dp0：获取脚本所在目录的绝对路径（自动适配 U 盘盘符）
·HOME / USERPROFILE：重定向到便携目录，确保数据不外泄
·PowerShell 替换：将配置文件中的 __PORTABLE_DIR__ 占位符替换为实际路径
·端口检测：避免重复启动导致冲突
·45 秒等待：网关启动需要约 42 秒完成认证预热
九、第六步：测试运行
步骤 1：双击 start.bat
在文件资源管理器中找到 U 盘上的 openclaw-portable 文件夹，双击 start.bat。
步骤 2：观察网关窗口
会弹出一个标题为 “OpenClaw Gateway” 的命令行窗口，显示启动日志。等待约 45 秒，直到看到类似 “gateway ready” 或 “listening on port 18789” 的信息。
步骤 3：浏览器自动打开
45 秒后浏览器会自动打开 http://127.0.0.1:18789/?token=你的Token。如果看到 OpenClaw 的 Web 控制面板界面，说明一切正常。
步骤 4：验证功能
在 Web 面板中尝试发送一条消息，例如”你好”，确认 AI 能正常回复。
如果页面一直加载或显示空白，请参考第十二章“故障排除”。
十、第七步：拷贝到 U 盘
如果你是在电脑硬盘上完成以上所有配置的，现在可以将整个 openclaw-portable 文件夹拷贝到 U 盘。
拷贝注意事项
·确保 U 盘有足够空间（完整目录约 500MB ~ 1GB）
·直接复制整个 openclaw-portable 文件夹到 U 盘根目录
·不要修改文件夹名称和内部结构
·拷贝完成后，在 U 盘上直接双击 start.bat 测试是否能正常运行
提示：如果之前在硬盘上配置时使用了绝对路径（如 C:\Users\…），启动脚本中的 PowerShell 替换逻辑会自动修正为 U 盘路径。只要配置文件中使用了 __PORTABLE_DIR__ 占位符，就不需要手动修改。
十一、日常使用指南
启动
插入 U 盘 → 打开 openclaw-portable 文件夹 → 双击 start.bat → 等待浏览器自动打开。
停止
·方法一：关闭网关命令行窗口
·方法二：双击 stop.bat
·方法三：直接拔出 U 盘（不推荐，可能导致数据丢失）
建议：先关闭网关窗口，等待 5 秒，再安全弹出 U 盘。
在不同电脑上使用
直接插入 U 盘，双击 start.bat 即可。脚本会自动适配当前电脑的 U 盘盘符。
无需安装任何软件，无需管理员权限。
所有对话记录和工作文件都保存在 U 盘的 workspace 目录中。
更换 API Key
编辑 U 盘上的 openclaw\.openclaw\agents\main\agent\auth-profiles.json 文件，修改 key 字段的值。
更换 AI 模型
编辑 openclaw\.openclaw\openclaw.json，在 models.providers 中添加新的提供商配置，然后修改 agents.defaults.model.primary 为新的模型 ID。
十二、故障排除
问题：浏览器页面一直加载/空白
解决：可能原因：网关未完全启动。解决：等待 60 秒后手动刷新页面。如果仍不行，检查 gateway.bat 窗口是否有报错信息。
问题：端口 18789 已被占用
解决：可能原因：之前的网关进程未正常关闭。解决：运行 stop.bat，或手动在任务管理器中结束 node.exe 进程。也可以修改 openclaw.json 中的 gateway.port 为其他端口（如 18790）。
问题：API 调用报错
解决：可能原因：API Key 无效或余额不足。解决：检查 auth-profiles.json 中的 Key 是否正确，登录 DeepSeek 平台确认账户余额。
问题：防火墙拦截
解决：可能原因：Windows 防火墙阻止了 Node.js 的网络访问。解决：在防火墙设置中允许 node.exe 访问网络。
问题：中文乱码
解决：可能原因：命令行编码问题。解决：gateway.bat 和 start.bat 开头都有 chcp 65001 命令，确保未被删除。
问题：U 盘在其他电脑上无法启动
解决：可能原因：盘符变化导致路径错误。解决：检查 openclaw.json 中是否使用了 __PORTABLE_DIR__ 占位符，启动脚本会自动替换。如果手动写了绝对路径，需要改为占位符。
问题：npm 安装失败
解决：可能原因：网络问题或 npm 源不可达。解决：设置 npm 镜像源：npm config set registry https://registry.npmmirror.com
十三、进阶配置
修改端口
编辑 openclaw.json，修改 gateway.port 的值。同时需要修改 gateway.bat 中的端口检测命令和 start.bat 中的 URL。
添加多个 AI 模型
在 openclaw.json 的 models.providers 中添加新的提供商。例如添加 OpenAI：
"openai": {"baseUrl": "https://api.openai.com/v1","api": "openai-completions","models": [{"id": "gpt-4o","name": "GPT-4o","reasoning": true,"input": ["text"],"contextWindow": 128000,"maxTokens": 16384}]}
允许局域网访问
将 gateway.bind 从 “loopback” 改为 “0.0.0.0”，即可让局域网内其他设备访问。
安全警告：改为 0.0.0.0 后任何能访问你 IP 的人都可以使用你的 AI 助手。建议仅在信任的网络中使用，并确保 Token 足够复杂。
更新 OpenClaw 版本
在便携目录中打开命令提示符，设置 HOME 和 USERPROFILE 环境变量后，执行：
npm update @qingchencloud/openclaw-zh附录 A：完整脚本代码
gateway.bat
@echo offchcp 65001 >nultitle OpenClaw Portable Gatewayset "PORTABLE_DIR=%~dp0"set "NODE_PATH=%PORTABLE_DIR%node"set "NODE_EXE=%NODE_PATH%\node.exe"set "OPENCLAW_JS=%PORTABLE_DIR%openclaw\node_modules\@qingchencloud\openclaw-zh\openclaw.mjs"set "USERPROFILE=%PORTABLE_DIR%openclaw"set "HOME=%PORTABLE_DIR%openclaw"set "PATH=%NODE_PATH%;%PATH%"set "CONFIG=%PORTABLE_DIR%openclaw\.openclaw\openclaw.json"if exist "%CONFIG%" (powershell -NoProfile -Command "(Get-Content '%CONFIG%' -Raw) -replace '__PORTABLE_DIR__\\\\', '%PORTABLE_DIR:\=\\%\\\\' | Set-Content '%CONFIG%' -Encoding UTF8 -Force")if not exist "%PORTABLE_DIR%workspace" mkdir "%PORTABLE_DIR%workspace"echo ========================================echo OpenClaw Portable - Direct Startecho ========================================echo.netstat -ano | findstr ":18789" >nulif %errorlevel% equ 0 (echo Port 18789 is already in use!echo Opening Web panel...start http://127.0.0.1:18789echo.pauseexit /b 0)echo Starting OpenClaw gateway...echo."%NODE_EXE%" "%OPENCLAW_JS%" gateway --port 18789 --allow-unconfigured run
start.bat
@echo offtitle OpenClaw Portableset "PORTABLE_DIR=%~dp0"set "TOKEN=你的Token"echo ========================================echo OpenClaw Portable - One Click Startecho ========================================echo.echo Starting gateway...start "OpenClaw Gateway" "%PORTABLE_DIR%gateway.bat"echo Waiting 45 seconds for gateway to start...timeout /t 45 /nobreak >nulecho Opening Web panel...start http://127.0.0.1:18789/?token=%TOKEN%echo.echo ========================================echo OpenClaw is launching...echo ========================================echo.echo Web Panel: http://127.0.0.1:18789echo Token: %TOKEN%echo.echo If the page doesn't load, wait 30 seconds and refresh.echo.pause
stop.bat
@echo offchcp 65001 >nultitle OpenClaw Portable - Stopecho ========================================echo Stopping OpenClaw Portableecho ========================================echo.taskkill /f /im node.exe 2>nulecho All OpenClaw processes terminated.echo.pause
附录 B：完整配置文件
openclaw.json
{"agents": {"defaults": {"workspace": "__PORTABLE_DIR__\\workspace","models": {"deepseek/deepseek-v4-flash": {"alias": "DeepSeek"}},"model": {"primary": "deepseek/deepseek-v4-flash"}}},"gateway": {"mode": "local","auth": {"mode": "token","token": "你的Token"},"port": 18789,"bind": "loopback","tailscale": {"mode": "off","resetOnExit": false},"controlUi": {"allowInsecureAuth": true}},"session": {"dmScope": "per-channel-peer"},"tools": {"profile": "coding"},"plugins": {"entries": {"deepseek": {"enabled": true}}},"models": {"mode": "merge","providers": {"deepseek": {"baseUrl": "https://api.deepseek.com","api": "openai-completions","models": [{"id": "deepseek-v4-flash","name": "DeepSeek V4 Flash","reasoning": true,"input": ["text"],"cost": {"input": 0.14,"output": 0.28,"cacheRead": 0.028,"cacheWrite": 0},"contextWindow": 1000000,"maxTokens": 384000,"compat": {"supportsReasoningEffort": true,"supportsUsageInStreaming": true,"maxTokensField": "max_tokens"},"api": "openai-completions"}]}}},"auth": {"profiles": {"deepseek:default": {"provider": "deepseek","mode": "api_key"}}}}
auth-profiles.json
{"version": 1,"profiles": {"deepseek:default": {"type": "api_key","provider": "deepseek","key": "sk-你的DeepSeek-API-Key"}}}
