cc_server CLI

每一個行程旗標都可以用 CLI 旗標或環境變數提供；旗標勝過環境變數，再勝過預設值。第三方憑證是例外——見下文。

未知旗標會被靜默忽略

參數剖析器是手寫的，會略過任何它不認識的東西，因此打錯字（--tls-key-file、--bindany）不會產生錯誤——伺服器只會以預設值啟動。當某個旗標似乎沒有作用時，請檢查啟動記錄行。

核心

旗標	環境變數	預設值	含義
--data-dir	CC_SERVER_DATA_DIR	作業系統的每位使用者應用程式資料目錄（見下文）	資料庫、密鑰、模型與快取媒體
--port	CC_SERVER_PORT	9030	TCP 連接埠（0 = 臨時）
--bind	CC_SERVER_BIND	loopback	loopback，或用 any/all/0.0.0.0 表示所有網絡介面（需要 TLS 或 --insecure）
--repo-roots	CC_SERVER_REPO_ROOTS	伺服器使用者的家目錄	用戶端註冊程式庫時可瀏覽的基礎目錄（以逗號分隔）。瀏覽至某個根目錄之上會被拒絕
--log-level	CC_SERVER_LOG_LEVEL	warning	debug、info、warning 或 error。啟動與就緒的記錄行一律會印出
--server-name	CC_SERVER_NAME	機器主機名稱	顯示於選擇器、探索與配對介面上的名稱

可觸達性與 TLS

旗標	環境變數	預設值	含義
--tls-cert	CC_SERVER_TLS_CERT	未設定	PEM 憑證鏈。與金鑰一同設定時，會在行程內提供 wss://
--tls-key	CC_SERVER_TLS_KEY	未設定	與憑證配對的 PEM 私鑰
--insecure	CC_SERVER_INSECURE	關閉	允許非回送的明文繫結。僅限在可信網絡上位於終止 TLS 的代理之後；已設定 TLS 時會被忽略
--public-url	CC_SERVER_PUBLIC_URL	由繫結推導	這部伺服器向已配對用戶端公佈的 RPC URL。在代理、NAT 或通道後方時，請明確設定它——預設值只是對本機繫結的猜測
--allowed-origins	CC_SERVER_ALLOWED_ORIGINS	https://app.usectrl.dev	允許跨來源撥打 /rpc 的瀏覽器來源（以逗號分隔）。回送與原生用戶端一律獲准
--web-client-url	CC_SERVER_WEB_CLIENT_URL	未設定	單一登入回呼會折返回去的受託管網頁用戶端來源
--signaling-url	CC_SERVER_SIGNALING_URL	wss://signaling.usectrl.dev	這部伺服器加入的中繼中介，讓手機在沒有直接路徑時也能觸達它
--mdns	CC_SERVER_MDNS	auto	LAN 公告：auto（只在繫結超出回送時）、on、off。探索只公佈存在——加入仍須配對
--tunnel	CC_SERVER_TUNNEL	off	受管理的通道供應商：off、cloudflared、ngrok、tailscale。公開曝光需自行開啟
--tunnel-binary	CC_SERVER_TUNNEL_BINARY	從 PATH 解析	明確的通道二進位檔路徑
--tunnel-sha256	CC_SERVER_TUNNEL_SHA256	未設定	該二進位檔的預期 SHA-256，每次啟動前都會驗證
--tunnel-args	CC_SERVER_TUNNEL_ARGS	空	通道叫用時額外的引數（以逗號分隔）

索引與第三方憑證

旗標	環境變數	預設值	含義
--sandbox	CC_SERVER_SANDBOX	on	當主機提供作業系統原生沙箱時，代理執行是否會被包裹其中。這是退出機制，而不是啟用機制——見下文
--code-index	CC_SERVER_CODE_INDEX	on	背景程式碼圖索引的現場終止開關。off 會在不重建的情況下乾淨啟動
--code-index-defer	CC_SERVER_CODE_INDEX_DEFER	15	就緒橫幅之後，延後第一次索引掃描的秒數（限制於 0–300）
--tool-deferral	CC_SERVER_TOOL_DEFERRAL	on	執行框架的執行是否只送出一個小的常駐工具集加一個名稱索引，其餘在首次使用時載入。見下文
--credential-gate	CC_SERVER_CREDENTIAL_GATE	900	某次執行因為憑證無法為它提供服務，而擱置等待真人修復的秒數（限制於 0–3600）。見下文

