基于Docker的便携式AI助手部署：打造跨平台私人智能体

1. 项目概述：打造你的“口袋AI”，一个随插随用的私人智能体

如果你和我一样，经常需要在不同的电脑上工作——办公室的台式机、家里的笔记本，甚至偶尔借用朋友的电脑——那么一个能随身携带、开箱即用的AI助手，绝对是效率神器。今天要聊的，就是这样一个项目：PocketClaw，我习惯叫它“口袋龙虾”。它的核心目标很简单：把一个功能完整的AI助手，连同它的运行环境、配置和数据，全部塞进一个U盘里。你只需要把这个U盘插到任何一台电脑上，双击运行，几分钟内就能获得一个完全属于你、且高度私密的AI对话环境。

这不仅仅是把网页版ChatGPT做成快捷方式那么简单。PocketClaw基于开源的OpenClaw项目构建，但做了大量“便携化”和“安全加固”的工作。它通过Docker容器技术，将AI助手的服务端、Web界面、乃至一个无头浏览器环境，全部打包。你的所有配置、聊天记录、甚至是AI的人格设定（Agent），都加密存储在U盘里，与宿主机完全隔离。这意味着，你可以在公司电脑上用它处理工作，回家后拔下U盘，插到自己的电脑上，刚才的对话上下文和所有设置都原封不动，而公司电脑上不会留下任何痕迹。

对于国内用户而言，它的另一个巨大优势是对中文AI生态的深度集成。项目默认并强烈推荐使用iFlow心流或智谱AI的GLM-4.7-Flash作为后端，两者目前都有可观的免费额度，足以满足日常使用。当然，它也完整支持OpenAI、Claude、DeepSeek等十余家主流厂商。你可以把它看作一个完全本地化、可定制的AI聚合客户端，摆脱了对特定网站或App的依赖，真正将AI能力“私有化部署”到了你的口袋里。

无论是开发者想随时有一个编码助手，学生党需要在图书馆电脑上查资料写论文，还是商务人士出差时处理邮件和文档，PocketClaw都提供了一个极其优雅的解决方案。它降低了使用门槛——你不需要懂Docker命令，也不需要配置复杂的环境变量；同时它又坚守了安全底线——所有敏感信息加密存储，用完即焚。接下来，我就带你深入拆解这个“口袋AI”的里里外外，从设计思路到实操细节，再到我踩过的坑和总结的经验，让你不仅能会用，更能理解其背后的精妙之处。

2. 核心架构与设计哲学：为什么是Docker+U盘？

2.1 技术选型的底层逻辑

为什么选择“Docker容器”加“U盘”这种组合？这背后是一系列权衡后的最优解。我们逐层分析：

第一层：环境一致性难题。AI应用，尤其是像OpenClaw这样的项目，依赖复杂的运行时环境（Node.js、Python包、系统库等）。不同操作系统（Windows/macOS/Linux）、甚至同一系统的不同版本，环境都可能千差万别。“在我电脑上能跑，在你那就报错”是常态。Docker的核心价值就在于环境隔离与标准化。它将应用及其所有依赖打包成一个镜像，在任何安装了Docker引擎的机器上，都能以完全相同的方式运行，彻底解决了“环境地狱”问题。

第二层：数据便携与安全诉求。我们希望AI助手是“属于个人”的，数据跟着人走，而不是跟着某台电脑。U盘（或移动硬盘）是物理层面最直观的便携载体。但直接将应用和数据放在U盘里，面临两个问题：一是跨平台文件系统兼容性（NTFS在macOS上只读，APFS在Windows上不识别），二是数据安全（U盘丢了怎么办？）。因此，项目选择ExFAT格式的U盘作为存储介质，因为它被三大操作系统广泛支持。同时，所有敏感配置（API Key、密码）都经过AES-256加密后才存入U盘。

第三层：用户体验与自动化。目标用户可能不是开发者，他们需要的是“双击即用”。因此，项目必须实现全自动化：自动检测并安装Docker、自动配置网络和镜像加速、自动构建和启动容器、甚至自动打开浏览器。这一系列操作被封装在PocketClaw.bat（Windows）和PocketClaw.command（macOS）这两个启动器中，用户无需接触命令行。

