摘要：> 本文详细介绍如何在 macOS 上安装 Claude Code UI，配置开机自启动，并通过 FRP 实现外网访问，让你可以在手机上随时随地使用 AI 编程助手。

在 macOS 上部署 Claude Code UI：完整安装指南

> 本文详细介绍如何在 macOS 上安装 Claude Code UI，配置开机自启动，并通过 FRP 实现外网访问，让你可以在手机上随时随地使用 AI 编程助手。

前言

Claude Code 是 Anthropic 推出的强大 AI 编程助手，但官方只提供了命令行界面（CLI）。如果你想：

在手机上使用 Claude Code
拥有更友好的图形界面
随时随地访问你的编程助手
私有部署，保护代码隐私

那么 Claude Code UI 就是你需要的解决方案！

项目介绍

什么是 Claude Code UI？

Claude Code UI（siteboon/claudecodeui）是一个开源的 Web 界面项目，为 Claude Code、Cursor CLI 和 Codex 提供了完整的图形化界面。 GitHub 地址: https://github.com/siteboon/claudecodeui

核心特性

✅ 响应式设计 - 完美适配桌面、平板和手机
✅ 交互式聊天界面 - 流畅的对话体验
✅ 集成终端 - 直接在浏览器中使用命令行
✅ 文件浏览器 - 语法高亮和实时编辑
✅ Git 集成 - 查看、暂存和提交更改
✅ 会话管理 - 恢复对话，管理多个会话
✅ 移动端优化 - 触摸导航，PWA 支持

项目数据

GitHub Stars: 5.3k+
活跃度: 高（2026年初仍在更新）
开源协议: MIT
支持平台: macOS, Linux, Windows

---

环境准备

系统要求

macOS 10.15 或更高版本
Node.js v20 或更高版本
npm 或 yarn 包管理器
Git

检查环境

打开终端，运行以下命令检查环境：

检查 Node.js 版本
node --version
应该显示 v20.x.x 或更高
检查 npm 版本
npm --version
检查 Git 版本
git --version

如果没有安装 Node.js，可以通过以下方式安装：

使用 Homebrew 安装
brew install node
或者从官网下载安装包
https://nodejs.org/

---

安装步骤

方法一：全局安装（推荐）

这是最简单的安装方式，适合日常使用。 #### 1. 安装 Claude Code UI

npm install -g @siteboon/claude-code-ui

安装过程需要几分钟，会下载约 456 个依赖包。

#### 2. 验证安装

查看安装路径
which claude-code-ui
查看版本
claude-code-ui --version

#### 3. 查看配置状态

cloudcli status

你会看到类似以下输出：

Claude Code UI - Status
════════════════════════════════════════════════════════════
[INFO] Version: 1.13.6
[INFO] Installation Directory: /opt/homebrew/lib/node_modules/@siteboon/claude-code-ui
[INFO] Database Location: server/database/auth.db
[INFO] Configuration:
       PORT: 3002 (default)
       CONTEXT_WINDOW: 160000 (default)

方法二：从源码安装

如果你需要自定义或开发，可以从源码安装。 #### 1. 克隆项目

cd ~/soft  # 或你喜欢的目录
git clone https://github.com/siteboon/claudecodeui.git
cd claudecodeui

#### 2. 安装依赖

npm install

#### 3. 构建生产版本

npm run build

构建完成后，会在 dist 目录生成静态文件。

#### 4. 创建环境配置

cat > .env << 'EOF'
服务器端口
PORT=3002
前端端口（仅开发模式使用）
VITE_PORT=5173
Claude Code 上下文窗口大小
CONTEXT_WINDOW=160000
VITE_CONTEXT_WINDOW=160000
EOF

---

配置开机自启动

为了让 Claude Code UI 在 macOS 启动时自动运行，我们使用 LaunchAgent。

1. 创建日志目录

mkdir -p ~/soft/server-ai/claudecodeui/logs

2. 创建 LaunchAgent 配置文件

cat > ~/Library/LaunchAgents/com.claudecodeui.plist << 'EOF'




    Label
    com.claudecodeui
    ProgramArguments
    
        /opt/homebrew/bin/node
        /Users/你的用户名/soft/server-ai/claudecodeui/server/index.js
    
    WorkingDirectory
    /Users/你的用户名/soft/server-ai/claudecodeui
    EnvironmentVariables
    
        PORT
        3002
        NODE_ENV
        production
        PATH
        /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
    
    RunAtLoad
    
    
                                    KeepAlive
    
    
                                    StandardOutPath
    /Users/你的用户名/soft/server-ai/claudecodeui/logs/stdout.log
    StandardErrorPath
    /Users/你的用户名/soft/server-ai/claudecodeui/logs/stderr.log


EOF

注意：请将 你的用户名 替换为你的实际用户名。

3. 加载服务

launchctl load ~/Library/LaunchAgents/com.claudecodeui.plist

4. 验证服务状态

查看服务是否运行
launchctl list | grep claudecodeui
检查端口是否监听
lsof -i :3002
测试访问
curl -I http://localhost:3002

5. 管理命令

