Escopos e confiança no workspace
Escolha configurações para todos os seus projetos ou apenas um e revise o código fornecido pelo repositório.
Escolha o escopo útil mais restrito
O Clarvis separa padrões pessoais de comportamentos específicos do projeto:
| Escopo | Local padrão | Use para |
|---|---|---|
| Global | ~/.clarvis/ | Seus provedores, padrões, agentes, skills, workflows, plugins, Extension Profiles e configurações |
| Workspace | <project>/.clarvis/ | Sobrescritas, definições de Extension Profile e extensões que devem acompanhar um repositório |
Se CLARVIS_HOME estiver definida, ela substitui ~/.clarvis para arquivos pessoais pertencentes ao Clarvis. Ela não move o diretório .clarvis do workspace nem os diretórios interoperáveis .agents.
Use o controle de escopo exibido em uma tela de configurações antes de salvar. Prefira o escopo global para credenciais e padrões pessoais. Prefira o escopo do workspace somente quando os colaboradores precisarem receber o mesmo comportamento do projeto.
Entenda a precedência
A configuração efetiva começa com os padrões do produto, depois aplica a configuração pessoal e, por fim, a configuração do workspace. Normalmente, um valor do workspace vence para a mesma escolha escalar. Mapas e listas ordenadas podem ser combinados de acordo com as regras de cada campo; as telas de configuração mostram o valor efetivo e sua origem quando essa distinção é relevante.
O mesmo padrão se aplica ao conteúdo criado pelo usuário:
- um agente do workspace sobrescreve um agente pessoal com o mesmo nome;
- uma skill Clarvis do workspace sobrescreve skills pessoais e interoperáveis com o mesmo nome;
- tanto
builtin:defaultquanto Extension Profiles personalizados resolvem plugins por escopo, origem de sistema de arquivos e nome exatos; uma instalação de mesmo nome nunca substitui outra; - as configurações do operador ainda têm precedência sobre toda contribuição de plugin.
Definições globais e de workspace de Extension Profile são conteúdo criado pelo usuário. O padrão global ativo e a seleção por workspace são estado local da máquina; versionar uma definição de workspace não a ativa para quem clonar o repositório.
Controles alterados para a próxima execução não reescrevem uma execução já ativa. Verifique o escopo e o cabeçalho antes de iniciar trabalho ao alternar entre repositórios.
Revise a confiança no workspace
Um repositório clonado não deve obter autoridade apenas por conter configuração. O Clarvis calcula um fingerprint do caminho do workspace, das partes de sua configuração capazes de executar código, selecionar um provedor executável ou alterar as instruções de sistema de um agente e do inventário completo de plugins do workspace pertencentes ao repositório, antes da seleção do Extension Profile.
Quando esse conteúdo protegido é novo ou muda, o Clarvis pede que você aprove seu fingerprint: um identificador daquele conteúdo exato. A aprovação libera o uso em futuras execuções. Recusar abre Extensions para remover itens indesejados. Use /workspace-trust depois para revisar ou revogar a aprovação. Se o repositório não declarar nenhum conteúdo protegido, não há o que aprovar.
Aprovar e revogar são recusados enquanto uma execução estiver ativa, antes de o registro de confiança mudar. Quando não há execução ativa, qualquer uma dessas decisões faz o Clarvis recompor o Extension Profile de workspace selecionado, incluindo a superfície de plugins de builtin:default derivada do workspace, antes da próxima execução.
Até a aprovação, o Clarvis retém estas contribuições do workspace e continua usando a configuração pessoal confiável:
- hooks e servidores MCP;
- ativação builtin de plugins, fontes de marketplace e todos os plugins do workspace pertencentes ao repositório;
- provedores executáveis ou de plugin para Memory e Plans;
- um provedor de Tasks;
- arquivos de agentes do workspace.
Declarações de provedores baseados em assinatura são uma exceção mais forte: arquivos do workspace nunca recebem a capacidade de reutilizar ou redirecionar suas credenciais pessoais de assinatura, mesmo após a aprovação do workspace. Configure provedores de assinatura globalmente.
A aprovação é intencionalmente específica ao conteúdo. Ela não seleciona um plugin ausente do Extension Profile ativo, e hooks de plugins continuam sendo ativados e removidos junto com o plugin selecionado. Plugins globais pertencem ao operador e não exigem aprovação adicional do workspace. Uma aprovação cobre o inventário completo e exato de plugins do workspace ao trocar de Extension Profile; adicionar ou alterar a superfície de contribuições de um plugin do repositório incluída no fingerprint exige nova revisão.
A confiança não é uma revisão de cada configuração
A confiança no workspace protege a superfície executável e de seleção de provedores descrita acima. Outras configurações do projeto ainda participam da precedência normal. Em especial, revise você mesmo as configurações de sandbox e de revisão de comandos do workspace; elas não se tornam seguras apenas porque o comando de confiança informa que o workspace é inerte.
Mantenha os segredos pessoais
Não faça commit de credenciais nas configurações do workspace. Configure credenciais de provedores em /settings/providers ou referencie variáveis de ambiente quando um formato aceitar ${NAME}. Aprovar o workspace nunca transforma um arquivo do repositório em um local adequado para segredos.
Use /storage para verificar se os arquivos de credenciais do Clarvis estão presentes e qual é a permissões, sem revelar caminhos, tamanhos ou conteúdo. Em POSIX, o Clarvis aplica bits de modo exclusivos do proprietário; no Windows, depende dos controles de acesso do perfil do usuário.