v1.3.23

安裝與模型設定

最後更新


在 macOS 或 Linux 安裝 Agenvoy、登入 GitHub Copilot,再加入第一個模型。這個流程不需要建立 API 金鑰或手動編輯設定檔。若你已在電腦上執行本機模型,請參考如何連接 Ollama 或其他 OpenAI 相容端點。

前置需求


  • Linux(透過 bubblewrap 沙箱;若缺少 bwrap 會自動經 apt/dnf/yum/pacman/apk 安裝)或 macOS(sandbox-exec)
  • 至少一個 LLM 供應商帳號——OAuth 訂閱(Codex、Copilot、Grok;PATH 上有本機 claude CLI 時另有 Claude Code)或 API key(OpenAI、Claude、Gemini、Grok、DeepSeek、Mistral、NVIDIA、Ollama Cloud、OpenRouter、Cloudflare),或本機 OpenAI 相容 server(Ollama、LM Studio、自訂 URL)
  • 僅在從原始碼建置時需要 Go 1.26.10 或更高版本
  • 選用:pdftotext(poppler-utils)供 read_files 解析 PDF
  • 選用:OPENAI_API_KEY 以啟用語意搜尋(text-embedding-3-small)
  • 選用:OpenAI、Gemini 或 OpenRouter 憑證以啟用音訊 —— /model stt 讓 read_files 能轉錄音訊與影片,/model tts 則註冊 generate_audio。未選模型前兩者皆為關閉

1. 安裝


  1. curl -fsSL https://agenvoy.com/scripts/install.sh | bash

腳本會判斷 macOS 或 Linux,將 agen 執行檔安裝到 /usr/local/bin,並補齊所需依賴(git、make、C 編譯器、python3、node、pdftotext,Linux 另加 bwrap)。過程會要求一次 sudo,用於寫入 /usr/local/bin。
Android 手機請在 Termux 內以 proot-distro 安裝 Ubuntu,再於其中執行安裝腳本;直接在 Termux 執行會中止,因為 Linux 執行檔無法在 Termux 上執行:
  1. pkg install proot-distro
  2. proot-distro install ubuntu
  3. proot-distro login ubuntu
  4. apt update && apt install -y curl
  5. curl -fsSL https://agenvoy.com/scripts/install.sh | bash

Android 封鎖了 bwrap 需要的 user namespace,因此 run_command 在該環境不經沙箱執行;也沒有 secret-tool keyring,憑證會存到 ~/.config/agenvoy/.secrets。
確認安裝成功:
  1. command -v agen

或從原始碼建置:
  1. git clone https://github.com/pardnchiu/Agenvoy.git
  2. cd agenvoy
  3. make build

make build 會編譯、把當前 exact-match 的 git tag 寫進 internal/runtime.CurrentVersion、將 binary 安裝至 /usr/local/bin/agen,並刷新內建的 skill 與 tool。

2. 訂閱 GitHub Copilot


GitHub Copilot($10/月)是 Agenvoy 推薦的最低成本起點:費用每月固定,agent 多跑幾輪也不會讓帳單跳動。
Agenvoy 不再推薦免費方案。Ollama Cloud 自 2026-11-09(PT 下午 5:40)起 Free 方案改為 pay-as-you-go,其雲端模型(gemma4:31b、gpt-oss:120b、gpt-oss:20b、nemotron-3-super、nemotron-3-ultra)需購買 credits。以 Ollama 在本機執行仍然免費,但小型本機模型的 tool calling 不穩定。
  1. 開啟 github.com/features/copilot/plans
  2. 登入並訂閱 $10/月的方案

3. 加入模型


啟動 TUI:
  1. agen

接著在 TUI 內:
步驟操作
1輸入 /model 按 Enter
2選 add —— add model from provider
3選單預設開在 OAuth 分頁,選 GitHub Copilot
4視窗顯示驗證網址與使用者代碼,有圖形介面時會自動開啟該頁(按 Enter 可重新開啟),在 10 分鐘內輸入代碼並授權。token 直接寫入 OS keychain —— 不進設定檔,也不進對話
5從你的 Copilot 方案提供的模型中選 luna 模型

