📦 OpenClaude Portable 详细部署教程

OpenClaude Portable 是一个完全便携的 AI 编程助手，你可以把它放在U盘里，在任何Windows、Linux或macOS电脑上即插即用，无需安装任何软件。它集成了 Node.js 运行时、智能提示词代理和 Web 仪表板，并支持9种AI提供商。

⚙️ 部署前准备

你只需要准备两样东西：

一个U盘或任意文件夹：建议使用 USB 3.0 或更快的存储设备以获得更好性能。
网络连接：仅在首次启动时需要下载必要的组件（约30MB）。后续使用可以完全离线（如使用Ollama）。

无需：

安装 Node.js
安装 Python
管理员权限
写入系统注册表或环境变量

🚀 快速启动 (三步走)

步骤 1: 下载并解压

从 GitHub Releases 页面下载最新的 OpenClaude-Portable.zip，解压到你的U盘或本地文件夹。

步骤 2: 运行启动脚本

Windows: 双击 START.bat 文件。
Linux / macOS: 打开终端，进入项目目录，运行 ./start.sh（首次需赋予执行权限：chmod +x start.sh）。

步骤 3: 跟随首次设置向导

自动下载：脚本会自动下载并配置 Node.js 运行时和 OpenClaude 引擎 (~5MB)。
选择 AI 提供商：在菜单中选择你希望使用的AI服务（如DeepSeek、OpenRouter、Ollama等）。
配置 API 密钥：根据提示输入所选提供商的 API Key。密钥只保存在你U盘上的 data/ai_settings.env 文件中。
开始使用：配置完成后，你会看到主菜单，选择 Launch AI 即可开始。

🎮 主菜单与核心功能

每次运行 START.bat 或 start.sh，你都会看到这个菜单：

1) Launch AI       — 普通模式 (文件写入或运行命令前会询问)
2) Limitless Mode  — 无限模式 (完全自主，无需批准)
3) Open Dashboard  — 打开 Web 界面 (http://localhost:3000)
4) Change Provider — 更换 AI 提供商或 API 密钥
5) Setup Offline   — 下载本地 Ollama 模型 (用于完全离线)

普通模式 (Normal Mode)：默认选项，安全可控，适合日常使用。
无限模式 (Limitless Mode)：代理完全自主运行，适合信任的自动化任务。
Web 仪表板 (Dashboard)：在浏览器中打开类似 ChatGPT 的图形界面，可视化操作代理。

🔧 配置 AI 提供商

支持的AI服务 (9种)

提供商	费用	推荐场景	配置要点
NVIDIA NIM	免费额度 (1000积分/月)	快速体验	需在 build.nvidia.com 注册获取Key
DeepSeek	付费API	高性价比中文模型	platform.deepseek.com 获取Key
OpenRouter	免费+付费模型	多模型切换	openrouter.ai 获取Key
Google Gemini	免费额度	多模态任务	aistudio.google.com 获取Key
Anthropic Claude	付费	高质量编码	console.anthropic.com 获取Key
OpenAI	付费	通用任务	platform.openai.com 获取Key
Ollama	完全免费，离线	隐私敏感、无网络环境	使用工具菜单中的 “Setup Offline” 下载模型
LM Studio	免费，本地运行	本地模型管理	需先在LM Studio中启动本地服务器 (http://localhost:1234/v1)
自定义API	取决于提供商	使用任意OpenAI兼容接口	需填写Base URL、模型名和可选Key

更换提供商

随时运行主菜单的 Change Provider 选项，或在Web仪表板的设置中更改。

📂 项目结构与数据持久化

所有数据都保存在项目目录下的 data/ 文件夹中，因此整个文件夹可以随意移动或复制到其他电脑，所有配置和会话历史都会保留。

data/
├── ai_settings.env        # 当前选择的提供商、模型和API密钥
├── openclaude/            # 会话历史、记忆、工作区
├── ollama/                # Ollama 本地模型文件 (如果下载)
└── proxy.log              # 本地代理日志 (用于调试)

💡 高级技巧与性能优化

1. 加速本地模型 (Ollama)

在普通U盘或CPU上运行大模型可能会慢。OpenClaude Portable 内置了一个 “速度代理” (local-proxy.js)：

它会在请求发送到 Ollama 前，将系统提示词从约 10,000 个 token 压缩到约 300 个 token。
效果：首次响应延迟从 60-120 秒降低到 5-20 秒 (在CPU上)。
推荐的轻量模型：gemma3:1b (最快)、qwen2.5:1.5b、phi3:mini。

2. 恢复中断的会话

如果你意外关闭了终端，可以使用 RESUME.bat <会话ID> (Windows) 来恢复之前的会话。

3. 完全离线使用

在有网络时，运行 START.bat 选择 Setup Offline 下载一个 Ollama 模型。
之后，选择 Ollama 作为提供商，无需任何网络连接即可使用。

❓ 常见问题与故障排查

Q: 第一次启动很慢？
- A: 正常现象。首次启动会下载 Node.js (~~25MB) 和引擎 (~~5MB)，在较慢的USB设备上可能需要10-15分钟。请耐心等待，或先在本地硬盘完成初始化，再将整个文件夹复制到U盘。
Q: 提示 “Node.js not found”？
- A: 不要手动安装Node.js。请确保先运行 START.bat 让它自动下载，而不是直接调用 engine/node-win-x64/node.exe。
Q: 端口被占用 (EADDRINUSE: port 11435)？
- A: 说明上一次运行的代理进程没有完全关闭。重启 START.bat 即可，它会自动清理。
Q: Windows 下要求 git-bash？
- A: 确保 START.bat 是最新版本。它现在会自动下载并捆绑一个便携版Git，无需你手动安装。
Q: 如何更新到最新版本？
- A: 下载最新的发布压缩包，将你旧版 data/ 文件夹（包含所有配置和会话）复制到新版本目录中，然后运行新版本的 START.bat 即可。