# Cloud 工作區與代理

Cloud 工作區的用法和本機 cmux 工作區相同，只是其中的終端機在雲端機器上執行。本頁說明持久終端機、執行代理、通知，以及每台機器上預先安裝的工具。

## 持久終端機

終端機位於機器的常駐程式中，而不在你的 Mac 上。關閉窗格、結束 cmux、Wi-Fi 中斷或闔上筆電時，終端機都會繼續執行。從任何已登入的 Mac 重新開啟機器，終端機的輸出和執行中的程序都還在。

如果連線中斷，窗格會顯示 Cloud session disconnected 和 Reconnect 按鈕，同時 cmux 會自動重試。

如果機器的常駐程式重新啟動，cmux 會還原工作區版面配置，但先前執行中的程序不會在重新啟動後保留。

關閉工作區時，其終端機會以分離狀態繼續執行。移除工作區則會停止其終端機。

## 執行程式設計代理

每台機器都已預先安裝 Claude Code、Codex、OpenCode 和 Pi。開啟 Cloud 工作區，像在本機一樣啟動代理即可。代理 hook 已設定完成，因此代理狀態和通知會傳回你的 Mac。

cmux vm agent 會從你的 Mac 在機器上啟動代理。提供提示詞時，會使用代理的單次執行模式。加上 --sync 可先上傳目前的目錄，加上 --wait 可等待結果。

```
cmux vm agent --agent claude --machine brave-otter -- "add tests for the parser"
cmux vm agent --agent codex --machine brave-otter --sync --wait -- "fix the build"
cmux vm agent --agent opencode --new --size 16g -- "profile the importer"
```

cmux vm prompt 會為你的本機代理安裝 cmux Cloud 技能，並輸出一段教它使用 Cloud 機器的提示詞。

```
cmux vm prompt --open claude
```

## 執行指令

cmux vm run 會在機器上執行指令並傳回其結束代碼。第一次從某個目錄執行時會選擇一台機器，並為該目錄記住它 14 天。加上 --sync 可先上傳目錄，加上 --pull 可下載結果。

```
cmux vm run -- npm test
cmux vm run --sync --pull dist -- npm run build
cmux vm route --json
```

cmux vm exec 會在沒有終端機的情況下執行簡短指令，適合快速檢查。預設逾時為 30 秒，最長 5 分鐘。長時間的工作請使用 cmux vm run、cmux vm agent 或工作區終端機。

```
cmux vm exec brave-otter -- uname -a
cmux vm exec --timeout 120 brave-otter -- docker ps
```

## 啟動開發伺服器

cmux vm dev 會上傳專案，找出啟動方式，並在包含伺服器和瀏覽器的工作區中開啟它。它能偵測 package.json 專案、Cargo、Go、Makefile 的 dev 目標、Django、uv、pyproject、requirements.txt 以及靜態 index.html 網站。使用 --dry-run 可先查看執行計畫。

```
cmux vm dev brave-otter --dry-run
cmux vm dev brave-otter . --port 3000
```

## 通知

在機器內執行 cmux notify，會在你的 Mac 上為該終端機顯示通知。代理 hook 會在代理完成、需要核准、提出問題或失敗時傳送通知。標題最多 128 位元組，內文最多 1 KB，短時間內大量的通知會受到速率限制。

```
# Inside a Cloud machine
cmux notify --title "Build" --body "Tests passed"
```

## 貼上圖片

在 Cloud 終端機中，當剪貼簿中有圖片時按 ⌘V。cmux 會將圖片上傳到機器並貼上遠端路徑，讓 Claude Code 和 Codex 能讀取它。支援 PNG、JPEG、GIF 和 WebP，每張最大 20 MB，一次最多 8 張。

## 透過 CLI 管理版面配置和終端機

cmux vm workspace 可在機器上建立、開啟、重新命名、關閉和移除工作區。cmux vm terminal 可傳送文字、讀取輸出，以及等待特定文字出現或等待結束。cmux vm tree 會顯示機器的工作區和終端機。cmux vm layout export 和 apply 使用與 cmux new-workspace --layout 相同的 JSON。

```
cmux vm tree brave-otter
cmux vm workspace new brave-otter --name review
cmux vm terminal send brave-otter term_2f9c "npm run dev" --keys enter
cmux vm terminal wait brave-otter term_2f9c --pattern "ready" --timeout 60
cmux vm terminal read brave-otter term_2f9c
cmux vm layout export brave-otter review > layout.json
cmux vm layout apply brave-otter layout.json --open
```

## 預先安裝的內容

機器執行 Ubuntu 24.04。你以使用者 cmux 的身分工作，可免密碼使用 sudo，而不是以 root 身分工作。Docker 會在開機時啟動。

-   語言和工具：Node.js LTS、Bun、Python 3.12、uv、Docker、git、GitHub CLI、ripgrep、fd、fzf、jq、tmux、sqlite3、建置工具、vim、nano 和 rsync。
-   瀏覽器和桌面：Chrome、agent-browser、VNC 桌面和 Ghostty。
-   代理：Claude Code、Codex、OpenCode 和 Pi。它們固定在經過測試的版本，並隨機器映像檔更新而更新。

如果剛建立機器後找不到代理指令，表示初始設定仍在進行中。初始設定記錄位於 /tmp/cmux/provision.log。

## 模型存取

機器上的代理不需要在機器上存放金鑰，即可使用 cmux 的模型路由。真正的憑證是在機器外部加入，因此 VM 中不會儲存任何帳號權杖。你也可以在機器內登入代理，或使用 cmux ai-accounts upload 為團隊上傳帳號。

```
cmux ai-accounts list
cmux ai-accounts upload claude
cmux coderouter status
```

[CodeRouter 文件：支援的帳號、共用與用量](https://cmux.com/zh-TW/docs/coderouter)

## 機器內的 cmux CLI

在機器內，cmux 指令會控制該機器的工作階段。它支援 tree、new-workspace、new-split、send、send-key、read-screen、terminal、layout、env、notify、open-url 和 self。cmux self 會顯示擁有者、目前的機器以及你的其他機器。cmux vm verb peer 可在機器內控制你的其他機器。

```
# Inside a Cloud machine
cmux tree
cmux new-split right
cmux self peers
cmux vm exec calm-heron -- git status
```

登入、上傳 AI 帳號，以及 new、delete、checkpoint、fork、resize、pause、domains、open 和 vpn 等機器生命週期指令只能在你的 Mac 上執行。

## iPhone

cmux iOS 應用程式不管理 Cloud 機器。正在啟動的機器會顯示為預留位置卡片。

Canonical: https://cmux.com/zh-TW/docs/cloud/workspaces

Documentation index: https://cmux.com/llms.txt