新手入門
最後更新
從零到可用 agent 的最短路徑：一行安裝、一把免費 API 金鑰、一個模型。不需信用卡，不需手改設定檔。
若你已有供應商帳號，快速開始 涵蓋同樣的流程，但選項與細節更多。
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。
確認安裝成功：
command -v agen
2. 申請免費的 Ollama Cloud 金鑰
Ollama Cloud 是最省事的起點：免費方案不需綁定付款方式，而 gemma4:31b 可在免費方案上使用 —— 足以在不綁卡的情況下先跑起一個能用的 agent。
- 開啟 ollama.com/settings/keys
- 註冊或登入
- 建立新的 API key
- 複製金鑰
金鑰先留在剪貼簿，下一步會用到。
3. 加入模型
啟動 TUI：
agen
接著在 TUI 內：
| 步驟 | 操作 |
|---|---|
| 1 | 輸入 /model 按 Enter |
| 2 | 選 add —— add model from provider |
| 3 | 按 → 切到 API Key 分頁，選 Ollama Cloud（選單預設開在 OAuth 分頁；在某列按 o 會開啟該供應商的金鑰頁面） |
| 4 | 貼上金鑰。輸入為遮罩顯示，金鑰直接寫入 OS keychain —— 不進設定檔，也不進對話 |
| 5 | Agenvoy 會即時拉取 Ollama Cloud 的模型清單，選 gemma4:31b |
設定到此結束。模型登記在 ~/.config/agenvoy/config.json，憑證不在裡面。
選它的理由是免費方案就能用，因此不綁卡也能把 agent 跑起來。免費方案有用量上限，請到 Ollama 帳號查看；Shift+U 已不再回報 Ollama Cloud（移除於 v1.2.0）。開源權重模型的 tool calling 不如前沿模型可靠 —— 先知道這件事，免得之後誤會是 agent 的問題。把它當 dispatcher 用，session 模型日後改指向訂閱方案（ChatGPT Plus、SuperGrok）。
4. 問它一件事
在輸入框打字後按 Enter：
台北現在天氣如何？
Agenvoy 並沒有內建天氣工具。可以觀察它怎麼做：agent 先查自己的工具註冊表、找不到、取得建工具的契約、挑一個公開 API、寫出 Python 工具、在沙箱測試，然後呼叫它並回答。這個工具會被保存 —— 第二次問就直接執行。
再試幾個：
幫我摘要這個資料夾裡的 README
每天早上 8 點回報台積電股價
我的文件裡哪一份提到 prompt guide？
5. 記住這六個按鍵
在輸入框為空的狀態下：
| 按鍵 | 作用 |
|---|---|
/ |
指令面板 —— 可用指令名稱或描述搜尋 |
| Shift+Tab | 切換自動核准（否則每個非唯讀工具呼叫都會先詢問） |
| Shift+F | 切換 fast mode |
| Shift+G | 切換 CLAUDE.md / AGENTS.md 注入（啟動時為關閉）。開啟且工作目錄有其中一個檔案時，模式列顯示 [CLAUDE.md] 或 [AGENTS.md]，該檔加入每輪的 context；兩者皆有時採用 CLAUDE.md |
| Shift+W / Shift+S | 切換 session 模型（auto 或已註冊模型） |
| Esc | 關閉彈出視窗或通知框；執行中按下會詢問要取消或暫停 |
Enter 送出，Alt+Enter 換行。執行中按 Enter 會把一般文字作為引導訊息送出，而不是中斷執行；/ 指令要等執行結束。