REST API
最後更新
Daemon 只監聽 loopback 位址——
127.0.0.1:17989 與 [::1]:17989——區網 client 無法連到。Port 固定，不可設定。同一個 daemon 在
/ 提供 web 儀表板。儀表板在編譯時內嵌進執行檔，因此 http://127.0.0.1:17989 就是全部介面——沒有託管在外的前端。開發時可用 AGENVOY_PAGE_DIR 把內嵌版本換成磁碟上的檔案（make dev）。自 v1.0.1 起儀表板可離線運作。
GET /sw.js 提供 service worker，把內嵌資產預先快取到帶版本號的 cache；GET /vendor/* 則從 ~/.config/agenvoy/vendor/ 提供第三方資產（QuickUI、Font Awesome、Material Symbols，以及 nanomd／voice 腳本），該目錄由 daemon 啟動時下載一次，執行檔版本變動時重新下載。頁面載入不會向 CDN 取任何東西。在 AGENVOY_PAGE_DIR 模式下 /sw.js 改為提供一支自我卸載的 worker，清掉自己的 cache 並解除註冊，避免開發版被舊快取蓋掉。標記 local 的端點另外要求請求來自
127.0.0.1/::1（localhostOnly() 守門）。這些端點管理憑證、設定檔或行程生命週期，設計對象是同機儀表板，不是遠端 client。未匹配的路由也套用同一道守門：未知的 /v1/ 路徑回 JSON 404，其他未知路徑則回退到儀表板首頁。v1.3.11 起，
Origin header 不是 loopback 來源（localhost、127.0.0.1、::1）的 POST、PUT、PATCH、DELETE 在路由前即回 403 [Denied] origin: ...；POST /v1/send 與 POST /v1/chat/completions 的 Content-Type 不是 application/json 時回 415 [Invalid] Content-Type: ...。沒有 Origin header 的請求（例如 curl）不受前一項檢查影響。Agent 執行
| Method | 路徑 | 說明 |
|---|---|---|
POST | /v1/send | 執行一次 agent 請求 |
POST | /v1/chat/completions | 無狀態、相容 OpenAI 的 chat completion |
GET | /v1/info/version | 編譯時寫入的版本（{version, dev}）；未打 tag 的組建 dev 為 true |
GET | /v1/log | SSE 串流。不帶 query 時只送 daemon slog 記錄（EventDaemonLog frame，source 即 level）——與 TUI 標題列同一路資料。其中包含新對話驗證碼，因此 daemon frame 只提供給 loopback 呼叫端。?sessions=a,b 在同一條連線附加這些 session 的事件；replay=0 跳過回補、daemon=0 去掉 daemon frame。遠端呼叫端或帶 daemon=0 時必須帶 sessions（否則回 400）。v1.3.8 起 session 事件附上後端格式化好的文字——trace（思考或工具呼叫行，例如 ⏵ API(Weather)）、工具呼叫與確認的 tool_display，以及確認事件的 confirm_title、restricted_lines、restricted_note——各介面顯示的用詞一致 |
GET | /v1/daemon | local — {content}：最近 28 天的 daemon.log 行。?from= / ?to=（yyyy-MM-dd-HH-mm，本地時間）縮限時間範圍，?keyword= 只保留包含該字串的行（不分大小寫）；時間格式錯誤回 400 |
GET | /v1/system/update | local — v1.0.11 新增。回 {version, latest, update_available}；latest 以追蹤 GitHub releases/latest/download/x 轉址取得（查不到時回 502 並附目前執行中的 version） |
POST | /v1/system/update | local — v1.0.11 新增。開一個終端機視窗執行 agen update，回 202 {status:"opened"}；更新本身跑在該終端機內，不在 daemon 內。macOS 用 Terminal.app、WSL 啟動 Windows 終端機、Linux 依序嘗試 xdg-terminal-exec、x-terminal-emulator、gnome-terminal、konsole、xfce4-terminal、kitty、alacritty、wezterm、xterm。找不到可用終端機回 501 |
GET | /v1/mcp/tools | 列出已連線 MCP server 註冊進來的工具（mcp__*） |
POST /v1/send 語意
Body 為
{content, stream?, session_id?, persist?, model?, reasoning?, skill?, work_dir?, rule?, task_hash?, exclude_tools?, enable_edit?, enable_sandbox?, enable_markdown?}，content 必填。v1.3.9 起以 stream、rule、task_hash 取代 sse、system_prompt、pending_task；舊名稱仍視為別名接受，之後會移除。v1.3.5 起 model 與 reasoning 只作用於這次請求，不改 session 預設：未帶 model 用 session 模型，auto 即使 session 已固定模型仍交給 dispatcher，未帶 reasoning 用 session 等級。Web 對話的選擇存在瀏覽器 cookie，隨請求送到這裡。work_dir 預設為家目錄，必須解析到既有的目錄（否則回 400）。rule 為該次執行附加額外系統指示；enable_markdown:false（v1.3.9，預設 true）會再附加一條規則，要求不含 markdown 語法的純文字回覆。task_hash 在該 pending 任務仍有背景 job 時接續它。若 session 仍在執行中，新請求會以 steer 訊息附加到該次執行，而不是另起一次，並立即回 {session_id}（steer:true 欄位移除於 v1.3.9）。其餘情況 stream:true 以串流送出執行事件；未帶時於執行結束後回 {text, model, usage, session_id}，被取消時回 {session_id, canceled:true}（失敗回 500 並帶 error）。v1.3.9 起，帶
enable_edit 或 enable_sandbox，或抵達時沒有開啟中的網頁確認 listener 的請求，以 API auto mode 執行：一律不跳確認；未設 enable_edit:true 時唯讀（擋寫入與非唯讀指令）；未設 enable_sandbox:false 時留在沙箱（擋 $HOME 外路徑、sudo、sandbox: false）；不提供 ask_user、store_secret 與背景工具；請求開始時清除該 session 的路徑授權。被擋的呼叫回 [Denied] 並指出可放行的參數。v1.3.9 之前，這類無人值守的請求會直接放行寫入與受限存取。v1.3.11 起 enable_sandbox:false 只接受 loopback 連線，其他位址的請求回 403 [Denied] enable_sandbox: false is accepted only from this machine。persist | session_id | 結果 |
|---|---|---|
false（預設） | 空 | 建立 temp-<uuid>，30 分鐘無變動後刪除 |
true | 空 | 建立 chat-<uuid>，保留 |
| 任意 | 有給 | 使用指定的 session_id（忽略 persist） |
chat 旗標與 http- 前綴已於 v1.0.11 移除：以 HTTP 建立的持久 session 改用儀表板同樣的 chat- 前綴，所有非 CLI 的持久 session 統一成同一種前綴。既有的 http- session 仍可透過 session_id 指名繼續使用。- curl --fail-with-body -sS \
- -H 'Content-Type: application/json' \
- -d '{"content":"List the available tools","persist":false}' \
- http://127.0.0.1:17989/v1/send
POST /v1/chat/completions：OpenAI 相容的路由端點
/v1/chat/completions 為無狀態：需要延續脈絡時，每次請求都要帶上先前訊息。reasoning_effort 接受 none low medium high xhigh max（以及別名 minimal extra ultra）；省略或無法辨識的值會回退到模型選擇器為該請求挑選的等級（未挑選時為 medium）。model 預設為 auto。預設情況下 completion 不帶任何 Agenvoy 自身的工具：只提供 client 送來的
tools。帶上標頭 X-Agenvoy-Agent: 1（或 true / yes）時改以 Agenvoy agent 執行——使用 Agenvoy 的 system prompt 與 TUI 專用以外的全部工具。不論哪種模式，此端點都會略過工具確認。任何 OpenAI client 都能把 Agenvoy 當成模型路由器：把 SDK 的 base URL 設為
http://127.0.0.1:17989/v1。此端點不檢查 API key，填任意值即可。GET /v1/models 列出所有已註冊模型與 auto（見模型端點）。model | 由哪個模型回應 | Fallback |
|---|---|---|
auto（預設） | dispatcher 模型依請求的工作類型挑選 worker 模型（見模型路由） | 送出失敗時，由優先序中下一個不同供應商、且通過 10 秒健康檢查的模型接手，最多四輪 |
<provider>@<model> | 直接使用該已註冊模型；未註冊的名稱回 [Not found] model | 無 |
逾時與 rate limit 會先在同一個模型重試最多三次，之後才 fallback。未帶
stream 時回傳單一 chat.completion 物件，fallback 後仍失敗則回 502、type: upstream_error；stream: true 時以 SSE 回傳 chat.completion.chunk，最後一筆為 data: [DONE]。usage 回報 prompt_tokens（含快取讀取）、completion_tokens 與 prompt_tokens_details.cached_tokens。client 送了 tools 且模型呼叫其中之一時，回應帶 tool_calls 與 finish_reason: "tool_calls"，由 client 自行執行工具。system prompt 來自 Zed 時，以其中列出的專案根目錄為工作目錄，否則使用家目錄。LiteLLM 是把多家供應商包成單一 OpenAI 格式 API 的 proxy server，OpenRouter 是在多家供應商間轉送請求的雲端 API。Agenvoy 的端點跑在你自己的電腦上，在你於 Agenvoy 註冊的模型之間路由，包含 Claude Code 與 Codex 訂閱供應商，並依工作類型挑選模型。