停止服务
launchctl unload ~/Library/LaunchAgents/com.claudecodeui.plist
启动服务
launchctl load ~/Library/LaunchAgents/com.claudecodeui.plist
查看日志
tail -f ~/soft/server-ai/claudecodeui/logs/stdout.log

---

配置外网访问（FRP）

如果你想从外网访问 Claude Code UI，可以使用 FRP（Fast Reverse Proxy）进行内网穿透。

什么是 FRP？

FRP 是一个高性能的反向代理应用，可以帮助你将内网服务暴露到公网。

前提条件

一台有公网 IP 的服务器（运行 frps）
本地 Mac 运行 frpc 客户端

1. 安装 FRP 客户端

下载 FRP（以 0.52.0 版本为例）
cd ~/soft
mkdir -p frp && cd frp
wget https://github.com/fatedier/frp/releases/download/v0.52.0/frp_0.52.0_darwin_arm64.tar.gz
解压
tar -xzf frp_0.52.0_darwin_arm64.tar.gz
mv frp_0.52.0_darwin_arm64 frp
cd frp

2. 配置 FRP 客户端

创建或编辑 frpc.toml 配置文件：

cat > frpc.toml << 'EOF'
user = "你的用户名"
serverAddr = "你的服务器地址"
serverPort = 7000
auth.token = "你的认证token"
Web 管理界面（可选）
webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "你的密码"
Claude Code UI 端口映射
[[proxies]]
name = "claude-code-ui"
type = "tcp"
localPort = 3002
remotePort = 49946
EOF

3. 启动 FRP 客户端

后台启动
nohup ./frpc -c frpc.toml > frpc.log 2>&1 &
查看日志
tail -f frpc.log

4. 验证连接状态

检查 frpc 进程
ps aux | grep frpc
通过管理界面查看状态
curl -s http://admin:你的密码@127.0.0.1:7400/api/status | jq

你应该看到类似输出：

{
  "tcp": [
    {
      "name": "claude-code-ui",
      "type": "tcp",
      "status": "running",
      "local_addr": "127.0.0.1:3002",
      "remote_addr": "你的服务器:49946"
    }
  ]
}

---

手机端使用

Claude Code UI 本身就是为移动端优化的 Web 应用，无需单独的 App。

访问方式

本地访问（同一 WiFi）：

http://你的Mac的IP:3002

外网访问（通过 FRP）：

http://你的服务器地址:49946

添加到主屏幕（推荐）

#### iOS (iPhone/iPad)

用 Safari 打开访问地址
点击底部的"分享"按钮（方框带向上箭头）
向下滚动，选择"添加到主屏幕"
输入名称（如"Claude Code"），点击"添加"

#### Android

用 Chrome 打开访问地址
点击右上角菜单（三个点）
选择"添加到主屏幕"
输入名称，点击"添加"

添加后，它会像原生 App 一样出现在主屏幕上！

移动端功能

在手机上可以使用的功能：

✅ 聊天界面 - 与 Claude 对话
✅ 文件浏览器 - 查看和编辑代码
✅ 终端访问 - 执行命令
✅ Git 操作 - 提交、推送代码
✅ 会话管理 - 切换不同项目

---

常见问题

1. 端口被占用怎么办？

如果 3002 端口被占用，可以更改端口：

查看占用端口的进程
lsof -i :3002
修改环境变量
export PORT=3003
或修改 .env 文件
echo "PORT=3003" >> .env

2. 服务启动失败

检查日志文件：

查看错误日志
tail -50 ~/soft/server-ai/claudecodeui/logs/stderr.log
查看标准输出
tail -50 ~/soft/server-ai/claudecodeui/logs/stdout.log

常见原因：

Node.js 版本过低（需要 v20+）
端口被占用
权限问题

3. 如何配置 Claude API Key？

首次访问时，需要在界面中配置 API Key：

打开浏览器访问 http://localhost:3002
进入设置页面
输入你的 Claude API Key
保存配置

4. FRP 连接失败

检查以下几点：

1. 检查 frpc 是否运行
ps aux | grep frpc
2. 查看 frpc 日志
tail -50 ~/soft/frp/frp/frpc.log
3. 测试服务器连接
ping 你的服务器地址
4. 检查防火墙规则

5. 手机无法访问

局域网访问问题：

确保手机和 Mac 在同一 WiFi
检查 Mac 防火墙设置
使用 ifconfig 确认 Mac 的 IP 地址

外网访问问题：

确认 FRP 连接正常
检查服务器防火墙是否开放端口
验证远程端口是否正确

---

总结

通过本教程，你已经完成了： ✅ 在 macOS 上安装 Claude Code UI ✅ 配置开机自启动服务 ✅ 通过 FRP 实现外网访问 ✅ 在手机上使用 AI 编程助手

快速回顾

本地访问：

http://localhost:3002

外网访问：

http://你的服务器:49946

管理命令：

查看服务状态
launchctl list | grep claudecodeui
重启服务
launchctl unload ~/Library/LaunchAgents/com.claudecodeui.plist
launchctl load ~/Library/LaunchAgents/com.claudecodeui.plist
查看日志
tail -f ~/soft/server-ai/claudecodeui/logs/stdout.log

优势总结

相比其他方案，Claude Code UI 的优势：