【教學】5 分鐘在 Cloud Mac 部署 CodeGraph MCP

大倉跑 codegraph init 時，筆電風扇常先響。更省事的做法：把 CodeGraph 與 MCP Server 部署在 Cloud Mac，只用 SSH 執行幾條命令；本地 Claude Code、Cursor 繼續寫碼，不必在本機安裝 CodeGraph、不必本地全量索引。

可複製的最短路徑：ssh root@zavcloud → brew install → codegraph init。若已讀 CodeGraph 與 AI 程式助理，本文只解決「放哪台機器、怎麼五分鐘上線」。

為什麼把 CodeGraph MCP 放在 Cloud Mac？

CodeGraph 在倉庫根生成 .codegraph/，首次 init -i 長時間占用 CPU 與 NVMe。放在 ZavCloud Cloud Mac 通常有這些好處：

• 與 xcodebuild、GitHub Actions Runner 同一台原生 macOS，圖譜版本與建置一致；
• 開發者只需 SSH，不必在 Windows / Linux 本機折騰 macOS 依賴；
• 常駐節點可夜間增量索引，白天本地 Agent 只讀圖譜。

開始前準備

• 已開通 Cloud Mac（控制台可見公網 IP 或 SSH 主機名）；
• 本機終端（Windows 可用 PowerShell / WSL）；
• 程式已在雲端 clone（或之後 git clone）；
• 可選：本機已裝 Claude Code 或 Cursor（用於步驟 4 驗證 MCP）。

步驟 1：SSH 登入 Cloud Mac

在控制台複製實例位址後，用 root（或面板使用者）登入。示例：

# Example: replace zavcloud with your instance IP or hostname
ssh root@zavcloud

# Key-based login (recommended)
ssh -i ~/.ssh/id_ed25519 root@203.0.113.10

首次登入輸入 yes 信任指紋。提示符應顯示雲端 macOS 主機名——後續安裝都在該機器，不是筆電。

步驟 2：brew install CodeGraph

ZavCloud Cloud Mac 為原生 macOS，通常已帶 Homebrew。用 brew 安裝 Node 與 CodeGraph CLI：

# Confirm Homebrew
brew --version

# Install Node if needed
brew install node

# Install CodeGraph CLI
npm install -g @colbymchenry/codegraph
codegraph --version

也可在同一 SSH 工作階段執行官方安裝器（效果相同，仍無需本地配置）：

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

步驟 3：codegraph init（建索引）

進入要交給 AI Agent 的倉庫根目錄，初始化並全量索引（大倉可加 -i）：

cd ~/workspace/your-monorepo
git pull

# Init + index (first run may take 10–40 min)
codegraph init -i

# Confirm database
codegraph status
ls -la .codegraph/

索引期間建議用 screen 或 tmux 防止 SSH 斷開。完成後 .codegraph/codegraph.db 留在 Cloud Mac——本地無需拷貝整庫。

步驟 4：部署 MCP Server（Claude Code / Cursor）

在 Cloud Mac 寫入 MCP 配置（stdio，命令 codegraph serve --mcp）：

codegraph install --target=claude,cursor --yes

# Foreground MCP (debug)
codegraph serve --mcp

本地無需重複 install。 兩種常見接法：

• 在 Cloud Mac 上跑 Claude Code / Cursor Remote：MCP 讀同一台機的 .codegraph，零額外配置；
• 本機 Agent + 雲端圖譜：以 ssh -L 或內網 IP 暴露 codegraph serve --mcp——仍不必在本機 codegraph init。

驗證：5 分鐘檢查清單

常見問題與實戰排錯

依真實工單頻率排序：每條给出「先確認什麼 → 再執行什麼 → 怎樣算修好」。預設已 SSH 登入 Cloud Mac，且倉庫已 clone 到例如 ~/workspace/your-repo。

SSH 連不上：ssh root@zavcloud 逾時或 Permission denied

現象: Connection timed out、Permission denied (publickey)，或信任指紋後仍失敗。

處理步驟:

1. 把 zavcloud 換成控制台公網 IP（如 ssh root@203.0.113.10）。主機名未解析時最常逾時。
2. 檢查本機金鑰權限：
   本機

   chmod 600 ~/.ssh/id_ed25519
   ssh -v -i ~/.ssh/id_ed25519 root@YOUR_IP

   看 -v 輸出是 Offering public key 還是 no mutual signature——後者多半是金鑰未綁定實例。
3. IP 可達但拒絕密碼：Cloud Mac 通常預設金鑰登入，在面板重置 SSH 金鑰，或先用 VNC 確認「遠端登入」已開啟。
4. 公司網路封 22 埠：改用手機熱點試一次；獨享實例的靜態 IPv4便於向維運登記白名單。

修好標準: 能穩定進入 shell，且 uname -a 顯示 Darwin（macOS）。

brew install 或 codegraph 提示 command not found

現象: brew: command not found，或 npm i -g 成功但 codegraph --version 找不到。

處理步驟:

1. 確認 Homebrew 路徑（Apple Silicon 常見）：
   Cloud Mac

   test -x /opt/homebrew/bin/brew && eval "$(/opt/homebrew/bin/brew shellenv)"
   brew --version

   仍無 brew 可改裝 Homebrew，或直接用下方 install.sh。
2. 全局 npm 二進位不在 PATH：
   Cloud Mac

   npm config get prefix
   export PATH="$(npm config get prefix)/bin:$PATH"
   which codegraph
   codegraph --version

   把 export PATH=... 寫入 ~/.zshrc，避免下次 SSH 又失效。
3. 仍失敗時在 Cloud Mac 一鍵安裝：
   備選

   curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
   exec $SHELL -l

修好標準: which codegraph 有路徑，codegraph --version 能印出版本。

