Claude Code: 설치된 플러그인을 재설치하지 않고 재구성하는 방법 (2.1.285)

이 가이드는 주소, 토큰 또는 폴더 경로와 같은 userConfig 설정을 선언하는 Claude Code 플러그인을 이미 설치한 사용자를 위한 것입니다. 잘못 입력한 값을 수정하거나 플러그인을 재설치하지 않고 토큰을 교체해야 할 수 있습니다. 아래 내용은 모두 Claude Code 공식 문서와 변경 기록을 바탕으로 합니다. 이 글에는 자체 테스트 실행 결과가 포함되어 있지 않습니다.

Ailoot 사용 방법은 문서에서 확인할 수 있습니다.

버전 2.1.285에 추가된 기능#

Claude Code 버전 2.1.285 변경 기록 항목(2026년 9월 29일자 커밋)에는 플러그인에 관한 몇 가지 내용이 있습니다. 그중 두 가지가 이 글과 관련이 있습니다.

Added claude plugin configure <plugin> to show a plugin's options and which are unset, or save new values read from stdin with --values-stdin

즉, 새 명령 claude plugin configure <plugin>은 플러그인 설정과 설정되지 않은 항목을 보여주거나, --values-stdin과 함께 사용하면 표준 입력에서 읽은 새 값을 저장합니다.

Added <server>.<key>=<value> to claude plugin install --config, so a bundled .mcpb MCP server's own settings can be set at install time and it starts without visiting /plugin → Configure

즉, 이제 claude plugin install --config에서 <server>.<key>=<value> 형식을 지원합니다. 따라서 .mcpb 파일의 플러그인에 포함된 MCP 서버의 설정을 설치 시 제공할 수 있으며, /plugin → Configure를 거치지 않고 서버를 시작할 수 있습니다.

명령어 참조 문서에서 필요한 버전을 확인할 수 있습니다. claude plugin configure를 사용하려면 Claude Code v2.1.285 이상이 필요합니다. 이전 버전에는 이 명령이 없습니다.

/plugin configure와의 차이점#

/plugin configure <plugin> 명령(별칭 config)은 대화형 Claude Code 세션에서 이미 사용할 수 있었습니다. 이 명령은 userConfig 설정을 위한 대화상자를 열며 v2.1.147 이상이 필요합니다. 그러나 /plugin은 대화형 세션에서만 작동합니다. claude -p와 같은 비대화형 호출에서는 Claude Code가 해당 환경에서 /plugin을 사용할 수 없다고 응답합니다.

문서에 따르면 claude plugin 명령은 Claude Code 세션 밖에서 셸이나 스크립트로 실행합니다. 따라서 대화상자를 열지 않고도 claude plugin configure를 실행할 수 있습니다. 대화형 터미널 없이 이 명령을 실행했을 때의 동작이나 그래픽 환경이 없는 서버에서 비밀 값을 저장하는 위치는 문서에 설명되어 있지 않습니다. CI에서 사용하기 전에 직접 사용하는 환경에서 확인하세요.

1단계. 설정된 항목 확인하기#

문서에서는 claude plugin list에 표시되는 name@marketplace 형식의 전체 플러그인 식별자를 요구합니다. configure 명령에는 @marketplace가 없는 이름을 사용할 수 없습니다.

claude plugin list
claude plugin configure formatter@my-marketplace

formatter@my-marketplace를 플러그인의 식별자로 바꾸세요. 플래그 없이 실행하면 각 설정에 required 또는 optional 레이블이 표시되고, 비밀 필드에는 sensitive가 표시되며, 그 뒤에 set 또는 not set 상태가 표시됩니다. 저장된 값은 출력되지 않습니다.

기계가 읽을 수 있는 출력이 필요하면 --json을 추가하세요. 이 경우 일반 필드에 저장된 값이 출력에 포함되지만, 비밀 필드의 내용은 절대 출력되지 않습니다.

2단계. 파일을 사용해 값 변경하기#

값은 JSON 객체로 제공하며, 각 키는 매니페스트에 있는 설정 이름이고 각 값은 줄바꿈이 없는 문자열입니다. 문서에는 파일을 이용하는 방법이 나와 있습니다. 객체를 values.json에 작성한 다음 해당 파일을 명령의 표준 입력으로 전달합니다. 여기서 api_url은 문서 예시에서 사용된 키입니다. 플러그인에 따라 1단계의 출력이나 매니페스트에서 필요한 설정 이름을 사용하세요.

{"api_url": "NEW_ADDRESS"}

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

저장할 때는 다음 규칙이 적용됩니다.