設定到此結束。模型登記在 ~/.config/agenvoy/config.json,憑證不在裡面。憑證存在 OS keychain(macOS 用 security、Linux 用 secret-tool),服務名稱固定為 agenvoy;secret-tool 無法使用時改寫入 ~/.config/agenvoy/.secrets(權限 0600)。讀取時依序查 keychain、該檔案、同名環境變數。
選 luna 模型的理由是額度損耗夠慢、能力也夠日常使用。Shift+U 可查看 Copilot 剩餘額度。

4. 選用:加入 decision model(TypeSafe Jev)


Decision model 是另一個小很多的模型,不負責回覆,只在零點幾秒內替 agent 回答選擇題:哪些 skill 和這個請求有關、哪些搜尋結果與網頁區塊是雜訊、哪些記憶條目這輪用得到。沒有它 Agenvoy 照樣能跑;有了它,每輪帶進 context 的無關內容會少很多。Jev 是 TypeSafe 專做這件事的模型。
  1. 開啟 console.typesafe.ai/keys,登入並建立 API key。Jev 目前是 early access,只依輸入 token 計費:每十億輸入 token $42,輸出不收費(docs.typesafe.ai/models,2026-11-11 查核)
  2. 在 TUI 輸入 /model → add → 切到 API Key 分頁 → 選 TypeSafe(在該列按 o 會開啟同一個金鑰頁)→ 貼上金鑰。金鑰以 TYPESAFE_API_KEY 存進 OS keychain,畫面提示 TypeSafe API key saved; pick its model in /model decision
  3. 輸入 /model → 切到 decision 分頁 → 選 typesafe@jev-latest,它會跟著最新的 Jev 版本

v1.3.0 之後它做了什麼


Decision model 從 v1.3.0 之後的第一個版本 v1.3.1 開始提供,取代原本只負責分派的 Jev beta,之後每個版本都多接了幾項判斷(完整清單見 Decision Model)。以下是作者本機 2026-11-05 至 2026-11-11 的實測,數字取自 daemon 自己的 debug log,不是 benchmark:
判斷次數結果
Skill 清單57611,846 筆 skill 條目中有 11,353 筆(95.8%)判定無關、不放進 turn context,每輪從約 21 個 skill 減到約 1 個
Session 摘要3278 筆記憶條目篩到與請求相關的 27 筆(v1.3.7)
摘要合併159496 段對話中有 74 段判為雜訊移除,另移除 20 條過時決策
工具缺口5658 次判定需要尚不存在的工具,直接引導 agent 去建工具
網頁擷取603,677 個頁面區塊中有 111 個導覽或樣板區塊在快取前移除
搜尋結果60648 筆結果中 9 筆離題被剔除

這些判斷只有 2 次失敗;判斷失敗時內容維持原樣,所以最差的情況就等於沒有設定 decision model。

5. 問它一件事


在輸入框打字後按 Enter:
  1. 台北現在天氣如何?

Agenvoy 並沒有內建天氣工具。可以觀察它怎麼做:agent 先查自己的工具註冊表、找不到、取得建工具的契約、挑一個公開 API、寫出 Python 工具、在沙箱測試,然後呼叫它並回答。這個工具會被保存 —— 第二次問就直接執行。
再試幾個:
  1. 幫我摘要這個資料夾裡的 README
  2. 每天早上 8 點回報台積電股價
  3. 我的文件裡哪一份提到 prompt guide?

使用 TUI


若 daemon 尚未執行會自動啟動。v1.2.0 起所有請求由 daemon 執行,TUI 經 Unix socket 與它通訊;連不上時狀態列顯示 Connecting。以 /new 建立 session(可用 /new <name> 指定名稱,接著選一個 role 作為描述)、/session 切換 session。
輸入框始終保持 focus——直接輸入訊息,按 Enter 送出(Alt+Enter 插入換行;執行中按 Enter 會把一般文字作為 steer 訊息送出,/ 指令要等執行結束)。輸入 / 開啟指令面板(比對指令名稱或說明);Tab/Enter 確認選中項,Esc 關閉面板。輸入框為空時:Shift+Tab 切換自動核准(⏸ safe ↔ ⏵⏵ auto;TUI 在 $HOME 底下的子目錄啟動時為 auto)、Shift+F 切換 fast 模式、Shift+W/Shift+S 輪替 session 模型、Shift+A/Shift+D 輪替 session 的 reasoning 等級(含 auto)、Shift+G 切換 CLAUDE.md / AGENTS.md 注入。
下一步:上手之後 整理了要先記住的六個按鍵與接下來的閱讀方向。
EN