第四层：安全边界与风险控制。Docker容器虽然提供了隔离，但并非铁板一块。一个配置不当的容器可能成为攻击宿主机的跳板。PocketClaw在docker-compose.yml中进行了严格的安全加固：容器以非root用户运行、丢弃所有Linux能力（cap_drop: ALL）、禁止提权（no-new-privileges）、限制内存和进程数量。更重要的是，它设计了敏感信息生命周期管理：加密的配置文件仅在启动时被解密到内存，启动后立即用随机数据覆写磁盘上的明文文件，最大限度减少攻击窗口。

2.2 项目目录结构深度解析

理解目录结构，是掌握项目管理和故障排查的基础。PocketClaw的目录设计清晰地区分了“系统文件”、“用户配置”和“运行时数据”。

PocketClaw/ ├── PocketClaw.bat (.command) # 【灵魂】统一启动入口，处理所有平台差异 ├── Doctor.bat (.command) # 独立诊断工具，用于救急 ├── docker-compose.yml # Docker容器编排定义，所有服务依赖关系在此 ├── Dockerfile.custom # 自定义镜像构建文件，可在此添加额外依赖 ├── config/ # 核心配置目录 │ ├── openclaw.json # OpenClaw主配置，定义Gateway行为、模型参数等 │ ├── providers.json # 【关键】12家AI提供商的API端点、模型列表定义 │ ├── mobile.html # 为手机浏览器优化的PWA界面 │ └── workspace/ # Agent的“大脑”，人格和技能定义（系统内部使用） ├── 工作区/ # 【用户交互区】v1.3.0后，用户编辑的Agent人格文件移至此 │ ├── AGENTS.md # 你可以在这里定义AI的行为指令（如“扮演一个资深程序员”） │ ├── SOUL.md # 你可以在这里定义AI的底层人格（如“严谨、乐于助人”） │ └── skills/ # 自定义技能存放处（需按OpenClaw规范编写） ├── data/ # 【动态数据】所有运行时产生的数据 │ ├── credentials/ # 各聊天频道（如Telegram Bot）的链接凭证 │ ├── sessions/ # 聊天会话历史记录，实现上下文延续 │ ├── logs/ # 容器和应用的运行日志，排查问题的第一现场 │ └── .build_hash # 镜像构建指纹，用于缓存，实现二次启动秒开 ├── secrets/ # 【安全核心】加密存储区 │ └── .env.encrypted # 经过AES-256加密的.env文件，包含所有API Key和密码 └── scripts/ # 【自动化引擎】所有幕后脚本 ├── _common.sh # 公共函数库，被其他脚本调用 ├── start.sh # 启动流程的总控制器 ├── encrypt-secrets.sh # 加密脚本，使用OpenSSL AES-256-CBC ├── doctor.sh # 自诊断脚本，包含11项健康检查 └── ... (其他功能脚本)

实操心得：几个关键目录的用途

• 工作区/vsconfig/workspace/：这是最容易混淆的地方。简单来说，工作区/是给你看的、给你改的；config/workspace/是给OpenClaw系统内部用的。当你修改工作区/AGENTS.md后，启动脚本会自动将其同步到内部目录。不要直接修改config/workspace/下的文件。
• data/目录的重要性：你的所有聊天记录、自定义技能都保存在这里。定期备份这个目录，就等于备份了你的AI使用历史。项目自带的备份脚本默认会备份它。
• secrets/目录的敏感性：这个目录里的.env.encrypted文件是你的数字钥匙。丢了它或者忘了密码，就无法解密你的配置。务必妥善保管U盘。

2.3 安全模型与威胁应对策略

安全是PocketClaw设计的重中之重。它的安全模型是分层防御的，针对不同的威胁场景有不同的应对措施。

威胁场景一：U盘丢失或被盗。

• 防护措施：所有敏感信息（API Keys、Gateway密码）存储在secrets/.env.encrypted中，使用AES-256-CBC算法加密，密钥由你设置的Master Password通过PBKDF2函数派生。没有密码，攻击者无法解密文件内容。
• 技术细节：加密命令类似openssl enc -aes-256-cbc -pbkdf2 -in .env -out .env.encrypted。PBKDF2（Password-Based Key Derivation Function 2）是一种密钥派生函数，它能将你的密码（即使比较简单）与一个随机盐值（salt）进行多次哈希运算，生成一个强加密密钥，有效抵御彩虹表攻击。

