# 新手入門

從零到可用 agent 的最短路徑：一行安裝、一把免費 API 金鑰、一個模型。不需信用卡，不需手改設定檔。

若你已有供應商帳號，[快速開始](/zh/docs/getting-started) 涵蓋同樣的流程，但選項與細節更多。

## 1. 安裝

```bash
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`。

確認安裝成功：

```bash
command -v agen
```

## 2. 申請免費的 Ollama Cloud 金鑰

Ollama Cloud 是最省事的起點：免費方案不需綁定付款方式，而 `gemma4:31b` 可在免費方案上使用 —— 足以在不綁卡的情況下先跑起一個能用的 agent。

1. 開啟 **[ollama.com/settings/keys](https://ollama.com/settings/keys)**
2. 註冊或登入
3. 建立新的 API key
4. 複製金鑰

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

## 3. 加入模型

啟動 TUI：

```bash
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** 會把一般文字作為引導訊息送出，而不是中斷執行；`/` 指令要等執行結束。

## 接下來

| 你想要 | 閱讀 |
|---|---|
| 加入第二個供應商，或為不同 session 指定模型 | [模型管理](/zh/docs/providers-config) |
| 了解 agent 現成能做什麼 | [內建工具](/zh/docs/built-in-tools) |
| 讓 agent 自己建立並保存工具 | [工具擴充](/zh/docs/tool-extension) |
| 把你的工具分享給 Claude Code 或 Codex | [MCP 伺服器](/zh/docs/mcp-server) |
| 排定每天早上自動執行的任務 | [排程](/zh/docs/scheduler-skills) |
| 改用瀏覽器操作 | 啟動 `agen` 後開啟 `http://127.0.0.1:17989` |