CloudCLI(Claude Code UI)教程:给命令行 AI 编程工具装上 Web 与移动端界面

Claude Code、Codex 这类命令行 AI 编程工具能力很强,但使用形态也被终端框住了:长任务跑着,人就得守在电脑前;出门在外想瞄一眼任务进度、回一句提示词,手机上完全没办法;会话开多了,哪条在等确认、哪条已经跑完,翻终端窗口翻到眼花。给这类 CLI 套一个像样的图形界面,是很多重度用户的共同诉求。

CloudCLI(仓库名 siteboon/claudecodeui,更广为人知的名字是 Claude Code UI)正是为此而生的开源项目:它给 Claude Code、Cursor CLI 与 Codex(仓库简介中亦提到 OpenCode)提供统一的 Web 界面,本机或远程服务器上启动一个服务,就能在桌面浏览器、平板和手机上管理这些 Agent 的项目与会话。它在 GitHub 上已有约 1.47 万 Star,采用 AGPL-3.0 协议开源。本文介绍它的功能、三种运行方式、日常使用流程,以及上线前必须搞清楚的安全配置。

一、功能总览

  • 响应式界面:同一套 UI 适配桌面、平板与手机,移动端有专门的触控导航设计,不是在手机上硬塞桌面页面
  • 交互式聊天界面:在网页里直接与 Agent 对话、发指令、看流式回复,不必回到终端
  • 内置 Shell 终端:需要敲原生命令时,界面里就有终端可以直接操作 Agent 的 CLI
  • 文件浏览器:交互式文件树,带语法高亮,支持在线查看与实时编辑文件
  • Git 管理:查看改动、暂存(stage)、提交(commit),还能切换分支,Agent 改完代码顺手就在界面里检查与提交
  • 浏览器使用(Browser Use):可打开浏览器会话做网页调研、测试与 Agent 驱动的浏览器任务
  • 会话管理:自动发现本机已有的全部会话(读取 ~/.claude 目录),可恢复对话、管理多会话、查看历史
  • 插件系统:可扩展自定义标签页与后端服务,官方列出的插件包括项目统计、Web 终端(多标签 xterm.js)、定时任务调度、Token 成本计算器、会话管理、GitHub Issues 看板等,也可从 Git 仓库直接安装自制插件
  • 模型兼容:支持 Claude 与 GPT 模型家族,具体可用模型列表在运行时通过接口获取;还可选集成 TaskMaster AI 做 AI 任务规划与 PRD 解析
  • REST API:自托管与云端版本都提供 API,可与自己的自动化流程对接

一个关键设计是:自托管模式下,CloudCLI 读写的就是 Claude Code 原生使用的同一份 ~/.claude 配置——你在界面里增删的 MCP 服务器、调整的工具权限,会直接写入 Claude Code 的配置并立即生效,反之亦然。它不是另起一套平行系统,而是给原有 CLI 换了个操作台。

二、安装与启动:三种方式

方式一:npm 自托管(开源主力用法)

前提是本机装有 Node.js v22 或更高版本,且已经在用 Claude Code 等目标 CLI。零安装试跑与全局安装二选一:

# 免安装直接试跑
npx @cloudcli-ai/cloudcli

# 或全局安装后长期使用
npm install -g @cloudcli-ai/cloudcli
cloudcli

启动后在浏览器打开 http://localhost:3001 即可,本机已有的项目和会话会被自动发现,不需要任何导入步骤。配套的命令行还有几个子命令值得记住:cloudcli start 启动服务、cloudcli status 查看当前配置与数据文件位置、cloudcli version 查看版本。官方文档还介绍了用 PM2 守护进程、部署到远程服务器等进阶跑法,长期自用的建议照此做成常驻服务。

方式二:Docker 沙盒(实验性)

想让 Agent 在隔离环境里跑代码,可以用官方的 Docker 沙盒模式,基于 microVM 提供虚拟机级别的隔离,默认启动 Claude Code,同时支持 Codex。该方式需要预先安装 Docker 的 sbx CLI:

# 在沙盒中为指定项目启动 CloudCLI
npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project

方式三:官方云 CloudCLI Cloud 与桌面伴侣 App

不想自己维护服务的,可以用官方托管的 CloudCLI Cloud:零配置开箱,浏览器、移动端、REST API 都能访问,合上笔记本 Agent 也能继续在云端运行,价格为每月 7 欧元起(AI 订阅仍需自备)。另外官方还提供免费的桌面伴侣 App(macOS、Windows、Linux 的 .deb 包,从 GitHub Releases 下载),装在菜单栏/托盘里,用来快速打开云端环境、在本地与远程工作区之间切换,并复制移动端访问链接;选其中的 Local CloudCLI 还能直接接管你本机正在运行的服务,没启动时它会帮你拉起来。

三种方式怎么选:主力机上日常用选 npm 自托管;让 Agent 跑不可信代码选 Docker 沙盒;团队协作或不想让本机保持开机选官方云(只有云端版支持团队共享)。

三、使用教程

先给一条五分钟上手路径,后文再逐项展开:① 用 npx @cloudcli-ai/cloudcli 启动服务;② 浏览器打开 http://localhost:3001,确认左侧已自动列出你原有的项目与会话(没有的话先检查目标 CLI 是否装好、~/.claude 里是否有历史会话);③ 点侧边栏齿轮图标进工具设置,按需开启第一批工具(见第四节,默认全关,不开则 Agent 只能聊天不能动手);④ 选一个项目新建会话,或点开一条旧会话恢复上下文;⑤ 在聊天框发出第一个任务,随后在文件与 Git 面板验收成果。五步走通,日常用法就掌握了大半。

