新手入門

從零到可用 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。

確認安裝成功：

agen --version

2. 申請免費的 NVIDIA NIM 金鑰

NVIDIA NIM 是最省事的起點：免費額度不需綁定付款方式，且提供 gpt-oss-120b —— 一個規模足以穩定進行 tool calling 的開源權重模型，而 tool calling 正是 agent 能不能用的關鍵。

1. 開啟 build.nvidia.com/explore/discover
2. 註冊（Email，或用既有的 Google / GitHub / NVIDIA 帳號）
3. 進入任一模型頁面，點 Get API Key
4. 複製金鑰 —— 開頭是 nvapi-

金鑰先留在剪貼簿，下一步會用到。

3. 加入模型

啟動 TUI：

agen

接著在 TUI 內：

設定到此結束。模型登記在 ~/.config/agenvoy/config.json，憑證不在裡面。

想用更小的？同一份清單裡有 openai/gpt-oss-20b，但 100B 以下的開源權重模型 tool calling 並不可靠 —— 先知道這件事，免得之後誤會是 agent 的問題。

4. 問它一件事

在輸入框打字後按 Enter：

台北現在天氣如何？

Agenvoy 並沒有內建天氣工具。可以觀察它怎麼做：agent 先查自己的工具註冊表、找不到、取得建工具的契約、挑一個公開 API、寫出 Python 工具、在沙箱測試，然後呼叫它並回答。這個工具會被保存 —— 第二次問就直接執行。

再試幾個：

幫我摘要這個資料夾裡的 README
每天早上 8 點回報台積電股價
我的文件裡哪一份提到 prompt guide？

5. 記住這五個按鍵

在輸入框為空的狀態下：

Enter 送出，Alt+Enter 換行。執行中按 Enter 會排入一則引導訊息，而不是中斷執行。

進階：兩個訂閱制供應商

免費額度不夠用時，下一步不是再開一把按量計費的 API key，而是接上你可能已經在付的訂閱。這兩個是備援／第二個模型的首選：費用本來就是每月固定，agent 多跑幾輪也不會讓帳單跳動。

兩者都不需要 API key，改用 device-code OAuth 驗證，token 與其他憑證一樣存進 OS keychain。

加入 Codex

加入 Grok (xAI)

已經授權過的話，流程會先問 <Provider> token exists · re-login?。選 No keep existing 沿用既有 token 並直接跳到模型清單 —— 只有要換帳號時才選 Yes re-authenticate。

註冊多個模型之後，TUI 內 Shift+W / Shift+S 可切換 dispatcher 模型，/model dispatch 與 /model summary 則用來明確指定 dispatcher 與 summary 模型。

接下來

遇到問題