Claude Code: como reconfigurar um plugin instalado sem o reinstalar (2.1.285)

Este guia destina-se a utilizadores que já têm instalado um plugin do Claude Code que declara definições userConfig, como um endereço, um token ou um caminho de pasta. Precisa de corrigir um valor introduzido incorretamente ou de substituir um token sem reinstalar o plugin. Tudo o que se segue baseia-se na documentação e no registo de alterações oficiais do Claude Code. O artigo não inclui um teste original.

Pode encontrar informações sobre como utilizar o Ailoot na documentação.

O que foi acrescentado na versão 2.1.285#

A entrada do Claude Code no registo de alterações da versão 2.1.285 (um commit datado de 29 de setembro de 2026) contém várias linhas sobre plugins. Duas delas são relevantes para este artigo:

Adicionado claude plugin configure <plugin> para mostrar as opções de um plugin e quais não estão configuradas, ou guardar novos valores lidos de stdin com --values-stdin

Isto significa que o novo comando claude plugin configure <plugin> mostra as definições de um plugin e quais não estão configuradas, ou guarda novos valores lidos da entrada padrão quando utilizado com --values-stdin.

Adicionado <server>.<key>=<value> a claude plugin install --config, para que as definições próprias de um servidor MCP incluído num .mcpb possam ser configuradas durante a instalação e este arranque sem visitar /plugin → Configure

Isto significa que claude plugin install --config passou a suportar o formato <server>.<key>=<value>, permitindo fornecer durante a instalação as definições de um servidor MCP incluído num plugin num ficheiro .mcpb, para que o servidor arranque sem visitar /plugin → Configure.

A referência dos comandos confirma o requisito de versão: claude plugin configure requer o Claude Code v2.1.285 ou posterior. O comando não existe nas versões anteriores.

Em que difere de /plugin configure#

O comando /plugin configure <plugin> (com o alias config) já estava disponível numa sessão interativa do Claude Code. Abre uma caixa de diálogo para as definições userConfig e requer a versão v2.1.147 ou posterior. No entanto, /plugin só funciona numa sessão interativa: numa execução não interativa, como claude -p, o Claude Code responde que /plugin não está disponível nesse ambiente.

Segundo a documentação, os comandos claude plugin são executados numa shell ou num script, fora de uma sessão do Claude Code. Também pode executar claude plugin configure sem abrir uma caixa de diálogo. A documentação não descreve como este comando se comporta sem um terminal interativo nem onde guarda valores secretos num servidor sem ambiente gráfico. Verifique isso no seu próprio ambiente antes de o utilizar em CI.

Passo 1. Veja quais as definições configuradas#

A documentação exige o identificador completo do plugin no formato name@marketplace, tal como apresentado por claude plugin list. O comando configure não aceita um nome sem @marketplace.

claude plugin list
claude plugin configure formatter@my-marketplace

Substitua formatter@my-marketplace pelo identificador do seu plugin. Sem opções, o comando apresenta cada definição com as etiquetas: required ou optional, depois sensitive para um campo secreto, seguido de set ou not set. Não apresenta os valores guardados.

Se precisar de uma saída legível por máquina, adicione --json. A saída incluirá então os valores guardados dos campos normais, mas o conteúdo de um campo secreto nunca é apresentado.

Passo 2. Altere um valor utilizando um ficheiro#

Os valores são fornecidos como um objeto JSON, em que cada chave é o nome de uma definição do manifesto e cada valor é uma cadeia de caracteres sem quebras de linha. A documentação apresenta um método baseado num ficheiro: escreva o objeto em values.json e passe esse ficheiro à entrada padrão do comando. Neste caso, api_url é a chave utilizada no exemplo da documentação. Para o seu próprio plugin, utilize o nome da definição de que precisa, indicado no respetivo manifesto ou na saída do passo 1.

{"api_url": "NEW_ADDRESS"}

claude plugin configure formatter@my-marketplace --values-stdin < values.json