1. 连接与恢复会话

打开界面后,左侧会列出自动发现的项目与历史会话。点进任意一条即可恢复上下文继续对话——包括那些你早先在纯终端里开的会话。顶部可以切换当前使用的 CLI(Agent),在 Claude Code、Cursor CLI、Codex 之间按项目选用。新建会话时选好项目目录即可开聊,多个会话可并行挂着,哪个在等待你确认、哪个已完成,在会话列表里一目了然。

2. 在界面里完成一次完整改码流程

典型流程是:在聊天区给出任务 → Agent 执行过程中涉及工具调用时会按你的权限设置请求确认 → 改完后切到文件浏览器,逐个文件检查改动(语法高亮+在线编辑,发现小问题可直接手改) → 打开 Git 面板查看全部变更,确认无误后暂存、填写说明并提交,需要时还能直接切换分支。整个过程不用离开浏览器,这正是它比「远程往终端发消息」类方案(如 Claude Code 官方 Remote Control 只能给单个已运行会话发消息,且终端必须开着、无网络约 10 分钟就超时)强的地方:CloudCLI 是全功能操作台,且管的是你的全部会话。

3. 手机上管理任务

自托管场景下,让手机与运行服务的机器处在同一网络(或用你自己的组网/VPN 方案),在手机浏览器打开 [机器IP]:3001 即可,界面会自动切到移动布局。常见用法是:出门前在电脑上给 Agent 派一个长任务,路上用手机看进度、批准工具调用、追加一句提示词;任务跑完回到电脑前直接验收。注意自托管版没有团队共享与推送体系,定位就是个人远程操作台。

4. 插件扩展

在 设置 → Plugins 中可以从 Git 仓库直接安装插件,给界面加新标签页。官方插件里比较实用的有:Web Terminal(多标签完整终端)、CloudCLI Scheduler(按工作区定时执行提示词)、Token Cost Calculator(按模型价格算 API 成本)、Sessions(查看与结束活跃会话)。从私有仓库装插件前,要先给运行服务的系统用户配好 Git 凭据(HTTPS 走 credential helper 或 gh auth login,SSH 走无口令密钥或 ssh-agent),因为服务端安装时无法交互输入密码。

四、配置与安全注意事项

1. 工具默认全部禁用,需手动开启

这是 CloudCLI 最重要的安全设计:Claude Code 的所有工具默认处于禁用状态,防止潜在有害操作被自动执行。首次使用要打开侧边栏的齿轮图标进入工具设置,按需逐个开启,建议从基础工具开始、用多少开多少,之后随时可再调整,设置保存在本地。

2. 环境变量与端口

服务通过 .env 文件配置(运行 cloudcli status 可确认该文件应放的位置),仓库 .env.example 中实际生效的变量包括:

# 后端服务端口(Express API + WebSocket),前端页面也由此访问
SERVER_PORT=3001
# 前端开发端口(源码开发时使用)
VITE_PORT=5173
# 绑定地址:默认 0.0.0.0 监听全部网卡;只本机用建议改成 127.0.0.1
HOST=0.0.0.0
# Claude CLI 不在默认路径时指定
# CLAUDE_CLI_PATH=claude
# 认证数据库位置(存用户凭据、API Key 与令牌),可自定义
# DATABASE_PATH=/path/to/your/custom/auth.db
# 上下文窗口大小(兜底值,会话会以 SDK 报告的模型窗口为准)
CONTEXT_WINDOW=160000

3. 网络暴露面要当回事

默认 HOST=0.0.0.0 意味着同一局域网内任何设备都能打开登录页——在家里图方便没问题,但不要把 3001 端口直接映射到公网裸奔:这个界面背后是能执行命令、改文件、操作 Git 的 Agent。远程访问优先走 VPN/组网工具或带认证的反向代理;只在本机用就把 HOST 改为 127.0.0.1。另外认证数据库里存着凭据与令牌,注意其文件权限与备份安全。

4. 其他须知

  • AI 订阅自备:CloudCLI 只提供环境与界面,不提供 AI 本身,Claude、Cursor、Codex 的订阅或 API 额度需要你自己有
  • 许可证为 AGPL-3.0:个人使用、修改、分发都没问题;但若修改后作为网络服务对外提供,按 AGPL 条款须向服务使用者公开修改后的源码,商用集成前先评估
  • 配置双向同步:自托管版在界面里改 MCP、权限会直接写回 ~/.claude 并对终端里的 Claude Code 生效,团队共用一台机器时注意别互相覆盖配置

五、适用人群与小结

CloudCLI 最适合三类人:同时开多个 Agent 会话、被终端窗口管理折磨的 CLI 重度用户;经常离开工位又想盯长任务进度的移动办公者;以及想给团队或自己搭一个「浏览器里用 Claude Code」入口的尝鲜派。它的价值不在替代 CLI,而在补齐 CLI 缺的那块图形操作台:会话全景、文件与 Git 的可视化、以及随时随地掏手机接管任务的能力。安装只要一条 npx 命令,已有会话自动发现,值不值得常驻,跑一个真实任务试十分钟就有答案——只是试之前,记得先把工具权限和 HOST 绑定这两件事按第四节检查一遍。

发表回复

后才能评论