設定

用 settings.json 設定

Ferret 的所有設定都存放在一個 JSON 檔中，旁邊附有 JSON Schema，因此你或你的程式設計 Agent（例如 Claude Code、Codex 或 Gemini CLI）只要編輯檔案就能設定 App。變更會在 App 執行中直接套用。

#檔案位置

所有作業系統的路徑都相同：

~/.ferret/settings.json          # your settings (edit this)
~/.ferret/settings.schema.json   # JSON Schema, rewritten by the app on launch
~/.ferret/state.json             # open folder, last URL, open tabs (managed by the app)
~/.ferret/.env                   # optional: API keys referenced by apiKeyEnv

設定 FERRET_CONFIG_DIR（舊名稱 MOVIE_ADE_CONFIG_DIR 也可使用）即可改用其他資料夾，例如 dotfiles 儲存庫中的資料夾。~ 會被展開。
開發版建置（pnpm dev）使用 ~/.ferret/dev/，因此開發 Ferret 時絕不會改寫你實際的設定。
從 0.1.0 升級：首次啟動時，舊的 <userData>/settings.json 會被複製到新檔案中。舊檔案會原樣保留作為備份，且不會被修改。

從 MOVIE-ADE 升級：首次啟動時，settings.json、state.json、usage/ 與 .env 會從 ~/.movie-ade/ 複製到 ~/.ferret/。舊資料夾會原樣保留，不會被修改。

在 App 中，設定頁面頂端會顯示路徑，並提供開啟 settings.json（在內建編輯器中編輯，支援依 Schema 自動完成）與在資料夾中顯示。

#Schema 與驗證

settings.json 的第一行是 "$schema": "./settings.schema.json"。VS Code 等編輯器與 Claude Code 等 Agent 會用它來自動完成、驗證，以及顯示每個欄位的說明。Schema 內建於 App 中，每次啟動時都會寫到檔案旁邊，因此一定與已安裝的版本一致。

App 儲存時，Ferret 不認得的鍵會原樣保留。開啟的分頁、最後的 URL 及其他工作階段狀態存放在 state.json，而不是這裡。

#附註解的範例

JSON 不支援註解，因此說明寫在範例下方。所有欄位都是選填的；不需要的就省略。

{
  "$schema": "./settings.schema.json",
  "theme": "dark",
  "locale": "en",
  "projects": [
    {
      "id": "shop",
      "name": "shop",
      "folderPath": "/Users/you/src/shop",
      "kind": "web",
      "urls": [
        { "id": "local", "label": "local", "url": "http://localhost:3000" },
        { "id": "prd", "label": "prd", "url": "https://shop.example.com" }
      ]
    }
  ],
  "agents": {
    "customAgents": [
      { "id": "custom:my-agent", "name": "My agent", "command": "my-agent", "args": "--yes" }
    ],
    "startupAgents": ["claude", "custom:my-agent"]
  },
  "capture": {
    "transcription": "compatible",
    "language": "auto",
    "costLimitUsd": null,
    "sttEndpoints": {
      "compatible": {
        "baseUrl": "http://gpu-box.local:8000/v1",
        "model": "Systran/faster-whisper-large-v3",
        "apiKeyEnv": "WHISPER_SERVER_TOKEN"
      }
    }
  },
  "organizer": {
    "runner": "api:compatible",
    "endpoints": {
      "compatible": { "baseUrl": "http://localhost:11434/v1", "model": "qwen3:14b" }
    }
  },
  "decision": {
    "enabled": true,
    "preset": "ollama",
    "endpoint": "http://localhost:11434/v1/systemone",
    "model": "clef-flash"
  },
  "layout": {
    "panels": {
      "projects": { "dock": "left", "visible": true },
      "terminal": { "dock": "bottom", "visible": true },
      "files": { "dock": "right", "visible": false }
    }
  }
}

projects[].urls：URL 選單中的審查目標。開啟專案時會開啟第一個。id 可以是任何不重複的字串。
agents.customAgents：任何 CLI 或包裝腳本。startupAgents 依序列出開啟專案時要開啟的 Agent 分頁。
capture.sttEndpoints.compatible：任何實作 OpenAI /v1/audio/transcriptions 的伺服器（speaches、vLLM、LocalAI…）。costLimitUsd: null 會關閉費用上限，適合使用自己的 GPU 時。請參閱轉錄與費用。
organizer：將整理意見直接送到相容 OpenAI 的 /v1/chat/completions 伺服器（此例為 Ollama）。若要改用你自己的 CLI 登入，請使用 "runner": "claude-code" 或 "codex"，並用 organizer.cliModels 選擇其模型。
decision：檢查每則意見是否已修正的模型。在本機 Ollama 上執行的 Clef Flash 免費，且能讀取螢幕截圖。preset 也可以是 cloudflare、vercel、typesafe 或 custom。
每個供應商區塊（sttEndpoints.*、organizer.endpoints.*）也接受 timeoutMs、headers，以及 Azure 用的 apiVersion。

Ferret 絕不會代你支付 AI 費用。沒有內建金鑰，也沒有中繼伺服器：每個請求都是用你的金鑰，從你的電腦直接送到你設定的端點。

#任何供應商：自訂端點

預設組合只會預先填入 URL 與模型。每個連線（轉錄、整理意見、判定模型）也接受任何 URL、模型、標頭與驗證方式，因此你可以使用任何供應商：Cloudflare、閘道、公司的代理伺服器或你自己的伺服器。下列欄位在三者中的名稱與結構都相同。