codegraph init -i 跑很久不動，或 SSH 斷線後索引毀了

現象: 終端長時間無輸出；合蓋斷線後 codegraph status 顯示未索引或資料庫損壞。

處理步驟:

1. 以後一律在 tmux 內跑索引：
   Cloud Mac · 建議

   brew install tmux
   tmux new -s codegraph
   cd ~/workspace/your-repo && codegraph init -i
   # After reconnect:
   tmux attach -t codegraph

2. 檢查磁碟空間（.codegraph/ 可能數百 MB）：

   df -h .
   du -sh .codegraph 2>/dev/null

3. 懷疑庫損壞：在倉庫根備份後刪除 .codegraph/，再跑 codegraph init -i（勿在程序執行中刪除）。
4. Monorepo 可用 .codegraphignore 排除巨型目錄——排除過多會讓 impact 漏檔，需權衡。

修好標準: codegraph status 已索引檔案數 > 0，且 ls .codegraph/codegraph.db 存在。

Claude Code / Cursor 看不到 CodeGraph，Agent 仍只會 Grep

現象: MCP 列表沒有 codegraph；改介面仍不呼叫 codegraph_impact。

處理步驟:

1. 在Cloud Mac（init 同一使用者）重寫 MCP：

   codegraph install --target=claude,cursor --yes
   grep -A6 codegraph ~/.claude.json 2>/dev/null || cat ~/.claude.json

   應看到 "command": "codegraph" 與 "args": ["serve", "--mcp"]。
2. 完全退出 Claude Code / Cursor 再開（只關視窗不算）。
3. 本機 Agent + 雲端圖譜：本機 MCP 需能執行到雲端 codegraph：
   本機 ~/.claude.json 片段

   {
     "mcpServers": {
       "codegraph": {
         "type": "stdio",
         "command": "ssh",
         "args": ["root@YOUR_IP", "codegraph", "serve", "--mcp"]
       }
     }
   }

   先在本機跑 ssh root@YOUR_IP codegraph serve --mcp 確認不報錯。
4. 若工具需批准：允許 mcp__codegraph__*，或在 CLAUDE.md 規定改公共 API 前必須 codegraph_impact。

修好標準: 新對話能列出 codegraph 工具或對某符號做 impact 並回傳檔案路徑，而非空或純 Grep。

codegraph impact 或 MCP impact 回傳空列表

現象: 明明有呼叫方，codegraph impact "Foo.bar" 卻 0 條；Agent 以為不用改其他檔。

處理步驟:

1. 確認在已 init 的倉庫根：

   pwd
   codegraph status

2. 符號名與語言一致：Swift 用 TypeName.method；TS export 名可能與檔名不同。可試 codegraph_callers 或搜尋拼寫。
3. 索引過期：main 大改後在 Cloud Mac git pull && codegraph init -i，否則圖譜仍是舊呼叫關係。
4. Generated / 第三方目錄若被 .gitignore 整包排除，可能漏掉真實呼叫方。

修好標準: 對已知有引用者的符號，impact 至少回 1 條路徑；結果應 ≥ 手動 Grep（圖譜含間接呼叫）。

一台 Cloud Mac 多倉庫，或 Claude 開錯目錄

現象: 在 A 倉 init，卻在 B 開 Agent；~/workspace 下只有一個專案有 .codegraph/。

處理步驟:

• 每個倉庫各自在根目錄 codegraph init -i，不要共用父目錄。
• 開 Agent 前 cd 到對應根，或 Remote-SSH 直接開該資料夾。
• 磁碟緊張：只給主 monorepo 全量索引；大庫可夜間 cron + tmux 跑 git pull && codegraph init -i。

修好標準: Agent 工作區根目錄與含 .codegraph/codegraph.db 的目錄一致。

想在筆電查圖譜，但堅持不在本機跑 init

現象: 希望本機 MCP 查詢，但不想在本機跑半小時索引。

處理步驟:

1. 索引仍在 Cloud Mac；只同步 .codegraph/：
   本機執行

   rsync -avz --progress root@YOUR_IP:~/workspace/your-repo/.codegraph/ ./your-repo/.codegraph/

2. 在本機倉庫根 codegraph status 驗證；本機仍需 codegraph install 配 MCP，不必再跑 init -i。

修好標準: 本機 codegraph status 正常且 MCP 能查同步後的 DB。

團隊常每晚從同一台 Cloud Mac rsync「黃金索引」給成員。

索引時 Cloud Mac 很卡，與 Xcode 建置搶資源

現象: CPU 吃滿；建置與索引在同一台機器上互搶。

處理步驟:

• 在 tmux 內跑 caffeinate -dims，避免睡眠中斷索引。
• 把 codegraph init -i 排在夜間或 CI 空檔，與 xcodebuild 錯峰；見 ../openclaw-yun-duan-zidonghua/openclaw-yun-duan-zidonghua.html Runner 筆記。
• codegraph 長時間占滿 CPU 屬正常；若模擬器與索引同時跑，可另租一台 Cloud Mac 專做索引節點。

修好標準: 索引完成且 DB 未損壞；白天開發/建置仍可接受。

和「在本機裝 CodeGraph」相比，我到底省了什麼？

沒有閹割版雲端圖譜——差別在算力放哪。你省掉本機 Node/Homebrew、全量解析時的風扇噪音，以及「合蓋索引暫停」。仍需要 SSH、雲端倉庫路徑、以及 Agent 側正確接 MCP。概念見 CodeGraph 與 AI 程式助理；安裝細節見 大倉 CodeGraph 實戰指南（2026）。

• 概念— Claude Code 漏改與 CodeGraph
• CI 同機— 雲端 Mac Runner
• 開通實例— Cloud Mac 方案