📋 部署前的准备

  • 硬件：一个 USB 3.0 或以上的 U 盘或移动硬盘，速度会快很多。
  • 网络：首次启动必须联网，因为要下载 Node.js 运行时和 Claude Code 包。之后如果用云端 API 也需联网，但如果你配置了本地 Ollama 模型，就可以完全离线跑。
  • 系统：Windows 10 及以上、Linux、macOS 都支持。Windows 上需要 PowerShell，Linux/macOS 上需要 curl 和 tar。

🚀 快速部署（把 U 盘变成 AI 编程站）

第一步：下载项目到 U 盘

把整个 ClaudeCode-Portable 仓库克隆或下载到你 U 盘里的一个文件夹，比如 E:\ClaudeCode-Portable。

第二步：启动它

  • Windows：直接双击 START.bat。

  • Linux / macOS：在终端里进入文件夹，给脚本加执行权限再运行：

    1
    2
    chmod +x start.sh
    ./start.sh

首次运行会自动完成两件事：下载一个校验过的 Node.js 运行时到 engine/ 目录，然后安装固定版本的官方 Claude Code 包。这个过程可能需要几分钟，取决于你的网速和 U 盘速度。

第三步：从主菜单选择功能

启动后会看到一个菜单，最常用的选项是：

  1. 打开 Studio 仪表盘（浏览器图形界面）
  2. 启动 Claude Code 终端（命令行界面）
  3. 配置 Provider（设置 AI 模型来源）

按回车默认会打开仪表盘。

⚙️ 核心配置：选择你的 AI 模型来源

这个便携版最大的价值是支持 9 种不同的 AI 提供商，你不需要被绑定在 Anthropic 官方账号上。在菜单里选 3（Configure providers），然后按提示填写 API Key 和地址即可。

支持的提供商包括：

提供商 类型 获取方式
Anthropic Claude 官方 API console.anthropic.com
OpenRouter 聚合平台 openrouter.ai
Google Gemini 官方 API aistudio.google.com
NVIDIA NIM 官方 API build.nvidia.com
DeepSeek 官方 API platform.deepseek.com
OpenAI 官方 API platform.openai.com
Ollama 本地模型 ollama.com
LM Studio 本地模型 lmstudio.ai
自定义 API 兼容 OpenAI 的任意服务 自己填地址和 Key

一个重要的提醒：官方明确说了，非 Claude 模型是实验性的。工具调用、图片识别、上下文长度这些功能，完全取决于你选的模型和提供商支持到什么程度。

💻 两种使用方式

方式一：浏览器仪表盘（推荐新手）

在菜单里选 1，会自动打开一个本地网页。界面类似 ChatGPT，支持流式输出、Markdown 渲染、代码高亮、附件上传。你可以在里面直接聊天、让它改代码、看它执行的工具步骤，还可以在界面上直接切换不同的 Provider。

方式二：终端界面

在菜单里选 2，会打开一个类似 Claude Code 官方的命令行界面。它的会话历史和仪表盘是共享的，用同一个对话 ID，可以随时切换着用。

🔧 常见问题速查

症状 可能原因 解决方法
Windows 上 START.bat 一闪而过 Node.js 下载中断 看 engine/node-download.log，或关掉杀毒软件重试
Linux U 盘报 Cannot create symlink U 盘是 NTFS/exFAT 格式，不支持符号链接 拉取最新代码，新版会自动检测并使用免链接模式
端口 3000 被占用 之前启动的仪表盘还在跑 关掉之前的，或设置环境变量 PORTABLE_AI_PORT 换个端口
图片提示 Unsupported content: image 当前模型不支持视觉 换一个支持视觉的模型，并用 Built-in 或 Responses 适配器
本地 Ollama 连不上 本地服务没启动或地址不对 先启动 Ollama/LM Studio，确认地址（默认 127.0.0.1:11434）

⚠️ 安全提醒

这个项目的设计目标是“便携”，但它不是零痕迹沙箱。官方说明里明确提到：API Key 是以明文存在 data/settings.json 里的，所以 U 盘丢了，Key 就泄露了。另外，虽然应用自身的文件都在 U 盘里，但官方账号登录、系统级的子进程工具可能还是会用到操作系统的设施。

这个便携版很适合在受限制的电脑上（比如公司电脑没有管理员权限）临时使用，或者把自己的 AI 编程环境随身带着走。你打算主要用它的浏览器界面还是终端界面？告诉我你的使用习惯，我可以帮你看看哪个 Provider 配置起来最顺手。