欄位	意義
`baseUrl`, `model`	任何 http(s) URL 與模型名稱。URL 中的 `{account_id}` 會被替換為 `accountId`，或 `CLOUDFLARE_ACCOUNT_ID` 環境變數的值
`authScheme`	`bearer`（`Authorization: Bearer <key>`）、`header`（金鑰放在 `authHeader` 指定名稱的標頭中）或 `none`。省略時沿用供應商的預設值
`headers`	額外的標頭。值可以是一般字串，或用 `{"env": "VAR"}` 從環境變數讀取（查找方式與 `apiKeyEnv` 相同）。`Authorization` 或閘道權杖等機密標頭只接受 `{"env": …}` 形式。在設定頁面中請寫成 `Name: ${VAR}`
`apiKey` / `apiKeyEnv`	金鑰，請參閱 API 金鑰

轉錄：使用任何相容 OpenAI 的 /v1/audio/transcriptions 伺服器，且該伺服器要求把金鑰放在 api-key 標頭中：

"capture": {
  "transcription": "compatible",
  "sttEndpoints": {
    "compatible": {
      "baseUrl": "https://stt.internal.example.com/v1",
      "model": "whisper-large-v3",
      "authScheme": "header",
      "authHeader": "api-key",
      "apiKeyEnv": "INTERNAL_STT_KEY",
      "headers": { "X-Team": "design" }
    }
  }
}

整理意見：使用 Cloudflare Workers AI（相容 OpenAI 的 chat completions），也可以選擇經由 AI Gateway：

"organizer": {
  "runner": "api:compatible",
  "endpoints": {
    "compatible": {
      "baseUrl": "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1",
      "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
      "apiKeyEnv": "CLOUDFLARE_API_TOKEN",
      "headers": { "cf-aig-authorization": { "env": "CF_AIG_TOKEN" } }
    }
  }
}

判定模型：在 Cloudflare Workers AI 上使用（Clef Flash），或以 "preset": "custom" 使用任何支援 System One API 的伺服器。判定模型在 endpoint 中接受完整的請求 URL（會填入 {account_id} 與 {model}）；其他欄位的名稱與結構都與上面相同：

"decision": {
  "enabled": true,
  "preset": "cloudflare",
  "endpoint": "https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}",
  "model": "clef-flash",
  "authScheme": "bearer",
  "apiKeyEnv": "CLOUDFLARE_API_TOKEN",
  "headers": { "cf-aig-authorization": { "env": "CF_AIG_TOKEN" } }
}

請把 CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_API_TOKEN 及其他變數放在 ~/.ferret/.env 中。上面的模型名稱只是範例，請查看你的供應商的模型清單。

#API 金鑰

每個供應商區塊可用以下三種方式之一接受金鑰，以最先找到的為準：

"apiKey": "…"：以明文寫在 settings.json 中的金鑰。任何能讀取該檔案的人都能讀到金鑰，且只要存在這種金鑰，設定就會顯示警告。請避免使用，尤其當檔案放在 dotfiles 儲存庫中時。
"apiKeyEnv": "OPENAI_API_KEY"：環境變數的名稱。Ferret 會依序查找自己的環境、目前開啟專案的 .env，然後是 ~/.ferret/.env。從 Finder 或「開始」功能表開啟的 App 看不到你在 shell 設定檔中 export 的變數，因此 ~/.ferret/.env 是最可靠的位置。
在設定中儲存的金鑰：以作業系統的鑰匙圈加密，存放在 <userData>/stt-keys.bin（請參閱金鑰的存放位置）。

只有當你在 apiKeyEnv 中指定環境變數名稱時，Ferret 才會讀取它。金鑰絕不會寫入記錄、絕不會顯示在 UI 上，也絕不會包含在當機報告中。

#即時重新載入

編輯 settings.json：App 會在執行中套用變更。

Ferret 會監看 settings.json。檔案變更時，App 會重新讀取、依 Schema 檢查並套用：主題、語言、版面配置、Agent、專案與 AI 端點都會更新，不需重新啟動，設定頁面也會重新整理。

如果檔案有 JSON 語法錯誤或型別錯誤的值，該次編輯的內容都不會套用。App 會保留最後一份有效的設定，顯示錯誤及其行號，並在你修正之前不會覆寫你的檔案。
當 App 自己儲存時（你在設定中變更了某些項目），會先寫入暫存檔，再以重新命名的方式取代 settings.json，因此即使當機也不會留下寫到一半的檔案。

#讓你的程式設計 Agent 設定 Ferret

把以下內容貼到 Claude Code、Codex 或任何能編輯檔案的 Agent 中：

Edit ~/.ferret/settings.json following the JSON Schema in
~/.ferret/settings.schema.json (read the field descriptions first).
Keep unknown keys and keep the file valid JSON. Never write API keys in
plaintext: set "apiKeyEnv" to an environment variable name instead and
tell me which variable to put in ~/.ferret/.env.
Ferret applies the change as soon as the file is saved.

Task: <what you want, e.g. "use my Ollama at http://localhost:11434 with
qwen3:14b for Organize findings and add a prd URL for the shop project">

同樣的提示詞（已填入你實際的路徑）位於設定 → 讓你的程式設計 Agent 設定 Ferret，並附有複製提示詞按鈕。

在 GitHub 上協助翻譯此頁（在新分頁中開啟）