Claude Code UI双端可视化指南：十分钟手残党也能部署AI编程神器

高效码农

15 小时前

把 Claude Code 搬进浏览器：一份写给所有开发者的桌面 & 手机双端可视化指南

——从安装到日常使用的完整路线图

“

“我已经在终端里用 Claude Code 写代码，但想在手机上随时查看项目进度，有没有更直观的方法？”
“团队成员不会用命令行，能否给他们一个点-点-点的界面？”
如果你有类似的疑问，这篇文章正好能一步步带你把官方 CLI 变成人人可用的图形界面。

本文解决的核心问题

读者常见疑问	一句话答案
Claude Code 是什么？	Anthropic 官方推出的 AI 辅助编程命令行工具。
Claude Code UI 又是什么？	一个开源的前端项目，把上面的命令行封装成网页，支持电脑和手机。
我是否需要重新学习？	不需要，所有功能都与 CLI 保持一致，只是多了一层点击和拖拽。
安全吗？	所有可能修改文件、执行命令的工具默认关闭，用前必须手动开启。
看完能做什么？	十分钟内本地跑起来，之后用手机也能随时浏览项目、继续对话、提交 Git。

一、先弄清楚：Claude Code 与 Claude Code UI 的关系

Claude Code
安装后你会得到一个 claude 命令。它能读懂你的代码库，回答技术问题、生成补丁、运行测试——但只活在终端里。
Claude Code UI
用 Node.js + React 写的一套网页壳，把终端里的文字流搬到浏览器，额外附赠文件树、代码高亮、Git 面板、会话管理这些“现代感”功能。

两者通过本地 WebSocket 通信：

你的浏览器 <=> Node 中间层 <=> Claude CLI

你在网页里输入的每句话，其实被转发给真正的 claude 进程，再把返回结果渲染出来。
因此，UI 不会“偷偷”越权，所有权限边界与 CLI 完全一致。

二、安装之前的准备清单

检查项	最低要求	如何验证
Node.js	v20 及以上	`node -v`
Claude CLI	已安装并能运行	`claude --version`
Git	克隆仓库用	`git --version`

如果 claude 还没装好，先去官方文档走一遍流程，再回到这里继续。

三、三步跑起来：从克隆到第一个对话

“

以下命令直接复制即可，全部基于仓库真实脚本。

克隆仓库并进入目录

git clone https://github.com/siteboon/claudecodeui.git
cd claudecodeui

装依赖
```
npm install
```

准备环境变量

cp .env.example .env
# 用任意编辑器打开 .env，把端口或代理改成你喜欢的，保存即可

启动开发模式
```
npm run dev
```
终端看到 Server running on http://localhost:3001 就代表成功。
打开浏览器
- 电脑：直接访问 http://localhost:3001
- 手机：保证与电脑在同一局域网，用 http://<电脑IP>:3001 访问；若想长期用，可“添加到主屏幕”，系统会自动以 PWA 模式打开。

四、第一次打开的界面：快速导览

区域	作用	常用操作
左侧边栏	项目 & 会话列表	点击项目名称即可进入；右上角齿轮可调工具开关
中央主面板	聊天或文件	默认显示对话，也可切换到文件树、Git 面板
底部输入框	发送消息	支持换行、粘贴代码块、上传图片
右上角终端图标	一键回到 CLI	弹出内嵌终端，完全与系统终端一致

五、把“工具”打开：安全策略与最小可用原则

为了让你第一眼就能放心用，所有会写磁盘、跑脚本的工具全部默认关闭。
需要哪些，自己点亮：

点击左侧边栏齿轮图标 → Tools Settings
逐个开关对应功能（文件写盘、Git commit、Shell 命令等）
关闭弹窗即生效，设置保存在浏览器本地存储

建议顺序	理由
先开 File Explorer	只读浏览，不会改动代码
再开 Git Explorer	可以查看 diff，再决定要不要 stage
最后开 Shell	真正执行命令时才打开，用完即关

六、核心功能逐一拆解

1. 项目管理：让 AI 记住你所有仓库

自动发现：UI 会扫描 ~/.claude/projects/ 目录，把曾经跑过 claude 的项目列出来。
手动刷新：侧边栏顶部有刷新按钮，新增项目后点一下即可出现。
重命名 / 删除：右键项目卡片即可操作，不会删除实际文件夹，仅移除 UI 记录。

