配置

使用 settings.json 配置

Ferret 的所有设置都保存在一个 JSON 文件中，旁边附有 JSON Schema，因此你或你的编码 Agent（例如 Claude Code、Codex 或 Gemini CLI）可以通过编辑文件来配置应用。更改会在应用运行时生效。

#文件位置

路径在所有操作系统上都相同：

~/.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/。旧文件夹保留原处，不会被修改。

在应用中，设置顶部会显示该路径，并提供打开 settings.json（在内置编辑器中编辑，带有基于 Schema 的补全）和在文件夹中显示。

#Schema 与校验

settings.json 的第一行是 "$schema": "./settings.schema.json"。VS Code 等编辑器和 Claude Code 等 Agent 会利用它进行补全、校验，并显示每个字段的说明。Schema 随应用一起发布，每次启动时都会写到该文件旁边，因此它始终与已安装的版本一致。

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 中查找。从访达或开始菜单打开的应用看不到你在 shell 配置文件中 export 的变量，因此 ~/.ferret/.env 是最可靠的位置。
保存在设置中的密钥：使用操作系统钥匙串加密，保存在 <userData>/stt-keys.bin 中（参见密钥的存储位置）。

只有当你在 apiKeyEnv 中指定了某个环境变量的名称时，Ferret 才会读取它。密钥永远不会被写入日志、不会在界面中显示，也不会包含在崩溃报告中。

#实时重新载入

编辑 settings.json：应用在运行时即应用更改。

Ferret 会监视 settings.json。文件发生变化时，应用会重新读取它，按 Schema 校验后应用：主题、语言、布局、Agent、项目和 AI 端点都会在不重启的情况下更新，设置页面也会刷新。

如果文件存在 JSON 语法错误或类型错误的值，这次编辑的任何内容都不会被应用。应用会保留上一次有效的设置，显示错误及其行号，并且在你修复之前不会覆盖你的文件。
当应用自己保存时（你在设置中做了更改），它会先写入临时文件，再将其重命名覆盖 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 上帮助翻译此页（在新标签页中打开）