憑證若為空值，會視同未設定，因此仍會套用內建的後備值。從原始碼自行建置的版本完全不附帶任何內建憑證。

Google Calendar 與 Klipy GIF 選擇器只能透過環境變數——沒有 --google-client-id / --klipy-app-key 旗標（未知旗標會被忽略）。請在環境中（或伺服器旁邊的 .env）設定 GOOGLE_OAUTH_CLIENT_ID + GOOGLE_OAUTH_CLIENT_SECRET，以及 KLIPY_APP_KEY。空值會停用該功能，而不是令啟動失敗。

--sandbox

伺服器會在啟動時探測主機一次，並在後端可用時，把代理的指令執行包裹在作業系統原生沙箱中：macOS 上是 sandbox-exec（Seatbelt），Linux 與 WSL2 上是 bwrap 加 socat。在沒有後端的地方——Windows，或缺少這些工具的 Linux 主機——執行會回退到環境清理、指令政策與操作護欄，而啟動記錄會說明當時適用哪一種狀態。

--sandbox off 是針對探測看不見的情況所用的現場終止開關：主機上的沙箱設定檔本身行為失當。它不需要重建，而伺服器會在整個行程存續期間記錄一則警告，因此這個狀態永遠不會是無聲的。

--tool-deferral

內建執行框架的執行會送出一個小的常駐工具定義集，加上其餘工具的名稱索引，這些工具的 schema 會在首次使用時才載入。這把工具區塊縮小約 78%，並讓永遠可見的集合落在模型能可靠選擇工具的區間之內。隨需載入的工具全程都仍可按名稱呼叫，而 search_tools 會按意圖找到它們。參見工具上下文與提示快取。

--tool-deferral off 會讓每個被准入的工具重新常駐，重現隨需載入出現之前伺服器所發出的請求。對於處理不好這種兩層式介面的模型，這是它的終止開關——是一個旗標，而不是要重建。它只影響內建執行框架；外部用戶端看到的 MCP tools/list 一律是完整目錄。

--credential-gate

若某次執行的供應商憑證缺失或已耗盡，該次執行會被擱置而非失敗：操作者會收到提示去修復它，而若他們修好，執行便會繼續。預設期限是 900 秒（15 分鐘），限制於 0–3600。

這個期限刻意遠長於核准提示的期限：核准是有人在數秒內作出的決定，而修復憑證則意味着要開啟終端、登入然後再回來。這個上限的作用，是要讓無人看管的執行——管線步驟、cron 觸發器、webhook——不會無了期地等待一個正在睡覺的人。當它到期時，執行會以它本來就會失敗的那則訊息失敗。

--credential-gate=0 就是終止開關：任何東西都不會被擱置，而一個壞憑證會結束該回合，情況與這道關卡存在之前完全相同。

子指令

指令	它的作用
cc_server	執行伺服器，直到收到 SIGINT/SIGTERM
cc_server pair	佈建一部裝置並印出其 id 與配對金鑰。對一個伺服器正在提供服務的資料目錄也是安全的——執行中的伺服器無須重新啟動就會接收該裝置
cc_server calendar connect --workspace <id>	透過裝置碼流程把 Google 帳戶連接到某個工作區，然後結束
cc_server update	檢查、下載並驗證較新的獨立發行版本
cc_server --version	印出版本與 git SHA——/healthz 與 RPC 握手所公佈的同一個身分

pair

旗標	預設值	含義
--device	web-client	裝置 id。平台由它推斷，因此 --device desktop 會建立一筆桌面資料列，而 --device ios/android 會建立一筆手機資料列；其他任何值都會當作網頁
--label	平台名稱加上本機的主機名稱	裝置清單中的顯示名稱
--host	localhost，或繫結至所有網絡介面時的 <this-host>	要嵌入所印出 URL 中的主機。請把它設為用戶端實際會撥打的 LAN IP 或通道主機
--client-url	未設定	受託管網頁用戶端的來源。會加入可掃描的深層連結與終端 QR 碼