2. 聊天界面：把对话当文档一样管理

会话续接：每个项目下会列出历史会话，点击继续聊，上下文自动衔接。
搜索：顶部有按关键词过滤，支持正则。
导出：单条或整个会话可导出为 .md 或 .jsonl，方便存档或分享。

3. 文件树 & 编辑器：临时改两行，不必打开 IDE

树形浏览：左侧展开目录，右侧实时预览文件。
语法高亮：基于 CodeMirror，支持 100+ 语言。
保存即生效：修改后 Ctrl+S，文件立即写入磁盘，CLI 端也能立刻感知。

4. Git Explorer：可视化提交

状态总览：修改、新增、删除文件一目了然。
一键 stage / unstage：勾选文件即可。
写 commit 信息：输入框支持多行，写完点 Commit。
分支切换：下拉菜单列出所有本地分支，点一下就 checkout。

5. 会话管理：真正的跨设备续写

云端无依赖：所有数据以 JSONL 形式存在项目 .claude/ 子目录，直接拷走即可。
手机端同步：把项目放 GitHub，换设备 git pull 后刷新页面，历史会话自动出现。

七、移动端专属体验

场景	操作技巧
地铁里阅读代码	打开手机浏览器 → 添加到主屏幕 → 全屏 PWA 模式
随手改配置文件	进入 File Explorer → 长按文件 → Edit → 保存
审核 PR 时快速回复	切到聊天 → 引用文件 → 输入 `/review` → 发送

八、常见问题 FAQ（基于 GitHub issue 高频提问）

Q1：页面空白，提示 “No Claude projects found”
A：

先在任意项目目录跑一次 claude，CLI 会创建 ~/.claude/projects/ 记录。
检查该目录权限：ls -ld ~/.claude/projects，确保当前用户可读。
刷新页面或重启 npm run dev。

Q2：文件树加载很慢或直接报错
A：

项目根目录权限不足 → chmod -R u+rwX .
目录过大 → 在 .env 里设置 IGNORED_DIRS=node_modules,.git 排除大文件夹。
看终端日志，常见 EMFILE 错误可用 ulimit -n 65535 解决。

Q3：我点了 enable shell，但命令没反应？
A：

Shell 工具只是打通通道，仍需你在输入框里用 /shell <command> 格式发送。
若想完全图形化，可装额外插件，但官方 UI 目前不提供按钮式命令。

Q4：如何卸载？
A：

前端：直接删除克隆目录。
Claude CLI：保留，与 UI 解耦。
项目数据：全部在 .claude/ 里，手动删即可，无残留。

九、架构速读：为什么它这么快、这么轻

浏览器（React + Vite）
        ↑ WebSocket
Node.js Express 中间层
        ↑ spawn
Claude CLI 进程

前端用 Vite 冷启动 < 1 s，热更新 < 50 ms。
后端只负责转发和静态文件，无数据库，无缓存，极简部署。
通信用 JSON 格式，一条消息一个对象，方便后续做二次开发或日志分析。

十、如果你打算贡献代码

步骤	关键细节
Fork + Clone	与安装流程一致
分支命名	`feature/描述` 或 `fix/问题`
代码风格	自带 `eslint + prettier`，`npm run lint && npm run format` 一键修正
提交信息	参考 Conventional Commits，`feat:`、`fix:`、`docs:` 开头
PR 模板	截图 + 简要说明 + 是否通过测试

十一、小结：什么时候用 CLI，什么时候用 UI？

场景	推荐方式
日常开发主力机	CLI 更快，IDE 集成更顺手
给非技术同事演示	UI 直观，零学习成本
地铁、咖啡馆、床上	手机浏览器打开 UI，随时查看
需要多人同时查看会话	UI 可投屏，CLI 只能本地

十二、下一步可以做什么

把 UI 部署到团队内网，大家共用同一套项目列表。
利用 .env 里的 BASE_PATH，把 UI 挂在子路径 /claude，与现有开发环境并存。
写一个小脚本，把会话导出的 .md 自动同步到内部 Wiki，形成持续更新的技术文档。

“

希望这份指南能让你在十分钟内跑起 Claude Code UI，并在之后的每一天，都能用更顺手的方式与 AI 一起写代码。
若遇到新问题，直接在仓库提 issue，社区会一起帮你解答。