• JSON에서 생략한 설정은 이전 값을 유지합니다. 변경할 필드만 제공할 수 있습니다.
• 플래그 설명은 일반적인 값 설정을 다루며 비밀 필드에 별도의 규칙이 적용된다고 명시하지 않습니다. 저장한 후 1단계에 따라 해당 필드가 set으로 표시되는지 확인하세요.
• Claude Code는 각 값을 선언된 유형과 대조해 확인하고 Configuration saved. Restart Claude Code to apply it.을 출력합니다. 이는 설정이 저장되었으며 Claude Code를 다시 시작한 뒤 적용된다는 뜻입니다.
• JSON에 매니페스트에 선언되지 않은 키가 있거나 값이 유효성 검사를 통과하지 못하면 명령은 아무것도 저장하지 않습니다. Failed to save configuration: 뒤에 이유를 출력하고 종료 코드 1로 끝납니다.

values.json에 토큰을 작성하면 디스크에 저장되는 일반 파일이라는 점을 기억하세요. 설정을 저장한 뒤 파일을 삭제하고 저장소에 추가하지 마세요.

값이 저장되는 위치#

플러그인 매니페스트 문서에 따르면 일반 값은 사용자의 settings.json에서 pluginConfigs 아래에 저장됩니다. sensitive: true로 표시된 필드의 값은 settings.json이 아니라 시스템의 보안 자격 증명 저장소에 저장됩니다. 이러한 필드에 입력하는 값은 마스킹됩니다.

비밀 필드의 값을 settings.json에서 찾을 필요는 없습니다. claude plugin configure는 sensitive와 set 또는 not set 레이블로 상태를 표시합니다.

install --config: 설치 중 값 설정하기#

새로 설치할 때 claude plugin install은 --config <key=value> 플래그를 제공합니다. 이 플래그는 매니페스트에 선언된 userConfig 설정을 지정하며 v2.1.147 이상이 필요합니다. 설정마다 플래그를 반복해 사용하세요. 버전 2.1.285부터는 <server>.<key> 형식의 키로 포함된 MCP 서버에 해당 서버의 user_config에 선언된 설정을 지정할 수 있습니다.

아래 예시에서 formatter@my-marketplace를 플러그인의 식별자로 바꾸고, api_url을 매니페스트에 있는 설정 이름으로 바꾸세요. NEW_ADDRESS 자리 표시자 전체는 사용할 값으로 바꿉니다. 인수 양쪽의 따옴표는 그대로 유지하세요.

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

사용할 명령은 플러그인의 설치 여부에 따라 다릅니다. install --config는 처음 설치할 때 값을 지정하고, plugin configure --values-stdin은 이미 설치된 플러그인의 값을 변경합니다.

포함된 MCP 서버에 속한 설정의 경우 문서에는 plugin install --config 또는 /plugin의 Configure라는 다른 방법이 안내되어 있습니다. 해당 설정에는 plugin configure 명령을 사용하라고 되어 있지 않습니다.

명령에서 플러그인을 찾을 수 없는 경우#

claude plugin configure가 해당 식별자의 로드된 플러그인을 찾지 못하면 No installed plugin has the id "<plugin>".을 출력하고 종료 코드 1로 끝납니다. 먼저 claude plugin list에 표시된 전체 name@marketplace 식별자를 입력했는지 확인하세요. 플러그인 이름만으로는 부족합니다.

세션 내 명령은 다른 메시지를 표시합니다. /plugin enable, disable, uninstall 또는 configure를 사용할 때 현재 프로젝트에 설치되지 않은 플러그인을 지정하면 Claude Code는 Plugin "<plugin>" is not installed in this project를 출력하고 아무 작업도 하지 않습니다.

결론#

Claude Code 2.1.285 이상에서 이미 설치된 플러그인의 토큰이나 주소를 변경하려면 claude plugin list에서 식별자를 찾고, claude plugin configure로 설정 상태를 확인한 다음, --values-stdin을 사용해 파일에서 새 값을 제공하고 Claude Code를 다시 시작하세요. 비밀 필드 값은 settings.json에 저장되지 않으므로 같은 명령으로 상태를 확인하세요.

Claude Code의 Skills, Subagents, MCP 및 Plugins 가이드는 확장 유형을 선택하는 데 도움이 될 수 있습니다. 아직 플러그인을 고르지 않았다면 Claude Code 플러그인 상위 10개부터 살펴볼 수 있습니다. Telegram 봇에 관한 별도 가이드도 있습니다. Telegram 에이전트에 플러그인 설치하기는 Claude Code에 설치하는 방법과 다릅니다.

Ailoot에 대해 알아보세요.