Cấu hình CLI (config.json)

Mỗi trường trong config.json mô tả cách CLI hoạt động trên máy của bạn.

Vị trí

CLI lưu trữ các cài đặt ở cấp máy tại ~/.config/openspec/config.json trên macOS và Linux, và %APPDATA%\openspec\config.json trên Windows. $XDG_CONFIG_HOME sẽ chiếm ưu tiên trên mọi nền tảng khi được thiết lập. Lệnh openspec config đọc và chỉnh sửa nó.

Các trường

Key	Type	Required	Hiệu ứng
profile	string: core hoặc custom	Không	Chọn bộ công cụ workflow mà openspec init cài đặt
delivery	string: both, skills, hoặc commands	Không	Liệu init có cài đặt skills, slash commands, hay cả hai không
workflows	danh sách chuỗi	Không	Danh sách workflow mà profile custom cài đặt
featureFlags	map: cờ → boolean	Không	Cờ tính năng Boolean
defaultStore	string	Không	Cửa hàng lưu trữ fallback ở cấp máy cho giải quyết gốc
openers	map: id công cụ → cài đặt	Không	Các công cụ workset có thể mở trong, và cách mỗi công cụ được khởi động
telemetry	map	Không	Tùy chọn telemetry, ID ẩn danh, và trạng thái đã thấy thông báo

profile

Bộ công cụ workflow mà openspec init cài đặt. Mặc định là core: propose, explore, apply, update, sync, và archive. Cài đặt custom sẽ cài đặt chính xác danh sách workflows thay vào đó.

delivery

Liệu init có cài đặt workflow dưới dạng skills, slash commands, hay cả hai không. Mặc định là both.

workflows

Các workflow mà profile custom cài đặt; bị bỏ qua khi profile là core. ID hợp lệ: propose, explore, new, continue, apply, update, ff, sync, archive, bulk-archive, verify, onboard.

featureFlags

Cờ tính năng Boolean được chỉ định bằng tên cờ, được đặt với openspec config set featureFlags.<flag> true. Hiện tại không có cờ nào được CLI đọc.

defaultStore

ID cửa hàng lưu trữ fallback ở cấp máy cho giải quyết gốc, được tham khảo chỉ khi không có cờ --store, đường dẫn openspec/ cục bộ, hoặc con trỏ store: của dự án được giải quyết. Cả chuỗi đầy đủ là Root resolution.

openers

Công cụ mà workset có thể mở trong, được chỉ định bằng tool id. Chỉnh sửa openers trong config.json toàn cục bằng lệnh openspec config edit trong terminal của bạn.

Trường	Hợp đồng
style	workspace-file hoặc attach-dirs. Bắt buộc cho công cụ mới; tùy ý cho công cụ có sẵn.
label	Chuỗi không rỗng hiển thị trong công cụ chọn. Mặc định là id cho công cụ mới.
command	Tên thực thi hoặc đường dẫn không rỗng. Mặc định là id cho công cụ mới. Đặt các argument trong args, không phải trong chuỗi này.
args	Mảng các chuỗi được truyền trước file workspace hoặc cờ attach. Mặc định là [] cho công cụ mới.
attach_flag	Chuỗi không rỗng được ghép với mỗi đường dẫn thành viên cho attach-dirs. Mặc định là --add-dir cho công cụ mới. Bỏ qua cho workspace-file.

Sự vượt qua mặc định: code, cursor, claude, và codex giữ lại bất kỳ trường nào bạn bỏ qua. Đặt args sẽ thay thế toàn bộ danh sách argument; [] xóa nó.

Phong cách khởi động: workspace-file truyền đường dẫn .code-workspace đã tạo đến thực thi. attach-dirs truyền một cặp flag/đường dẫn cho mỗi thành viên, bao gồm thành viên chính.

Tính khả dụng: Các openers attach-dirs, bao gồm Claude Code và Codex, bị tắt theo mặc định. Bạn không thể chọn hoặc lưu chúng với --tool, và OpenSpec từ chối mở một workset đã có tên một trong số chúng. Các sự vượt qua cấu hình không kích hoạt phong cách khởi động attach-dirs.

Xác thực: các trường không biết, kiểu dữ liệu không hợp lệ, và một công cụ mới không có style sẽ thất bại khi một lệnh workset đọc bảng openers.

Ví dụ này thêm VS Code Insiders và truyền --new-window bất cứ khi nào công cụ mở VS Code có sẵn được khởi động:

{
  "openers": {
    "code-insiders": {
      "style": "workspace-file",
      "label": "VS Code Insiders"
    },
    "code": {
      "args": ["--new-window"]
    }
  }
}

Công cụ thực thi tương ứng code-insiders hoặc code phải được cài đặt và có sẵn trên PATH.

telemetry

CLI lưu trữ ID ẩn danh của bạn và xem thông báo lần đầu được hiển thị. Đặt telemetry.enabled thành false để tắt telemetry. Bạn cũng có thể từ chối bằng OPENSPEC_TELEMETRY=0 hoặc DO_NOT_TRACK=1 trong môi trường của bạn.

Ví dụ

Một config.json đã điền đầy đủ:

{
  "profile": "core",
  "delivery": "both",
  "featureFlags": {},
  "telemetry": {
    "anonymousId": "5f8a2c1e-4b6d-4f9a-9c3d-7e1b2a8d4c6f",
    "noticeSeen": true
  }
}