# 快速開始

## 前置需求

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

## 安裝

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

或從原始碼建置：

```bash
git clone https://github.com/agenvoy/Agenvoy.git
cd agenvoy
make build
```

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

## 至少配置一個供應商

啟動 TUI 後執行 `/model`——它會逐步帶你完成供應商選擇、從該供應商 API 即時取得模型清單，以及憑證儲存。Token 會落在 OS keychain（macOS 用 `security`、Linux 用 `secret-tool`，其餘則回退至加密檔案），服務名稱固定為 `agenvoy`。

主要設定位於 `~/.config/agenvoy/config.json`，存放已註冊模型與 runtime 限制，不存憑證。

## 首次執行

```bash
agen
```

若 daemon 尚未執行會自動啟動。在 TUI 中以 `/new` 建立 session（可用 `/new <name>` 指定名稱，接著選一個 role 作為描述）、`/session` 切換 session。

輸入框始終保持 focus——直接輸入訊息，按 **Enter** 送出（**Alt+Enter** 插入換行；執行中按 **Enter** 則排入 steer 訊息）。輸入 **`/`** 開啟指令面板（比對指令名稱或說明）；**Tab**/**Enter** 確認選中項，**Esc** 關閉面板。輸入框為空時：**Shift+Tab** 切換自動核准、**Shift+F** 切換 fast 模式、**Shift+W**/**Shift+S** 輪替 session 模型、**Shift+A**/**Shift+D** 輪替 session 的 reasoning 等級（含 `auto`）。