威胁场景二：在公共电脑上使用，担心进程被窥探。

• 防护措施：脚本在解密时，使用printf ‘%s’ “$PASS” | openssl … -pass stdin的方式传递密码。printf是Shell内置命令，不会在进程列表（ps aux）中显示密码参数。在Windows上，则使用PowerShell的Read-Host -AsSecureString，输入时显示为星号。
• 防护措施：解密后的明文.env文件仅在内存中用于启动Docker容器，一旦容器启动成功，脚本会立即用/dev/urandom生成的随机数据覆写该文件，然后再删除。这在一定程度上对抗了磁盘文件恢复工具。

威胁场景三：容器本身被攻击。

• 防护措施：Docker Compose配置中设置了严格的安全限制：

  security_opt: - no-new-privileges:true # 禁止进程提升权限 cap_drop: - ALL # 丢弃所有Linux能力，容器能做的事件少 read_only: true # 根文件系统只读 pids_limit: 128 # 限制最大进程数，防止Fork炸弹 mem_limit: 2g # 限制内存使用

• 局限性：需要清醒认识到，如果攻击者已经控制了宿主机并拥有root或Docker守护进程权限，他可以通过docker inspect <容器名>命令查看到容器内设置的所有环境变量，包括解密后的API Key。这是Docker架构层面的限制，无法通过容器内配置解决。因此，绝对不要在你不信任的电脑上使用PocketClaw。

威胁场景四：网络嗅探。

• 防护措施：所有与AI提供商API的通信均使用HTTPS加密。Gateway与本地浏览器之间的通信在本地回环地址（127.0.0.1）上进行，不经过外部网络。
• 手机访问：当你在手机浏览器通过局域网IP访问时，通信在本地WiFi网络内，相对于公网更安全，但仍建议在可信的网络环境中使用。

安全红线：物理安全是最后一道，也是最重要的一道防线。将PocketClaw U盘视为你的家门钥匙。如果U盘落入拥有高级技能且能物理接触你电脑的攻击者手中，没有方案是绝对安全的。定期更换API Key和Master Password是良好的安全习惯。

3. 从零开始：全平台部署与首次配置实操

3.1 前期准备与U盘选择

工欲善其事，必先利其器。选择一个合适的U盘是第一步。

• 容量：推荐至少64GB。Docker镜像本身大约需要2-3GB空间，加上系统文件、聊天数据、备份等，32GB会显得捉襟见肘。64GB或以上能让你安心存储大量会话历史。
• 速度：强烈建议选择USB 3.2 Gen 1（即USB 3.0）或更高速度的U盘。首次构建Docker镜像时需要下载和编译大量内容，速度慢的U盘可能让这个过程长达半小时。高速U盘能将首次构建时间控制在10分钟以内，后续启动几乎是秒开。
• 格式：必须格式化为ExFAT。这是macOS、Windows和Linux都能完美读写（无需额外驱动）的唯一通用格式。不要在macOS上用“磁盘工具”默认的APFS，也不要在Windows上格式化为NTFS。
  • Windows格式化：右键点击U盘 -> 格式化 -> 文件系统选择“exFAT”，分配单元大小“默认”。
  • macOS格式化：打开“磁盘工具” -> 选择U盘 -> 点击“抹掉” -> 格式选择“ExFAT”，方案“主引导记录”。
• 安全（可选）：如果你对数据安全有极高要求，可以考虑购买支持硬件加密的U盘（如金士顿IronKey），或者使用VeraCrypt在U盘上创建一个加密容器分区，再将PocketClaw放入其中。但这会增加一些使用复杂度。

3.2 Windows系统首次启动全流程（含避坑指南）

对于Windows用户，PocketClaw的自动化程度最高，但也是最容易遇到环境问题的平台。我们来一步步走通，并解释每个环节背后的原理。

步骤1：获取项目文件。从GitHub仓库（ProjectAILiberation/PocketClaw）下载最新的Release包（ZIP格式），解压到你的ExFAT格式U盘的根目录。你会得到一个名为PocketClaw的文件夹。

