Configurações da CLI (config.json)

Cada campo do config.json: como a CLI do openspec se comporta na sua máquina.

Localização

A CLI mantém suas configurações de nível de máquina em ~/.config/openspec/config.json no macOS e Linux, e em %APPDATA%\openspec\config.json no Windows. $XDG_CONFIG_HOME tem precedência em todas as plataformas quando definido. O comando openspec config lê e edita esse arquivo.

Campos

Chave	Tipo	Obrigatório	Efeito
profile	string: core ou custom	Não	Escolhe o conjunto de workflows que o openspec init instala
delivery	string: both, skills ou commands	Não	Define se o init instala skills, slash commands ou ambos
workflows	lista de strings	Não	A lista de workflows que um perfil custom instala
featureFlags	mapa: flag → boolean	Não	Alternadores booleanos de funcionalidades
defaultStore	string	Não	Store de fallback de nível de máquina para resolução de root
openers	mapa: id da ferramenta → configurações	Não	As ferramentas nas quais os worksets abrem, e como cada uma é iniciada
telemetry	mapa	Não	Opt-out de telemetria, id anônimo e estado de aviso visto

profile

Qual conjunto de workflows o openspec init instala. O padrão é core: propose, explore, apply, update, sync e archive. Definir custom instala exatamente a lista workflows.

delivery

Define se o init instala workflows como skills, como slash commands ou ambos. O padrão é both.

workflows

Os workflows que um perfil custom instala; ignorado quando o perfil é core. Ids válidos: propose, explore, new, continue, apply, update, ff, sync, archive, bulk-archive, verify, onboard.

featureFlags

Alternadores booleanos indexados pelo nome da flag, definidos com openspec config set featureFlags.<flag> true. Nenhuma flag é lida pela CLI atualmente.

defaultStore

O id do store de fallback de nível de máquina para resolução de root, consultado apenas quando nenhuma flag --store, openspec/ local ou ponteiro store: do projeto é resolvido. A hierarquia completa está em Resolução de root.

openers

As ferramentas nas quais um workset pode abrir, indexadas pelo id da ferramenta. Edite openers no config.json global com openspec config edit no seu terminal.

Campo	Contrato
style	workspace-file ou attach-dirs. Obrigatório para uma nova ferramenta; opcional para uma ferramenta integrada.
label	String não vazia exibida no seletor de ferramentas. O padrão é o id para uma nova ferramenta.
command	Nome ou caminho de executável não vazio. O padrão é o id para uma nova ferramenta. Coloque argumentos em args, não nesta string.
args	Array de strings passado antes do arquivo de workspace ou das flags de attach. O padrão é [] para uma nova ferramenta.
attach_flag	String não vazia associada a cada caminho de membro para attach-dirs. O padrão é --add-dir para uma nova ferramenta. Ignorado para workspace-file.

Substituições de ferramentas integradas: code, cursor, claude e codex mantêm quaisquer campos que você omitir. Definir args substitui toda a lista de argumentos; [] a limpa.

Estilos de inicialização: workspace-file passa o caminho .code-workspace gerado para o executável. attach-dirs passa um par flag/caminho por membro, incluindo o membro primário.

Disponibilidade: os openers attach-dirs, incluindo Claude Code e Codex, ficam desabilitados por padrão. Você não pode selecioná-los ou salvá-los com --tool, e o OpenSpec se recusa a abrir um workset que já os nomeie. Substituições de configuração não habilitam o estilo de inicialização attach-dirs.

Validação: campos desconhecidos, tipos inválidos e uma nova ferramenta sem style falham quando um comando de workset lê a tabela de openers.

Este exemplo adiciona o VS Code Insiders e passa --new-window sempre que o opener integrado do VS Code é iniciado:

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

O executável code-insiders ou code correspondente deve estar instalado e disponível no PATH.

telemetry

A CLI armazena seu id anônimo e se o aviso de primeira execução foi exibido. Defina telemetry.enabled como false para desabilitar a telemetria. Você também pode fazer opt-out com OPENSPEC_TELEMETRY=0 ou DO_NOT_TRACK=1 no seu ambiente.

Exemplo

Um config.json preenchido:

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