pair 也接受核心的 --data-dir、--port 與 --bind 旗標：它們選定要寫入的資料目錄，並塑造所印出的伺服器 URL（回送上為 ws，--bind any 時為 wss）。對同一個 --device 重新執行 pair 會輪替它的金鑰，並丟棄該裝置的現行工作階段。在此簽發的憑證 沒有到期時間，不像應用程式內配對所設定的 30 天。

--client-url 的 QR 碼不是手機 QR 碼

pair --client-url 會填入網頁用戶端的連接表單（伺服器 URL、裝置 id 與金鑰都在 URL 片段中）。手機則以另一種承載內容配對，它是由應用程式內的配對面板簽發的——伺服器的完整連線描述元加上一個到期時間。兩者不能互換——參見配對裝置。

update

--apply 會替換整個安裝；若設定的連接埠上仍有伺服器回應，除非你傳入 --force，否則它會被拒絕。--allow-downgrade 允許較舊的發行版本。

對於不屬於它管的安裝，這個指令會直接拒絕，並給出解釋而不是錯誤：

環境	偵測方式	它會說甚麼
桌面應用程式內嵌的伺服器	CC_EMBEDDED=1 或 CC_BOOTSTRAP_DEVICE_ID	請改為更新應用程式——安裝程式會替換整棵目錄樹
dart run 原始碼檢出	指令碼路徑以 .dart 結尾	請用 git 更新它
Docker	容器標記	拉取較新的映像

行程生命週期

cc_server 會一直執行到收到 SIGINT / SIGTERM。有一個額外的環境變數管轄這件事，而它是由桌面應用程式設定，而不是由你設定：

變數	作用
CC_EXIT_WITH_PARENT=1	當它的父行程結束時，伺服器也會結束——判斷方式是父行程關閉其 stdin 管道的寫入端。桌面應用程式會設定它，這樣即使應用程式當掉，也永遠不會遺下一個仍持有資料目錄的孤兒伺服器

只有在你把 cc_server 當作子行程監督，並想要同樣的保證時，才自行設定它。

資料目錄佈局

預設資料目錄在 macOS 上是 ~/Library/Application Support/control-center， 在 Windows 上是 %APPDATA%\control-center，其他地方則是 $XDG_DATA_HOME/control-center（否則為 ~/.local/share/control-center）。只有在無法解析出家目錄或應用程式資料目錄時，才會使用相對於 cwd 的 .cc_server。

路徑	內容
global.db	工作區註冊表、使用者、已配對裝置、資訊動態與機群佇列
<workspaceId>/workspace.db	每個工作區一個資料庫——代理、空間、工單、記憶、程式碼圖
<workspaceId>/chat_credentials/	聊天機械人權杖，以純 JSON 儲存，因此它們會跟着工作區走
secrets.json	配對金鑰、供應商應用程式身分、每位使用者與 Google 權杖、SSO（0600）
backups/<timestamp>/	一份安裝快照——manifest.json、global.db 以及每個工作區的複本
backups/exports/	單一工作區匯出檔，<workspaceId>-<timestamp>.db
backups/transfer/	備份下載與上傳的暫存區；由寫入它的路由清掃
models/	裝置上的嵌入、說話人分離與語音模型
meetings/<meetingId>/	保留的會議音訊
rigs/images/	匯入的測試機磁碟映像（QEMU 桌面介面）
rigs/smolvm/<rigId>/	每部測試機的 microVM 執行階段狀態（仲介程式的密鑰，0600）
rigs/smolvm-packs/	預先解壓的機器套件——讓測試機重複啟動更快的快取
rigs/tls/	測試機 HTTPS 用的開發網域憑證頒發機構（金鑰 0600）
rigs/run/<rigId>/	QEMU 覆寫層、種子映像與每個 VM 的金鑰（0600）

另請參閱

• 執行無介面伺服器：這些旗標所屬的設定配方
• 執行機群工作節點：向這部伺服器註冊的獨立 cc_worker 二進位檔
• 備份與還原：把這個目錄複製到安全的地方
• 備份、匯出與匯入：快照佈局與每一項備份操作
• 連接遠端伺服器：讓用戶端指向它
• 部署與用戶端：為何伺服器擁有一切