小石U盘AGENT_详细使用说明
小石U盘 AGENT
本文件已经过我自己的WIN11(AMD9800X+32G内存) 和 MAC(M5）测试，但不保证所有设备都没有BUG，如果有请用AI自动修复（一般都是小BUG）。
通过网盘分享的文件：小石智能U盘.zip
链接: https://pan.baidu.com/s/1CQ6KhZwwDHBBYkhS0fw2gg?pwd=6666 提取码: 6666
把下载文件解压到U盘，双击启动即可。
WINDOWS用户请务必使用WIN11＋谷歌浏览器要不然有莫名其妙的BUG。
详细使用说明
面向普通消费者的 U 盘便携式双 Agent 使用手册
|文档用途<br>本文用于交付、测试和用户自助使用。内容覆盖 U 盘要求、系统要求、首次配置、日常启动、模型 API、对话、文件上传、官方更新、还原和常见问题。|
|—|
1. 产品定位
小石U盘 AGENT 是一个放在 U 盘里的便携式 AI Agent 启动器。用户把整套文件复制到 U 盘后，在 Windows 或 Apple Silicon Mac 上通过启动脚本打开本地网页面板，在同一个面板里使用 OpenClaw 和 Hermes。
- OpenClaw 和 Hermes 独立存在，端口、数据目录、记忆文件和工作区互不干扰。
- 用户可以选择两个 Agent 共用一个模型，也可以分别配置模型 API。
- 启动器提供简易对话框，支持文本、文本类文件和图片附件；图片识别取决于所选模型是否支持视觉输入。
- 正式控制电脑、浏览器自动化、文件操作等高级能力，应进入对应 Agent 后台并按系统权限提示授权。
|组件|当前便携包版本|说明|
|—|—|—|
|OpenClaw|2026.5.7|来自本地便携包 agents/openclaw 目录，后续可通过 OpenClaw 官方 npm 包更新。|
|Hermes Agent|0.13.0|来自本地便携包 agents/hermes 目录，后续可通过 NousResearch 官方仓库/安装脚本更新。|
2. U 盘和存储要求
|项目|建议|说明|
|—|—|—|
|文件系统|exFAT|Windows 和 macOS 都能读写，适合单文件较大的运行时、缓存和模型文件。|
|接口|USB 3.0 或更高|启动、更新、依赖读取和日志写入更稳定；USB 2.0 可用但会明显变慢。|
|最低容量|16GB|仅适合基础包和少量工作区文件。当前桌面测试包约 2.15GB。|
|推荐容量|64GB 或 128GB|给日志、缓存、备份、插件、文件对话和后续更新留空间。|
|高阶玩法|移动 SSD / 1TB 以上|如果后续把本地模型、向量库、浏览器引擎、素材库也放进去，建议直接用移动固态硬盘。|
|容量估算<br>当前测试包约 2.15GB：runtime 约 477MB，OpenClaw 约 379MB，Hermes 约 309MB，data 约 1.01GB。正式分发建议预留至少 10GB 可写空间，避免更新和备份失败。|
|—|
3. 系统要求
|系统|要求|注意事项|
|—|—|—|
|Windows|Windows 10/11 x64|首次启动可能出现防火墙、杀毒软件或 SmartScreen 提醒。允许本地 127.0.0.1 服务即可。|
|macOS|Apple Silicon：M1/M2/M3/M4|首次运行 .command 可能需要右键打开，可能提示文件访问、辅助功能、屏幕录制或浏览器控制授权。|
|网络|首次配置和官方更新需要|模型 API、OpenClaw npm 官方更新、Hermes 官方仓库更新都需要联网。日常使用是否联网取决于模型供应商。|
|浏览器|Edge / Chrome / Safari 均可|启动器是本地网页，默认地址为 127.0.0.1。|
|Git|Hermes 官方更新建议具备|Hermes 官方更新来自 NousResearch 官方仓库；没有 Git 时可能需要官方安装脚本自动处理或提示失败。|
4. 目录结构说明
|目录或文件|用途|能否删除|
|—|—|—|
|Windows-启动.bat|Windows 统一启动入口，打开本地面板后再选择 OpenClaw 或 Hermes。|不能删|
|Mac-启动.command|macOS 统一启动入口，打开本地面板后再选择 OpenClaw 或 Hermes。|不能删|
|AI-Agent-Portable/runtime|便携 Node 等运行时。|不能随意删|
|AI-Agent-Portable/agents|OpenClaw 和 Hermes 程序本体。|官方更新会改动|
|AI-Agent-Portable/config|模型、权限、端口、更新配置。|不要删|
|AI-Agent-Portable/data|记忆、workspace、日志、缓存、对话记录。|不要删|
|AI-Agent-Portable/data/launcher/backups|最近一次备份。|一键备份会自动维护|
5. 首次使用流程
1. 把整个“小石U盘 AGENT”文件夹复制到 exFAT 格式的 U 盘根目录，建议不要放在中文层级过深或网盘同步目录里。
2. Windows 用户双击“Windows-启动.bat”；macOS 用户右键打开“Mac-启动.command”。这两个入口都会打开统一的本地启动器页面。
3. 启动器页面打开后，在页面中分别启动 OpenClaw 或 Hermes；不再需要为两个 Agent 准备四个外层启动脚本。
4. 在“首次配置”区域选择模型供应商，填写 Base URL、模型名和 API Key。普通用户推荐先选择“两个 Agent 共用一个模型”。
5. 点击“测试连接”。看到连接成功后点击“保存配置”。
6. 回到页面上方，分别点击 OpenClaw 或 Hermes 的“启动”。启动后可以点击“进入后台”打开对应官方后台。
7. 如果只想快速聊天，可直接使用页面中间的两个简易对话框，不必进入官方后台。
6. 模型 API 配置
启动器支持两种配置方式：共用模型和分别配置。普通用户先用共用模型更简单；高级用户可以让 OpenClaw 和 Hermes 使用不同供应商、不同模型或不同 Key。
|配置方式|适合人群|操作建议|
|—|—|—|
|两个 Agent 共用一个模型|普通用户、演示、售后交付|只填一次 API Key，OpenClaw 和 Hermes 都使用同一模型。|
|只配置 OpenClaw|需要 OpenClaw 使用更强 coding 模型|选择 OpenClaw，保存后会进入分开配置模式。|
|只配置 Hermes|需要 Hermes 使用多模态或工具模型|选择 Hermes，保存后 Hermes 使用自己的配置，OpenClaw 可继续沿用共用配置。|
|安全提示<br>API Key 会保存在 U 盘 config 目录内。不要把已填好 Key 的 U 盘借给陌生人；交付给消费者时建议引导用户填写自己的 Key。|
|—|
7. 启动、关闭和进入后台
|按钮|作用|说明|
|—|—|—|
|启动|启动对应 Agent 服务|启动器会自动选择未占用端口，尽量避免和用户电脑已有服务冲突。|
|关闭|停止对应 Agent|只停止由启动器启动的进程，不会卸载软件。|
|进入后台|打开对应 Agent 官方后台|OpenClaw 可进入官方聊天和管理页；Hermes 在 Windows 官方 Chat 页受 POSIX PTY 限制。|
|简易对话|使用启动器自带对话框|适合快速问答、文件解释、演示和基础售后。|
|Hermes Windows 提醒<br>Windows 下打开 Hermes 官方后台时，官方 Chat 页不能直接对话；启动器里的 Hermes 简易对话可以正常使用。|
|—|
8. 简易对话和附件
- OpenClaw 和 Hermes 各有独立对话框，聊天记录分别保存在 U 盘数据目录。
- 可以添加图片或文本类文件。文本文件会随问题发送给模型；图片会按多模态格式发送。
- 图片能否被理解，取决于当前模型是否支持视觉输入。若模型不支持，页面会显示模型接口返回的错误。
- 为了避免 U 盘膨胀，附件内容默认不单独长期保存；历史记录只保留附件名称。
9. 官方更新、备份和还原
启动器提供官方更新入口，但它本身不托管 OpenClaw 或 Hermes 的版本。更新时分别调用各自官方渠道：OpenClaw 使用 npm 官方包 openclaw@latest，Hermes 使用 NousResearch 官方仓库和官方安装脚本。
|功能|发生了什么|用户需要知道|
|—|—|—|
|备份配置和数据|备份 config、data、agents、launcher 和外层启动脚本。|每次新备份成功后，只保留最新一份备份。|
|更新 OpenClaw|停止 OpenClaw，备份后执行 npm 官方包更新。|需要网络；更新后重新启动 OpenClaw。|
|更新 Hermes|停止 Hermes，备份后执行 Hermes 官方安装脚本更新。|需要网络，耗时可能较长。|
|全部官方更新|依次更新 OpenClaw 和 Hermes。|适合维护人员，不建议用户频繁点击。|
|一键还原|恢复最近一次备份。|更新失败或版本异常时使用。|
10. 常见问题处理
|问题|可能原因|处理方法|
|—|—|—|
|网页打不开|启动器未启动、端口被占用、浏览器拦截|重新双击启动脚本；看诊断中心；换浏览器打开 127.0.0.1 页面。|
|模型连接失败|Base URL、模型名或 API Key 不正确|先点测试连接；确认供应商地址和模型名大小写。|
|Windows 报毒或拦截|便携 Node、脚本、Python 虚拟环境被误判|从可信来源获取整包；允许本地脚本和 127.0.0.1 服务。|
|Mac 无法打开 command|系统安全策略限制|右键打开；必要时在隐私与安全性里允许。|
|Hermes 官方 Chat 页不能打字|Windows 原生 Python 无 POSIX PTY|使用启动器的 Hermes 简易对话，或在 WSL2/类 Unix 环境使用官方终端能力。|
|更新失败|网络、Git、npm、权限或文件占用|先关闭 Agent，再一键还原；之后重试或更换网络。|
|U 盘越来越大|日志、缓存、workspace 文件增加|清理缓存，转移 workspace 大文件，必要时换移动 SSD。|
11. 普通用户注意事项
- 不要在 Agent 正在运行时直接拔 U 盘，先点关闭，等页面显示未运行后再拔。
- 不要手动删除 config 和 data 目录。这里保存模型配置、记忆、workspace、日志和备份。
- 不要把自己的 API Key 发给别人。售后排查时可以截图错误提示，不要截图完整 Key。
- 如果 U 盘用于多台电脑，建议固定使用 exFAT，并保留至少 10GB 空余空间。
12. 交付前检查清单
|检查项|结果|
|—|—|
|U 盘为 exFAT，容量和剩余空间足够|□|
|Windows 启动脚本可打开本地面板|□|
|Mac 启动脚本在 Apple Silicon 上可打开|□|
|模型 API 测试连接成功|□|
|OpenClaw 可启动、关闭、进入后台|□|
|Hermes 可启动、关闭，简易对话可用|□|
|备份和一键还原路径可见|□|