Terminal API

設定與安全

在設定 > 遠端控制 > Terminal API 啟用服務並產生 token。伺服器綁定 127.0.0.1，正式版預設埠為 3037，開發版為 3036。一般 API 預設停用，請保持本機連線，不要對公網公開。

Authorization: Bearer $TERMINAL_API_TOKEN
Content-Type: application/json

JSON 成功回應為 { success: true, data: ... }；失敗回應為 { success: false, error: { code, message, reason?, details? } }，請依 error.code 判斷。一般限額為每個 IP／method／path 每 60 秒 120 次，超過回傳 429 RATE_LIMITED。Bootstrap challenge 與 Webhook 入口的驗證例外見下文。

工作區與 session

{ "success": true, "data": { "workspaces": [
  { "id": "ws_123", "name": "my-project", "rootPath": "/path/to/project" }
] } }

Agent 自動化請設 background: true，避免占用分頁或窗格。前景 session 可指定 paneId 並設 stealFocus: false；放置選項不能與 background: true 同用，否則回傳 INVALID_PLACEMENT。

Session 路徑可用 id 或唯一分頁名稱，名稱須做 URL 編碼。id 優先於同名分頁；找不到或有多個同名分頁時回傳 SESSION_NOT_FOUND，解析程序失敗則回傳 SESSION_RESOLVE_FAILED。需要跨重新命名保持目標不變時，請使用 id。SSE 在訂閱時解析一次。

輸入

{ "data": "npm test", "appendEnter": true, "queueUntilReady": true, "readyTimeoutMs": 30000 }

queueUntilReady 等待 readiness 為 "idle"。等待逾時回傳 TERMINAL_NOT_READY，不寫入資料。無效 data 回傳 400 INVALID_INPUT_DATA；無效 submitKey 也不寫入。進入輸入處理後，成功回傳 data.requestId，失敗回傳 error.details.requestId；在進入處理前就被拒絕的請求不含此欄位。

遠端 peer 持有的 session 會拒絕 /input、/submit、/keys、/interrupt，回傳 409 SESSION_HELD_BY_PEER。請先在本機接手，不要重送相同的被拒請求。

輸出與 SSE

回應包含 data.sessionId、mode、lines、cursor、nextCursor、hasMore、truncated、windowStart、windowEnd、lineCount。增量讀取使用前次 nextCursor 作為 since。screen 不支援 since，優先讀 headless 狀態，DOM 備援需要可見窗格；source=headless 或 source=dom 可指定讀取路徑。content 的 chromeProfile 支援 claude-code、default、none。

Screen 回應包含 outputHash、unchanged。下次讀取帶 ifHash，hash 相同時回傳 unchanged: true 與空 lines。waitForChange=true 啟用長輪詢，data.wait 包含 changed、timedOut 與選填 reason: "LONGPOLL_TIMEOUT"。

終端 SSE 不重播保留的歷史。需要補讀時先呼叫 /output?since=... 再訂閱，之後以 payload.nextCursor 推進游標。讀取太慢可能被斷線。

版面

curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:3037/api/terminal/layout?full=true" | jq .data.layout > layout.json
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d @layout.json \
  http://127.0.0.1:3037/api/terminal/layout/restore

Keep-alive 與通知

{ "rule": { "id": "review", "enabled": true,
  "schedule": { "kind": "interval", "intervalMs": 1800000 },
  "message": "continue" } }

每個 session 最多 10 條啟用規則。若要每次觸發讀取 Prompt Library，設定 message: "" 與 promptRef: { slug: "review", scope: "project" }，也可用 scope: "global"。參照與內嵌文字互斥，prompt 不可含變數。專案參照取自目標的本機工作區。無效 prompt 會略過該次觸發，session 刪除時移除規則。

有 sessionId 且 Discord 支援 session 討論串時，訊息選擇 Discord；否則使用已連線的遠端 provider。未指定 session 時送至已連線的遠端平台。成功代表至少一個 provider 接受傳送；未送達回傳非 2xx 回應。

Agent sessions

此介面管理 provider session 與結構化對話記錄，與原始終端 session 分開。Provider: claude、codex、agy、duo、opencode；gemini 是 agy 的輸入別名，新回應使用 agy。

Callback 目標可用既有 AgentSession id，或其終端 id／唯一名稱。不會建立或附加 agent，也不用來回答權限提示。Key 不會自動去除重複事件；metadata 由呼叫端提供，不是經驗證的身分。成功只確認 provider 傳送，不代表任務完成。

Service tokens

UI token 可存取完整 API；service token 可限制為 terminal 與／或 agent-session，省略 scopes 時包含兩者。一般 API 停用時仍可做 bootstrap provisioning，但終端與 agent 端點回傳 403 DISABLED。

Webhook 入口

網址只顯示一次，請視為密鑰。目標須為停在輸入框等待的 agent；忙碌、不存在、名稱不明確、非 agent 或無法讀取畫面時拒絕，不寫入也不建立 session。submit: true 同時送出 Enter。成功為 { success: true, data: { delivered: true } }。

外部傳送者須自行設定支援 TLS 的 tunnel 或反向代理，只公開 /api/webhooks/...，避免存取記錄洩漏密鑰。其他 Terminal API 路徑不要公開；可在設定撤銷網址。

範例：背景終端

BASE="http://127.0.0.1:3037"
AUTH="Authorization: Bearer $TERMINAL_API_TOKEN"
WS=$(curl -s -H "$AUTH" "$BASE/api/terminal/workspaces" | jq -r ".data.workspaces[0].id")
SID=$(curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d "{\"workspaceId\":\"$WS\",\"background\":true}" \
  "$BASE/api/terminal/sessions" | jq -r ".data.session.id")
curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"data":"pwd","appendEnter":true,"queueUntilReady":true}' \
  "$BASE/api/terminal/sessions/$SID/input"
curl -s -H "$AUTH" "$BASE/api/terminal/sessions/$SID/output?mode=text&lines=20"
curl -s -X DELETE -H "$AUTH" "$BASE/api/terminal/sessions/$SID"