步骤2：双击启动，信任程序。进入PocketClaw文件夹，双击PocketClaw.bat。此时，Windows SmartScreen可能会弹出警告，提示“来自未知发布者”。这是因为批处理文件没有数字签名。

• 操作：点击“更多信息”，然后点击“仍要运行”。如果你不放心，可以用记事本打开这个.bat文件查看内容，它本质上是调用了scripts\目录下的PowerShell脚本。

步骤3：自动化安装依赖。这是最关键的环节。脚本会依次检测并安装以下组件：

1. WSL2 (Windows Subsystem for Linux 2)：Docker Desktop for Windows 依赖于WSL2来运行Linux内核。如果系统未启用，脚本会尝试自动启用并安装一个轻量级的Linux发行版（通常是Ubuntu）。
2. Docker Desktop：脚本会检测是否已安装Docker Desktop。如果未安装，它会使用U盘内自带的安装包（或从网络下载）进行静默安装。这里常见的坑是：公司网络可能有代理或软件限制，导致Docker Desktop下载或安装失败。如果卡住，你可以手动去Docker官网下载Docker Desktop Installer.exe，放在U盘根目录，脚本会优先使用它。
3. Git：用于后续的版本检查和一些脚本功能。通常Windows系统可能没有，脚本会引导你安装。

步骤4：面对“首次启动”菜单。所有依赖安装完成后，会弹出命令行窗口，显示一个文本菜单。选择[1] 启动。

• 系统可能会弹出多个用户账户控制（UAC）窗口，请求管理员权限来安装软件或修改系统配置。务必点击“是”。

步骤5：配置向导。接下来会进入交互式配置向导：

1. 选择AI提供商：你会看到一个列表。对于国内用户，无脑选择1) iFlow 心流或2) 智谱AI。我推荐iFlow，因为它聚合了多个优质模型（如DeepSeek、Qwen），且有免费额度。脚本会自动打开浏览器，引导你注册并获取API Key。
2. 输入API Key：将你在网站上复制的API Key粘贴到命令行中。注意：粘贴时可能没有视觉反馈（这是为了安全），直接按回车即可。
3. 设置主密码（Master Password）：这是用来加密你所有配置的密码。务必牢记！如果忘记，无法恢复，只能重置所有配置。输入时同样无视觉反馈，输入两遍确认。

步骤6：等待镜像构建。配置完成后，脚本会开始构建Docker镜像。这是最耗时的一步，取决于你的网速和U盘速度。屏幕上会滚动输出Docker构建日志。首次构建通常需要5-15分钟。请耐心等待，不要关闭窗口。

• 如果卡在某个步骤（如下载node镜像），可能是网络问题。你可以按Ctrl+C中断，然后尝试配置代理（后续会讲），或换个网络环境再试。

步骤7：启动成功。构建完成后，Docker容器会自动启动。脚本会生成一个随机的访问Token，并自动用你的默认浏览器打开聊天界面（URL类似http://127.0.0.1:18789/#token=abc123...）。看到OpenClaw的聊天界面，就意味着成功了！

Windows专属避坑指南：

• Hyper-V/WSL2冲突：如果你电脑上安装了VMware或VirtualBox等基于Hyper-V的虚拟机，可能与WSL2冲突。建议在BIOS中确保虚拟化（VT-x/AMD-V）已开启，并关闭冲突的虚拟机软件。
• 杀毒软件拦截：部分杀毒软件（如360、火绒）可能将Docker或脚本行为误判为风险。请将PocketClaw目录添加到信任区。
• 端口占用：默认端口是18789。如果该端口被其他程序占用，启动会失败。你可以修改docker-compose.yml文件中的端口映射，例如将18789:18789改为18790:18789。
• 拔U盘前务必停止：一定要在菜单中选择[2] 停止，等待脚本提示“可以安全移除U盘”后再拔出。强制拔出可能导致数据损坏。

3.3 macOS系统首次启动详解

macOS的体验通常比Windows更顺畅，因为Unix底层与Docker的亲和性更好。

步骤1：获取并放置文件。同Windows，解压到ExFAT格式的U盘根目录。

步骤2：解决权限问题。首次双击PocketClaw.command时，macOS可能会提示“无法打开，因为来自身份不明的开发者”。

