# 快速開始

## 前置需求

- Linux（透過 bubblewrap 沙箱；若缺少 `bwrap` 會自動經 apt/dnf/yum/pacman/apk 安裝）或 macOS（`sandbox-exec`）
- 至少一個 LLM 供應商帳號——OAuth 訂閱（Codex、Copilot、Grok；`PATH` 上有本機 `claude` CLI 時另有 Claude Code）或 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/pardnchiu/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`；`secret-tool` 無法使用時改寫入 `~/.config/agenvoy/.secrets`（權限 0600）。讀取時依序查 keychain、該檔案、同名環境變數。

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

## 首次執行

```bash
agen
```

若 daemon 尚未執行會自動啟動。v1.2.0 起所有請求由 daemon 執行，TUI 經 Unix socket 與它通訊；連不上時狀態列顯示 `Connecting`。在 TUI 中以 `/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` 注入。