# config.json

`~/.config/agenvoy/config.json` 的每個鍵、預設值與讀取它的地方。

模型、路由與 channel 設定：

| 鍵 | 說明 |
|---|---|
| `models` | 已註冊模型，格式為 `"<provider>@<model>"` 字串；順序即 fallback 優先序（v1.1.0 起略過 `pass` tier 模型） |
| `model_tag` | `{model: tier}`，tier 為 `S` `A` `B` `C` `pass`；缺少時寫入 `{}`。v1.1.0 起 `pass` 模型不會被 auto routing、subagent 或 fallback 選用，即使請求指名也一樣；只有把自身模型設為它的 session 會使用 |
| `dispatcher_model` / `summary_model` | Dispatcher 與 summary 角色 |
| `dispatcher_beta` | v1.0.18 新增。`true` 表示改由 TypeSafe dispatcher 路由，不再使用 `dispatcher_model`；需 keychain 中的 `TYPESAFE_API_KEY` |
| `image_generator` / `stt_model` / `tts_model` | 圖像 provider 端點與音訊模型 |
| `compats` | 自訂 OpenAI 相容端點，`[{provider, url}]` |
| `keys` | 存於 keychain 的憑證名稱（絕不含值） |
| `telegram_enabled` / `discord_enabled` | Channel 旗標；`telegram_username` / `discord_username` 由 daemon 補上 |
| `admin_channel` | 驗證碼轉發目標（v1.1.0 起由 TUI `/config` → **Admin Channel** 設定） |
| `reply_lang` | 回覆語言，預設 `"auto"`（跟隨使用者）。接受 `configs/jsons/reply_lang.json` 中的代碼（`en`、`zh-TW`、`zh-HK`、`zh-CN`、`ja`、`ko`、`es`、`fr`、`de`、`pt`、`it`、`ru`、`vi`、`th`、`id`、`ar`）或任何語言名稱 |
| `output_dir` | 未指定位置時為使用者產出檔案的存放處；預設 `""` 代表 `~/Downloads`，該資料夾不存在時為 `~/.config/agenvoy/download`。會展開 `~`；路徑無法使用時回到預設 |

`reply_lang` 與 `output_dir` 可由 TUI `/config`，或 `GET` / `POST` `/v1/config/system` 與 `/v1/config/output_dir` 設定；`/config` 也可切換 **Startup on login**（`/v1/config/startup`）。原本獨立的 startup、reply-language、output-dir TUI 指令已移除，改用 `/config`。Daemon 監看 `config.json`，每次寫入都會重新載入 agent registry 與 Telegram / Discord。

`auto_reasoning`（v1.0.18 新增）已於 v1.1.0 移除：reasoning 改為 per-session 設定，`reasoning` 為 `auto` 的 session 由模型選擇器逐請求決定等級。`config.json` 中殘留的 `auto_reasoning` 會被忽略。

除了模型與 channel 設定，`config.json` 也承載 runtime 限制與可選的 policy 覆寫。缺少的限制欄位、`reply_lang`、`output_dir` 與 `model_tag` 會以預設值補齊並於啟動時寫回。

| 鍵 | 預設 | 說明 |
|---|---:|---|
| `limits.max_tool_iterations` | `128` | 單次執行的 tool 迭代上限 |
| `limits.agent_send_timeout_seconds` | `600` | 模型請求 timeout |
| `limits.max_history_messages` | `24` | 保留的近期歷史訊息數 |
| `limits.max_history_bytes` | `4194304` | 歷史大小上限。v1.0.12 由 `5242880` 改為 `DocumentMaxBytes * 4`，即單一文件 1 MiB 上限的四倍 |

**不從** `config.json` 讀取的套件層預設值：

| 常數 | 預設 | 說明 |
|---|---:|---|
| `MaxSessionTasks` | `NumCPU × 4` | 每個 session 的並行任務數；超出者排隊而非失敗 |
| `MaxSubagentTimeoutMin` | `30` | Subagent timeout（分鐘） |
| `MaxResumeWaitMin` | `60` | 待處理續跑等待回答的時間上限 |
| `maxConcurrentTools` | `5` | 單一模型回合內同時執行的 tool call 數；其餘排隊（v1.0.20） |

Daemon port **不可設定**：`17989` 為套件常數，`limits.port` 條目會被忽略。

`config.json` 的 policy 鍵。前兩者會與編譯進 binary 的內建值合併（使用者項目是追加，永不取代預設）；其餘僅存在於使用者設定：

| 鍵 | 內建來源 | 用途 |
|---|---|---|
| `sensitive_path` | `configs/jsons/sensitive_path.json` | 憑證與金鑰路徑——需經密碼驗證的 per-session 授權才能存取。分類：`dirs`、`files`、`prefixes`、`extensions` |
| `read_only_command` | `configs/jsons/read_only_command.json` | 跳過 confirm gate 的 `run_command` 呼叫（`git status`、`ls`、`cat` ...）。v1.0.25 起條目比對 binary 加上最多前兩個參數（`git config --get`、`docker compose ps`），帶 `network: true` 或參數含敏感路徑的呼叫一律不符合，專用的唯讀指令工具也已移除 |
| `denied_command` | — | `run_command` 一律拒絕的 binary，`sh -c` 內亦然 |
| `denied_path` | — | 讀寫皆永久禁止的路徑；任何提示都無法核准。條目須為絕對路徑或以 `~/` 開頭；拒絕檔案系統根目錄 |
| `net_white_list` | — | 豁免 `http_request` SSRF 防護的 host |

三個鍵已不再讀取，若存在會在啟動時記警告：`sensitive_map`（更名為 `sensitive_path`）、`white_list`（移除——不在 `denied_command` 的指令皆可執行）、`path_white_list`（移除——`$HOME` 之外的路徑改為逐 session 核准）。

v0.35.0 移除最後一批 pre-v0.28.9 相容路徑：`limits.max_skill_iterations`（由 `limits.max_tool_iterations` 取代）與 `planner_model`（由 `dispatcher_model` 取代，下次儲存時會從 `config.json` 刪除）不再被採用，舊的 `api_tools/`／`script_tools/` 目錄也不再讀取——工具改放 `tools/api/` 與 `tools/script/`。

Runtime 限制**沒有環境變數**——env 覆寫已移除，`config.json` 是唯一調整點。