• 操作：打开“系统设置” -> “隐私与安全性” -> 向下滚动，找到关于“PocketClaw.command”的阻止信息，点击“仍要打开”。或者，在Finder中右键点击该文件 -> “打开”，然后在弹出的对话框中点击“打开”。

步骤3：自动化安装Docker。脚本会智能选择安装方式：

1. 首选Homebrew：如果你的系统已安装Homebrew（macOS包管理器），它会通过命令brew install --cask docker来安装Docker Desktop，这是最干净的方式。
2. 备选Colima：如果Homebrew安装失败或你没有Homebrew，脚本会尝试安装Colima——一个更轻量级的Docker运行时。它不包含Docker Desktop的GUI，但完全兼容Docker CLI。
3. 兜底方案：如果上述都失败，脚本会直接下载Docker Desktop的.dmg安装包（约600MB）并引导你安装。

步骤4：后续流程。与Windows类似，通过菜单选择启动、配置AI提供商和密码、构建镜像。由于macOS的文件系统性能通常更好，首次构建速度可能略快于Windows。

macOS专属提示：

• Apple Silicon (M1/M2/M3) 兼容性：完全支持。Docker镜像会自动拉取匹配arm64架构的版本。
• 菜单栏Docker图标：如果通过Homebrew安装了Docker Desktop，它会在菜单栏显示一个鲸鱼图标。你可以从这里管理容器、配置资源等。PocketClaw脚本会自动处理Docker Desktop的后台启动。

3.4 Linux系统部署要点

Linux用户通常是技术爱好者，过程相对直接。

1. 安装Docker Engine：如果你的系统没有Docker，需要先安装。可以使用项目推荐的命令：

   curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # 将当前用户加入docker组，避免每次用sudo

   执行完usermod后，你需要注销并重新登录，或者新开一个终端，用户组变更才会生效。
2. 安装Docker Compose插件：现代Docker Engine已包含Compose插件。如果没有，可运行sudo apt-get install docker-compose-plugin(Ubuntu/Debian)。
3. 运行启动脚本：进入U盘中的PocketClaw目录，直接运行bash scripts/start.sh。后续的配置向导与macOS/Windows一致。

Linux注意事项：确保你的用户有U盘目录的读写权限。有时从其他系统创建的U盘，在Linux下挂载后权限是root，你需要用chmod更改目录所有权。

4. 核心功能实战：配置、使用与高级技巧

4.1 AI提供商配置与切换实战

PocketClaw支持12家AI提供商，这是它的核心优势之一。我们来深入看看如何管理和切换它们。

理解config/providers.json这个文件是AI提供商的总目录。它以JSON格式定义了每个提供商的名称、API基础地址、默认模型、可用模型列表以及认证方式（通常是API Key放在请求头）。例如，iFlow的配置片段可能如下：