Ao guardar, aplicam-se as seguintes regras:

• As definições omitidas do JSON mantêm os valores anteriores. Pode fornecer apenas o campo que está a alterar.
• A descrição da opção refere-se à configuração de valores em geral e não indica uma regra separada para campos secretos. Depois de guardar, utilize o passo 1 para verificar se o campo relevante está marcado como set.
• O Claude Code verifica cada valor em função do tipo declarado e apresenta Configuration saved. Restart Claude Code to apply it. Isto significa que a definição foi guardada e terá efeito depois de reiniciar o Claude Code.
• Se o JSON contiver uma chave não declarada no manifesto ou um valor que não passe a validação, o comando não guarda nada, apresenta Failed to save configuration: seguido do motivo e termina com o código 1.

Se escrever um token em values.json, lembre-se de que se trata de um ficheiro normal no disco. Apague-o depois de guardar a configuração e não o adicione ao repositório.

Onde o valor é guardado#

Segundo a documentação do manifesto do plugin, os valores normais são guardados em pluginConfigs, no ficheiro settings.json do utilizador. Os valores dos campos marcados com sensitive: true são guardados no arquivo seguro de credenciais do sistema, em vez de em settings.json; a entrada destes campos é ocultada.

Não vale a pena procurar o valor de um campo secreto em settings.json. claude plugin configure mostra o respetivo estado com as etiquetas sensitive e set ou not set.

install --config: definir um valor durante a instalação#

Para uma nova instalação, claude plugin install disponibiliza a opção --config <key=value>. Esta define uma configuração userConfig declarada no manifesto e requer a versão v2.1.147 ou posterior. Repita a opção para cada definição. A partir da versão 2.1.285, uma chave no formato <server>.<key> define uma configuração de um servidor MCP incluído, declarada no próprio user_config desse servidor.

No exemplo abaixo, substitua formatter@my-marketplace pelo identificador do seu plugin, api_url pelo nome da definição do respetivo manifesto e todo o marcador de posição NEW_ADDRESS pelo seu próprio valor. Mantenha as aspas à volta do argumento.

claude plugin install formatter@my-marketplace --config 'api_url=NEW_ADDRESS'

O comando a utilizar depende de o plugin estar instalado: install --config define valores durante a instalação inicial, enquanto plugin configure --values-stdin altera valores de um plugin já instalado.

Para definições pertencentes a um servidor MCP incluído, a documentação indica outros métodos: plugin install --config ou Configure em /plugin. Não sugere o comando plugin configure para essas definições.

Se o comando não encontrar o plugin#

Se claude plugin configure não conseguir encontrar um plugin carregado com esse identificador, apresenta No installed plugin has the id "<plugin>". e termina com o código 1. Primeiro, confirme que forneceu o identificador completo name@marketplace apresentado por claude plugin list. O nome do plugin, por si só, não é suficiente.

O comando na sessão tem a sua própria mensagem. Se indicar um plugin que não está instalado no projeto atual ao utilizar /plugin enable, disable, uninstall ou configure, o Claude Code apresenta Plugin "<plugin>" is not installed in this project e não faz nada.

Conclusão#

Para alterar um token ou endereço de um plugin já instalado no Claude Code 2.1.285 ou posterior, encontre o respetivo identificador com claude plugin list, verifique o estado das definições com claude plugin configure, forneça o novo valor a partir de um ficheiro com --values-stdin e reinicie o Claude Code. Os valores dos campos secretos não são guardados em settings.json, pelo que deve verificar o respetivo estado com o mesmo comando.

O guia sobre Skills, Subagents, MCP e Plugins no Claude Code pode ajudar a escolher entre tipos de extensão. Se ainda não escolheu um plugin, pode começar pelos 10 melhores plugins para Claude Code. Existe um guia separado para um bot do Telegram: instalar um plugin num agente do Telegram funciona de forma diferente de instalar um no Claude Code.

Conheça o Ailoot.