安裝與模型設定
最後更新
在 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上有本機claudeCLI 時另有 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. 安裝
- 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 上執行:- pkg install proot-distro
- proot-distro install ubuntu
- proot-distro login ubuntu
- apt update && apt install -y curl
- curl -fsSL https://agenvoy.com/scripts/install.sh | bash
Android 封鎖了
bwrap 需要的 user namespace,因此 run_command 在該環境不經沙箱執行;也沒有 secret-tool keyring,憑證會存到 ~/.config/agenvoy/.secrets。確認安裝成功:
- command -v agen
或從原始碼建置:
- git clone https://github.com/pardnchiu/Agenvoy.git
- cd agenvoy
- 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 不穩定。- 開啟 github.com/features/copilot/plans
- 登入並訂閱 $10/月的方案
3. 加入模型
啟動 TUI:
- 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 專做這件事的模型。
- 開啟 console.typesafe.ai/keys,登入並建立 API key。Jev 目前是 early access,只依輸入 token 計費:每十億輸入 token $42,輸出不收費(docs.typesafe.ai/models,2026-11-11 查核)
- 在 TUI 輸入
/model→ add → 切到 API Key 分頁 → 選 TypeSafe(在該列按o會開啟同一個金鑰頁)→ 貼上金鑰。金鑰以TYPESAFE_API_KEY存進 OS keychain,畫面提示TypeSafe API key saved; pick its model in /model decision - 輸入
/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 清單 | 576 | 11,846 筆 skill 條目中有 11,353 筆(95.8%)判定無關、不放進 turn context,每輪從約 21 個 skill 減到約 1 個 |
| Session 摘要 | 32 | 78 筆記憶條目篩到與請求相關的 27 筆(v1.3.7) |
| 摘要合併 | 159 | 496 段對話中有 74 段判為雜訊移除,另移除 20 條過時決策 |
| 工具缺口 | 565 | 8 次判定需要尚不存在的工具,直接引導 agent 去建工具 |
| 網頁擷取 | 60 | 3,677 個頁面區塊中有 111 個導覽或樣板區塊在快取前移除 |
| 搜尋結果 | 60 | 648 筆結果中 9 筆離題被剔除 |
這些判斷只有 2 次失敗;判斷失敗時內容維持原樣,所以最差的情況就等於沒有設定 decision model。
5. 問它一件事
在輸入框打字後按 Enter:
- 台北現在天氣如何?
Agenvoy 並沒有內建天氣工具。可以觀察它怎麼做:agent 先查自己的工具註冊表、找不到、取得建工具的契約、挑一個公開 API、寫出 Python 工具、在沙箱測試,然後呼叫它並回答。這個工具會被保存 —— 第二次問就直接執行。
再試幾個:
- 幫我摘要這個資料夾裡的 README
- 每天早上 8 點回報台積電股價
- 我的文件裡哪一份提到 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 注入。下一步:上手之後 整理了要先記住的六個按鍵與接下來的閱讀方向。