{ “iflow”: { “name”: “iFlow 心流”, “api_base”: “https://api.iflow.cn/v1”, “default_model”: “deepseek-v3.2”, “models”: [“deepseek-v3.2”, “qwen3.5”, “kimi-k2”], “auth_header”: “Authorization”, “auth_prefix”: “Bearer ” } }

你一般不需要手动修改这个文件，除非某个提供商的API地址发生了变化。

如何获取免费的API Key？

1. iFlow心流：启动配置向导时，脚本会自动打开https://iflow.cn的注册/登录页面。注册后，在控制台通常能找到“获取API Key”或“创建应用”的选项。复制生成的Key即可。iFlow经常提供免费额度，是起步的最佳选择。
2. 智谱AI：访问https://bigmodel.cn，注册并实名认证（通常很简单）。在控制台创建API Key。GLM-4.7-Flash模型有长期免费额度，速度很快。
3. 硅基流动：另一个优秀的国内聚合平台，也提供免费额度。注册流程类似。

切换提供商或API Key这是高频操作。你不需要手动编辑任何加密文件。

1. 运行PocketClaw.bat或PocketClaw.command，进入主菜单。
2. 选择[4] 切换模型/API Key。
3. 脚本会列出所有支持的提供商，让你选择。
4. 输入新的API Key。
5. 脚本会要求你再次输入Master Password（用于重新加密配置文件）。
6. 完成后，脚本会询问是否立即重启容器以应用更改。选择“是”，等待重启即可。

实操心得：API Key管理

• 定期检查额度：免费额度会用完。定期到对应平台的控制台查看剩余额度，避免聊天突然中断。
• 备用Key：建议至少配置两个提供商的API Key（如iFlow和智谱）。当一个出问题或额度用完时，可以快速切换。
• 环境变量：切换操作本质上是修改了secrets/.env.encrypted文件解密后的OPENAI_API_KEY、OPENAI_API_BASE等环境变量。你可以在解密后手动编辑.env文件来实现更复杂的配置（如同时配置多个备用Key），但这需要一定的技术知识。

4.2 与AI对话：Web界面与手机端优化

启动成功后，你主要通过Web界面与AI交互。

电脑端：浏览器会自动打开http://127.0.0.1:18789/chat#token=xxx。这个界面功能完整，支持对话、切换模型、查看会话历史等。

手机/平板端：这是PocketClaw的一大亮点。

1. 确保手机和运行PocketClaw的电脑在同一个WiFi网络下。
2. 在电脑端的启动菜单或命令行日志中，找到类似[手机] http://192.168.1.100:18789/mobile.html#token=xxx的地址。192.168.1.100是你电脑的局域网IP。
3. 在手机浏览器中输入这个地址，即可打开一个为移动端优化的聊天界面。
4. 添加到主屏幕（PWA）：
   • iPhone (Safari)：点击底部分享按钮 -> 滚动找到“添加到主屏幕”。
   • Android (Chrome)：点击右上角三个点 -> “添加到主屏幕”。 这样，你的手机桌面上就会出现一个像原生App一样的图标，点开就能直接聊天，体验非常接近ChatGPT官方App。

聊天命令在输入框中，除了普通对话，还可以使用一些命令：

• /status：查看当前会话状态，包括使用的模型、Token消耗情况。
• /new或/reset：开始一个新的会话，清空上下文。
• /think medium：设置AI的“思考深度”。off（快速）、low、medium、high（深度思考，更慢但可能更准）。
• /verbose on：开启详细模式，AI会输出更多的中间思考过程（如果模型支持）。

4.3 配置聊天频道（连接Telegram、Discord等）

这是OpenClaw的进阶功能，让你能在常用的聊天软件里直接和你的AI助手对话。PocketClaw通过脚本极大地简化了配置过程。

以配置Telegram Bot为例（最推荐，最简单）：

1. 在Telegram中搜索@BotFather（官方Bot创建工具）。
2. 向它发送/newbot命令。
3. 按提示输入你的Bot名称（如My PocketClaw Bot）和用户名（必须以bot结尾，如my_pocket_claw_bot）。
4. BotFather会生成一个HTTP API Token，格式像1234567890:ABCdefGhIjKlMnOpQrStUvWxYz。复制并保存好这个Token，它只会显示一次。
5. 在PocketClaw目录下，运行脚本：bash scripts/setup-channels.sh（macOS/Linux）或scripts\setup-channels.bat（Windows）。
6. 在交互式向导中，选择配置Telegram。
7. 将刚才复制的Token粘贴进去。
8. 脚本会更新加密的配置文件，并重启相关服务。
9. 重启后，在Telegram中找到你的Bot（通过它的用户名），发送/start消息，就可以开始聊天了！

其他频道配置逻辑类似，都需要在对应的开发者平台创建应用（App）或机器人（Bot），获取Token或密钥，然后通过向导填入。scripts/setup-channels.sh这个脚本是神器，它把复杂的OAuth、回调地址配置等流程都封装成了简单的问答。

注意事项：

• 网络要求：你的运行PocketClaw的电脑必须能访问外网，因为Telegram/Discord的Bot需要连接它们的官方服务器。
• Token安全：Bot Token相当于你Bot的密码，一旦泄露，别人就可以控制你的Bot。PocketClaw会将其加密存储在U盘中。
• 频道冲突：如果你配置了多个频道（如同时开了Telegram和Discord），同一个AI助手会响应所有频道的消息。你可以通过不同的Agent人格文件来让它在不同频道表现不同性格。

4.4 代理网络配置

如果你的网络环境需要代理才能访问OpenAI、Claude等国际AI服务，PocketClaw也提供了配置入口。

方法一：首次启动向导在首次启动配置AI提供商时，如果脚本检测到网络不通，可能会询问你是否需要配置代理。你可以输入你的代理地址，例如http://127.0.0.1:7897（这是Clash等代理软件的典型本地端口）。

方法二：手动配置

1. 停止PocketClaw服务（在主菜单中选择[2] 停止）。
2. 解密配置文件：bash scripts/decrypt-secrets.sh（输入Master Password）。
3. 编辑解密后生成的.env文件，添加或修改以下行：

   HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897

   如果你的代理需要认证，格式为：http://username:password@proxy-server:port。
4. 重新加密配置文件：bash scripts/encrypt-secrets.sh。
5. 重新启动PocketClaw。

方法三：在Docker Desktop中配置对于Docker Desktop for Windows/macOS，你可以在其设置中配置代理，这样所有容器都会使用这个代理。

• macOS：Docker Desktop -> Settings -> Resources -> Proxies。
• Windows：Docker Desktop -> Settings -> Resources -> Proxies。

重要提示：国内模型（智谱、iFlow、DeepSeek国内版、通义千问等）的API服务器在国内，通常不需要配置代理。配置代理反而可能导致访问变慢或失败。建议只为需要访问国际服务的提供商配置代理。

5. 维护、故障排查与备份策略

5.1 日常维护操作

通过主菜单，你可以完成绝大多数日常操作：

• [1] 启动/[2] 停止：最常用的两个选项。务必先停止再拔出U盘。
• [3] 打开聊天页面：如果浏览器窗口被关闭，可以用这个选项重新打开。
• [4] 切换模型/API Key：如前所述。
• [5] 备份数据：将当前配置、脚本和（可选）会话数据备份到电脑硬盘（默认在~/PocketClaw_Backup）。备份是增量的，并会保留最近5个版本。
• [6] 自诊断修复：这是排障神器。它会自动运行11项检查，包括Docker状态、端口占用、配置文件完整性、API连通性等，并调用AI分析日志给出建议。
• [7] 检查更新：从官方服务器检查是否有新版本，并引导你完成一键更新。

5.2 常见问题与解决方案（FAQ）

以下是我在长期使用中遇到的一些典型问题及解决方法：

Q1: 双击启动器后，窗口一闪而过，什么都没发生。

• 原因：最常见的原因是系统缺少必要的运行时库（如Windows的VC++ Redistributable）或脚本执行策略限制。
• 解决：
  • Windows：以管理员身份打开PowerShell，执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，然后重试。或者，直接进入scripts\目录，右键点击start.bat-> “以管理员身份运行”。
  • macOS/Linux：打开终端（Terminal），cd到PocketClaw目录，手动运行bash scripts/start.sh，查看具体的错误输出。

Q2: 首次构建镜像时，卡在Downloading Docker Desktop...或下载镜像极慢。

• 原因：网络连接Docker Hub或GitHub不稳定。
• 解决：
  • 配置镜像加速器：对于国内用户，脚本会尝试自动配置国内镜像源。如果失败，可以手动修改Docker Desktop的配置。在Docker Desktop设置中，找到Docker Engine，添加或修改registry-mirrors为国内镜像地址，如https://docker.mirrors.ustc.edu.cn/。
  • 使用代理：如果你的网络需要代理，请先配置好系统或Docker Desktop的代理设置。
  • 手动下载：如果某个基础镜像（如node:20-alpine）始终拉取失败，可以尝试在网络好的环境下，先用docker pull node:20-alpine拉取，再运行PocketClaw。

Q3: 启动后，浏览器打开显示“无法连接”或“Invalid Token”。

• 原因1：容器启动失败。Docker容器可能因为端口冲突、资源不足或配置错误而未能成功运行。
• 解决1：在主菜单中选择[6] 自诊断修复。它会检查容器状态和日志。最常见的是端口18789被占用。你可以修改docker-compose.yml文件，将第一个端口号改为其他未被占用的端口（如18790:18789）。
• 原因2：复制粘贴的URL中Token不完整或错误。
• 解决2：直接从启动菜单或命令行日志中复制完整的URL，确保#token=后面的长字符串完整。

Q4: 聊天时，AI回复“Invalid API Key”或“额度不足”。

• 原因：API Key无效、过期或免费额度已用完。
• 解决：使用菜单[4] 切换模型/API Key，重新输入一个有效的Key，或切换到另一个有额度的提供商（如从iFlow切换到智谱）。

Q5: 在Mac上，Docker Desktop一直显示“Docker Desktop is not running”。

• 原因：Docker Desktop没有在后台启动，或者启动失败。
• 解决：手动打开“Docker Desktop”应用，等待鲸鱼图标在菜单栏稳定出现（不是跳动状态）。然后重新运行PocketClaw启动脚本。

Q6: 忘记Master Password怎么办？

• 残酷的现实：无法恢复。Master Password用于加密你的配置文件，没有它，无法解密.env.encrypted文件。
• 唯一办法：删除secrets/.env.encrypted文件，然后重新运行启动脚本，走一遍首次配置流程。这意味着你会丢失所有已保存的API Key和频道配置，需要重新输入。这凸显了牢记密码或使用密码管理器的重要性。

5.3 数据备份与迁移

你的数据资产主要在两个地方：data/目录（会话、日志）和secrets/.env.encrypted（加密配置）。

自动备份使用菜单[5] 备份数据是最简单的方式。它会将核心文件打包并复制到你的用户目录下（如~/PocketClaw_Backup/2025-01-15_10-30-00/），并保留最近5个备份。

手动备份如果你需要更精细的控制，可以手动复制整个PocketClaw文件夹到另一个安全的位置（如另一个U盘、电脑硬盘或云盘）。这是最完整的备份。

迁移到新U盘或新电脑

1. 在旧环境中，正常停止PocketClaw（菜单[2] 停止）。
2. 将整个PocketClaw文件夹复制到新U盘或新电脑。
3. 在新电脑上，确保已安装Docker（首次运行启动脚本会自动安装）。
4. 双击启动器。因为Docker镜像缓存（在Docker的存储目录中）没有跟随U盘，所以首次启动可能会重新构建或拉取镜像，但你的所有配置和数据都会保留。

版本更新当有新版本发布时，使用菜单[7] 检查更新。更新脚本会智能地覆盖程序文件（如脚本、配置文件），但会保留你的data/、secrets/和工作区/目录。更新完成后，通常需要重启容器。

5.4 高级技巧：自定义Agent人格与技能

PocketClaw的魅力在于它的可定制性。你可以让AI扮演不同的角色。

修改Agent人格编辑工作区/AGENTS.md文件。这个文件使用特定的标记来定义不同场景下的AI行为。例如：

# 通用助手 你是一个乐于助人、知识渊博的AI助手。 ## 编程模式 当我询问编程相关问题时，请切换到编程专家角色。 - 优先提供可运行的代码片段。 - 解释代码的关键逻辑。 - 考虑代码的性能和最佳实践。 ## 写作模式 当我要求写作或润色文本时，请切换到资深编辑角色。 - 保持语言流畅、优美。 - 根据要求调整风格（正式、口语、学术等）。 - 提供修改建议和理由。

保存文件后，重启PocketClaw容器，AI就会根据你的指令来调整它的回应风格。你可以通过/status命令查看当前激活的Agent。

安装自定义技能OpenClaw支持“技能”（Skills），这是更强大的功能扩展。社区开发的技能可以让你用自然语言命令AI执行特定任务，比如“总结这个网页内容”、“把这段代码转换成Python”等。

1. 将技能文件（通常是.js或.py文件）放入工作区/skills/目录。
2. 技能可能需要额外的依赖。你可以在Dockerfile.custom文件中添加安装命令，然后重建镜像（这需要一些Docker知识）。
3. 重启容器后，AI就能识别并使用新技能。

最后的建议：PocketClaw是一个将强大AI能力“平民化”、“便携化”的优秀项目。它最大的价值在于让你完全掌控自己的AI交互数据和环境。花点时间熟悉它的目录结构和脚本，你就能更好地驾驭它，让它成为你真正得力的数字伴侣。从简单的随身问答，到连接Telegram Bot成为你的私人秘书，它的可能性由你定义。如果在使用中遇到任何问题，除了使用自带的诊断工具，查阅项目GitHub仓库的Issues和文档，通常能找到答案。