Cấu hình bằng settings.json

#Vị trí của tệp

Đường dẫn giống nhau trên mọi hệ điều hành:

~/.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

• Đặt FERRET_CONFIG_DIR (tên cũ MOVIE_ADE_CONFIG_DIR vẫn dùng được) để dùng một thư mục khác, ví dụ một thư mục trong repo dotfiles. ~ sẽ được mở rộng.
• Bản build phát triển (pnpm dev) dùng ~/.ferret/dev/, nên việc phát triển Ferret không bao giờ ghi đè cài đặt thật của bạn.
• Nâng cấp từ 0.1.0: ở lần khởi động đầu tiên, tệp cũ <userData>/settings.json được sao chép sang các tệp mới. Tệp cũ được giữ nguyên chỗ làm bản sao lưu và không bao giờ bị sửa.

Nâng cấp từ MOVIE-ADE: ở lần khởi động đầu tiên, settings.json, state.json, usage/ và .env được sao chép từ ~/.movie-ade/ sang ~/.ferret/. Thư mục cũ được giữ nguyên và không bị sửa.

Trong ứng dụng, phần đầu trang Cài đặt hiển thị đường dẫn, cùng nút Mở settings.json (sửa trong editor tích hợp có gợi ý theo schema) và Hiện trong thư mục.

#Schema và kiểm tra hợp lệ

Dòng đầu tiên của settings.json là "$schema": "./settings.schema.json". Các editor như VS Code và các agent như Claude Code dùng nó để gợi ý, kiểm tra hợp lệ và hiển thị mô tả của từng trường. Schema đi kèm trong ứng dụng và được ghi ra cạnh tệp mỗi lần khởi động, nên luôn khớp với phiên bản đã cài.

Các key mà Ferret không biết được giữ nguyên khi ứng dụng lưu. Các tab đang mở, URL gần nhất và trạng thái phiên khác được lưu trong state.json, không phải ở đây.

#Ví dụ có chú thích

JSON không có chú thích, nên phần giải thích nằm bên dưới ví dụ. Mọi trường đều không bắt buộc; bỏ qua những gì bạn không cần.

{
  "$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: các mục tiêu review cho menu URL. URL đầu tiên được mở khi mở dự án. id có thể là bất kỳ chuỗi duy nhất nào.
• agents.customAgents: bất kỳ CLI hay script wrapper nào. startupAgents liệt kê theo thứ tự các tab agent được mở cùng dự án.
• capture.sttEndpoints.compatible: bất kỳ server nào triển khai /v1/audio/transcriptions của OpenAI (speaches, vLLM, LocalAI…). costLimitUsd: null tắt giới hạn chi phí, hợp lý khi dùng GPU của chính bạn. Xem Chuyển văn bản và chi phí.
• organizer: Sắp xếp góp ý được gửi thẳng tới một server /v1/chat/completions tương thích OpenAI (ở đây là Ollama). Dùng "runner": "claude-code" hoặc "codex" để dùng thông tin đăng nhập CLI của bạn thay vào đó, và organizer.cliModels để chọn model của chúng.
• decision: model kiểm tra xem từng góp ý đã được sửa hay chưa. Clef Flash trên Ollama cục bộ thì miễn phí và đọc được ảnh chụp màn hình. preset cũng có thể là cloudflare, vercel, typesafe hoặc custom.
• Mọi khối provider (sttEndpoints.*, organizer.endpoints.*) cũng nhận timeoutMs, headers và, với Azure, apiVersion.

#Mọi provider: endpoint tùy chỉnh

Preset chỉ điền sẵn URL và model. Mọi kết nối (chuyển văn bản, Sắp xếp góp ý, model quyết định) đều nhận bất kỳ URL, model, header và cách xác thực nào, nên bạn có thể dùng bất kỳ provider nào: Cloudflare, một gateway, proxy của công ty hay server của riêng bạn. Các trường dưới đây có cùng tên và cấu trúc ở cả ba.

Chuyển văn bản với bất kỳ server /v1/audio/transcriptions tương thích OpenAI nào yêu cầu key trong header 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" }
    }
  }
}

Sắp xếp góp ý với Cloudflare Workers AI (chat completions tương thích OpenAI), có thể đi qua 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" } }
    }
  }
}

Model quyết định trên Cloudflare Workers AI (Clef Flash), hoặc với "preset": "custom" trên bất kỳ server nào dùng System One API. Model quyết định nhận URL request đầy đủ trong endpoint (đã điền {account_id} và {model}); mọi trường khác có cùng tên và cấu trúc như trên:

"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" } }
}

Đặt CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN và các biến khác trong ~/.ferret/.env. Tên model ở trên chỉ là ví dụ. Hãy kiểm tra danh sách model của provider bạn dùng.

#API key

Mỗi khối provider nhận key theo một trong ba cách. Cách nào được tìm thấy trước sẽ được dùng:

1. "apiKey": "…": key dạng văn bản thuần trong settings.json. Ai đọc được tệp cũng đọc được key, và Cài đặt hiển thị cảnh báo khi có key như vậy. Hãy tránh cách này, nhất là khi tệp nằm trong repo dotfiles.
2. "apiKeyEnv": "OPENAI_API_KEY": tên một biến môi trường. Ferret tìm trong môi trường của chính nó, rồi đến .env của dự án đang mở, rồi ~/.ferret/.env. Ứng dụng mở từ Finder hoặc menu Start không thấy các biến được export trong shell profile, nên ~/.ferret/.env là nơi đáng tin cậy.
3. Key được lưu trong Cài đặt: được mã hóa bằng keychain của hệ điều hành trong <userData>/stt-keys.bin (xem Nơi lưu key).

Ferret chỉ đọc một biến môi trường khi bạn ghi tên nó trong apiKeyEnv. Key không bao giờ được ghi log, không bao giờ hiển thị trên giao diện và không bao giờ có trong báo cáo crash.

#Tải lại tức thì

Ferret theo dõi settings.json. Khi tệp thay đổi, ứng dụng đọc lại, kiểm tra theo schema rồi áp dụng: chủ đề, ngôn ngữ, bố cục, agent, dự án và endpoint AI được cập nhật mà không cần khởi động lại, và trang Cài đặt được làm mới.

• Nếu tệp có lỗi cú pháp JSON hoặc một giá trị sai kiểu, không thay đổi nào từ lần sửa đó được áp dụng. Ứng dụng giữ cài đặt hợp lệ gần nhất, hiển thị lỗi kèm số dòng, và không ghi đè tệp của bạn cho đến khi bạn sửa xong.
• Khi chính ứng dụng lưu (bạn thay đổi gì đó trong Cài đặt), nó ghi vào một tệp tạm rồi đổi tên đè lên settings.json, nên một lần crash không bao giờ để lại tệp ghi dở.

#Để coding agent cấu hình Ferret

Dán đoạn này vào Claude Code, Codex hoặc bất kỳ agent nào có thể sửa tệp:

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">

Cùng prompt này, với đường dẫn thật của bạn đã được điền sẵn, có trong Cài đặt → Để coding agent cấu hình Ferret với nút Sao chép prompt.