claude plugin configureでプラグインの未設定オプションを確認・保存する

claude plugin configure <plugin> は、インストール済みプラグインの設定項目(userConfig)を一覧し、どれが未設定かを確かめるコマンドです。--values-stdin を付けると、標準入力で渡したJSONを値として保存できます。v2.1.285(2026年9月29日)で追加されました。/plugin の画面を開かずに、シェルだけで設定を済ませたい場面に向いています。

userConfig の宣言の書き方はClaude Code plugin userConfigの書き方にあります。ここでは、利用者がCLIで値を確認・保存する手順を扱います。

claude plugin configureは何をするコマンドか

プラグインは plugin.json に userConfig を宣言でき、有効化したときにClaude Codeが値の入力を求めます。エンドポイントのURLやAPIトークンのように、利用者ごとに違う値を受け取るための仕組みです。

これまで値を入れる手段は /plugin 画面のConfigure optionsでした。claude plugin configure はそのCLI版で、役割は2つあります。

• 引数だけで実行すると、各オプションの状態を一覧する
• --values-stdin を付けると、標準入力のJSONを検証して保存する

対象はインストール済みのプラグインです。プラグインの指定は name@marketplace の完全なIDで行い、名前だけの指定は受け付けません。IDは claude plugin list の表示と同じ形で渡します。該当するIDが無いと No installed plugin has the id "<plugin>". と表示されて終了コード1になります。

claude plugin list
claude plugin configure formatter@my-marketplace

formatter@my-marketplace は例です。実際には手元の claude plugin list に出るIDに置き換えてください。

未設定のオプションを一覧で確かめる

フラグなしで実行すると、オプションごとに最大3つのラベルが付いて並びます。

この一覧は保存済みの値そのものを表示しません。画面に出るのは状態だけです。

使いどころは、チームに配ったプラグインの設定漏れを洗い出す場面です。required で not set の行が残っていれば、そのプラグインはまだ動く状態にありません。CIやセットアップスクリプトで「必須が埋まっているか」を機械的に見たいなら、次の --json が向いています。

--jsonでスクリプトから状態を読む

--json を付けると、結果が標準出力に1つのJSONオブジェクトとして出ます。--values-stdin の有無で中身が変わります。

機密でないオプションの保存値は --json の出力に含まれます。機密オプションの値は、--json でも出力されません。

claude plugin configure formatter@my-marketplace --json \
  | jq '.unconfigured'

jq は読み取りの一例です。unconfigured の配列が空かどうかで、設定が揃っているかを判定できます。configured と unconfigured に実際どんな順で名前が並ぶかは、手元で一度実行して確かめてください。

--values-stdinで値を保存する

保存は、オプションのキーと文字列値を対応させたJSONオブジェクトを標準入力に流して行います。次の例は api_url を1つ設定します。

echo '{"api_url": "https://example.com"}' > values.json
claude plugin configure formatter@my-marketplace --values-stdin < values.json

成功すると Configuration saved. Restart Claude Code to apply it. と表示されます。値は次回の起動から反映されるので、実行中のセッションには効きません。

保存のルールは次のとおりです。

• 値は単一行の文字列のJSONオブジェクトで渡す
• JSONに書かなかったオプションは、保存済みの値がそのまま残る
• 各値は、オプションが宣言した型で検証される
• マニフェストに無いキーや、検証に通らない値が1つでもあると何も保存されない。Failed to save configuration: と理由が出て、終了コードは1

最後の点は、複数のキーをまとめて渡すときに効きます。一部だけ保存されて中途半端な状態になることはありません。--json と併用して拒否されたときは、標準出力の refused フィールドに message が入り、原因が1つのオプションに絞れる場合は option のキーも入ります。

数値や真偽値、multiple のリスト、directory や file を、単一行の文字列でどう書くかは、CLIリファレンスに例がありません。型が string 以外のオプションは、まず値を1つだけ渡して、検証の結果を見てから揃えるのが安全です。

機密値を履歴に残さず渡す

sensitive: true のオプションは、入力が伏せ字になり、settings.json ではなくプラットフォームの安全な保管先に保存されます。claude plugin configure の一覧もこのオプションの値を表示しません。

標準入力で渡せることは、機密値をコマンドライン引数に書かずに済むという意味でも有利です。引数に書いた値はシェルの履歴やプロセス一覧に残りえますが、標準入力なら残りません。環境変数に入れた値をJSONに組み立てて渡す例を挙げます。

jq -n --arg token "$PLUGIN_API_TOKEN" '{api_token: $token}' \
  | claude plugin configure formatter@my-marketplace --values-stdin

文字列を手で組み立てて echo に渡すと、値に引用符や円記号が含まれたときにJSONが壊れます。jq --arg のようにJSONとして正しくエスケープしてくれる道具を挟むと、この事故を避けられます。jq はあくまで一例で、同じ形のJSONを標準入力へ流せれば手段は問いません。

