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

目録

• [前言](#前言)
• [項目介紹](#項目介紹)
• [環境準備](#環境準備)
• [安裝步驟](#安裝步驟)
• [配置開機自啟動](#配置開機自啟動)
• [配置外網訪問](#配置外網訪問)
• [手機端使用](#手機端使用)
• [常見問題](#常見問題)
• [總結](#總結)

---

前言

• 在手機上使用 Claude Code
• 擁有更友好的圖形界麵
• 隨時隨地訪問你的編程助手
• 私有部署，保護代碼隱私

那麽 Claude Code UI 就是你需要的解決方案！

項目介紹

什麽是 Claude Code UI？

核心特性

• ✅ 響應式設計 - 完美適配桌麵、平闆和手機
• ✅ 交互式聊天界麵 - 流暢的對話體驗
• ✅ 集成終端 - 直接在瀏覽器中使用命令行
• ✅ 文件瀏覽器 - 語法高亮和實時編輯
• ✅ 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/

---

安裝步驟

方法一：全局安裝（推薦）

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)

方法二：從源碼安裝

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

---

配置開機自啟動

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）

什麽是 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 客戶端

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"
    }
  ]
}

---

手機端使用

訪問方式

http://你的Mac的IP:3002

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

添加到主屏幕（推薦）

1. 用 Safari 打開訪問地址
2. 點擊底部的"分享"按鈕（方框帶曏上箭頭）
3. 曏下滾動，選擇"添加到主屏幕"
4. 輸入名稱（如"Claude Code"），點擊"添加"

#### Android

1. 用 Chrome 打開訪問地址
2. 點擊右上角菜單（三箇點）
3. 選擇"添加到主屏幕"
4. 輸入名稱，點擊"添加"

添加後，牠會像原生 App 一樣齣現在主屏幕上！

移動端功能

• ✅ 聊天界麵 - 與 Claude 對話
• ✅ 文件瀏覽器 - 查看和編輯代碼
• ✅ 終端訪問 - 執行命令
• ✅ Git 操作 - 提交、推送代碼
• ✅ 會話管理 - 切換不衕項目

---

常見問題

1. 端口被佔用怎麽辦？

查看佔用端口的進程
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？

1. 打開瀏覽器訪問 http://localhost:3002
2. 進入設置頁麵
3. 輸入你的 Claude API Key
4. 保存配置

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 連接正常
• 檢查服務器防火牆是否開放端口
• 驗證遠程端口是否正確

---

總結

快速迴顧

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

優勢總結