トラブルシューティング

macOS でインストールに失敗する

macOS には Python 3.9 が同梱されていますが、keygrant には 3.10 以降が必要です。pip install ではなく、適切な Python をダウンロードしてくれる uv tool install keygrant を使ってください。

Claude Code がツールを認識しない

• keygrant init の後に Claude Code を再起動してください。Claude Code は起動時に .mcp.json を読み込みます。
• サーバーが単体で起動するか確認してください。keygrant-mcp は入力待ちの状態で止まるはずです（終了するには Ctrl+C）。“Command not found” と表示される場合は、ツールのディレクトリが PATH に含まれていません。.mcp.json には、uv tool dir で確認できる絶対パスを指定してください。
• Claude Code では、/mcp で接続中のサーバーを一覧表示できます。

モデルが値を貼り付けたり出力したりする

その値は、keygrant 以外のどこかから来ています。たとえば、エージェントが読み込んだ .env ファイルや、シェル環境に設定されている値です。keygrant が値をコンテキストから締め出せるのは、その値が keygrant に保存されている場合だけです。keygrant set で値を移し、.env 内のコピーを削除したうえで、CLAUDE.md にガイダンスブロックがあることを確認してください（keygrant init が追加します）。

CLI で $NAME が展開されない

keygrant exec は、シェルを介さずにコマンドを直接実行します。シェルで包んでください。

keygrant exec --redact KEY -- sh -c 'echo "$KEY"'        # macOS, Linux
keygrant exec --redact KEY -- cmd /c "echo %KEY%"        # Windows

“command is longer than 2000 characters”

長いコマンドはダイアログで確認しきれないため、拒否されます。処理をスクリプトファイルにまとめ、その内容を読んだうえで、スクリプトの実行を承認してください。

ダイアログが表示されない

• Linux： zenity をインストールしてください。これがないとローカルのダイアログは表示されず、リクエストは拒否されます（またはスマートフォン承認に送られます）。
• リモートセッション： ダイアログは、MCP サーバーを実行しているマシン上に表示されます。SSH 経由の場合、それはリモートホストです。スマートフォン承認を使ってください。

拒否したのにエージェントが何度も求めてくる

本来そうはならないはずです。ツールは、再試行しないようエージェントに伝えています。それでも繰り返す場合は、チャットでそう指摘してください。いずれにしても、そのリクエストに対する拒否は最終的なものです。

終了コード

keygrant exec は、使い方の誤りでは 2、シークレットが存在しない場合やその他のエラーが発生した場合は 1、アクセスが拒否された場合は 3 で終了し、それ以外の場合はコマンド自身の終了コードで終了します。

バグの報告

GitHub で Issue を作成してください。セキュリティに関わる内容については、代わりにセキュリティを参照してください。