保存した値はどこに入るか

保存先は機密かどうかで分かれます。

• 機密でない値: 利用者の settings.json の pluginConfigs 配下。プラグインIDをキーにして、options の中にオプション名と値が入る
• 機密の値: macOSではキーチェーン。書き込みを拒否された場合や、キーチェーンの無い環境では ~/.claude/.credentials.json

pluginConfigs のイメージは次のとおりです。公式の設定リファレンスにある deployer@acme-tools の例に沿った形です。

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

読み込み元にも制限があります。pluginConfigs が読まれるのは、利用者設定・--settings・管理設定です。プロジェクト側の .claude/settings.json の pluginConfigs は読まれません。値はプラグインのhookやMCP、LSPの設定に差し込まれるため、クローンしたリポジトリから持ち込めない仕様になっています。したがって、チームで共有するリポジトリに設定値をコミットしても効きません。配る側は、各自が claude plugin configure を実行する手順を用意することになります。

保存した値をプラグイン側がどう参照するか(${user_config.KEY} を使える場所や、シェル形式のhookで拒否される理由)は、作者向けの話です。詳細はuserConfigの書き方を参照してください。

/plugin画面・install --configとの使い分け

設定の入口は複数あり、できることが少しずつ違います。

同じv2.1.285では、claude plugin install --config が <server>.<key>=<value> の形も受け付けるようになりました。プラグインが同梱する .mcpb のMCPサーバーが、自前の user_config で宣言した設定を、インストール時に渡すための書式です。claude plugin configure が扱うのはプラグイン本体の userConfig で、同梱MCPサーバー側の設定は対象外です。そちらは plugin install --config か、/plugin のConfigure項目で行います。

/plugin の詳細メニューには、この2つが別項目で並びます。Configure optionsは userConfig を宣言したプラグイン、Configureは .mcpb のMCPサーバーを同梱したプラグインに出ます。両方を備えたプラグインでは両方が表示されます。

一覧に出るオプションは作者が決める

claude plugin configure が一覧するのは、プラグインの plugin.json に書かれた userConfig です。フィールドの一覧や claude plugin validate での事前確認は、userConfigの書き方にあります。

利用者の側から見ると、一覧に required と出るのは、作者が required: true を宣言したオプションです。sensitive が付く項目は sensitive: true の宣言によるもので、利用者側で切り替えることはできません。配布する側は、機密にしたい値に必ずこの宣言を付けておく必要があります。

設定し終わっても動かないときの確認先

値を保存したのに期待どおり動かないときは、順に次を見ます。

1. 再起動したか。保存直後のメッセージが示すとおり、反映はClaude Codeの再起動後です
2. IDが合っているか。名前だけでは受け付けないため、name@marketplace を claude plugin list の出力と照らします
3. 参照先がシェルになっていないか。プラグインのシェル形式hookなどが ${user_config.*} を使っていると、設定の有無にかかわらずエラーになります
4. 値の置き場所。プロジェクトの .claude/settings.json に書いた pluginConfigs は読まれません

プラグイン関連の別の失敗については、GitHub MCPプラグインがHTTP 400で失敗する原因と対処法も参考になります。複数のプラグインをセッション単位で読み込む方法は、CLAUDE_CODE_PLUGIN_DIRSで複数プラグインをセッション単位で読み込むにまとめています。組織としてスキルやhookの出どころをプラグインに絞る設定は、strictPluginOnlyCustomizationでskillsやhooksをプラグインに絞るの領分です。

運用に組み込む例

チームでプラグインを配るなら、導入手順書の末尾に「claude plugin configure <id> --json で unconfigured が空であること」を確認する1行を足す形が考えられます。設定値の受け渡しは、パスワードマネージャーや社内のシークレット基盤から環境変数に取り出し、--values-stdin へパイプするのが筋です。リポジトリに値を置いても pluginConfigs は読まれないので、置くのは手順とプラグインIDまでにとどめます。

CLAUDE.mdに書く場合は、次のような短い規約が実用的です。

## プラグインの設定
- 新しい環境では `claude plugin list` で ID を確認し、
  `claude plugin configure <id> --json` の `unconfigured` が空になるまで設定する
- 機密値は引数に書かず、標準入力(`--values-stdin`)で渡す
- 設定後は Claude Code を再起動する

エージェントに任せる場合も、機密値を会話に貼らせず、環境変数経由で流す手順にしておくと値が履歴に残りません。

まとめ

claude plugin configure の価値は、プラグイン設定を画面操作から切り離せる点にあります。状態の確認は引数なし、機械可読な出力は --json、保存は --values-stdin です。検証に失敗すると何も保存されない仕様が、スクリプトに組み込むときの安心材料になります。型が string 以外のオプションの書き方は一次資料に例がないため、実機で1項目ずつ試す前提で組み立てるのが現実的です。