「Commands refused」エラーの原因と対処 — Claude Codeバックグラウンド

Claude Codeのバックグラウンドセッションで /install-github-app や /mcp の設定画面を開こうとすると、対話ダイアログを開けずにコマンドが拒否されます。原因は単純です。バックグラウンドセッションには対話端末が接続されていないため、確認画面や選択肢を表示できません。対処法も同様に単純で、該当セッションにアタッチしてから同じコマンドを実行し直せば通ります。

Commands refusedエラーとは何か

このエラーは、対話ダイアログを必要とするコマンドを、端末が接続されていないバックグラウンドセッションで実行したときに出ます。バックグラウンドセッションは claude agents(agent view)や /bg、claude --bg から起動でき、ターミナルを占有せずに裏で作業を進められる点が利点です。ただしダイアログを表示する機能はこの仕組みと相性が悪く、人間が端末の前にいないと完結できません。

対象になるのは /install-github-app、/mcp の設定一覧画面、そしてMCPサーバーメニューの認証アクションの3つです。これらはいずれも選択肢の提示やブラウザ連携が必要なコマンドで、バックグラウンドで自動的に進めることができません。実際のメッセージはコマンドごとに文言が変わり、/mcp の設定一覧なら次のように表示されます。

なぜバックグラウンドセッションでは拒否されるのか

バックグラウンドセッションは元々、人が張り付いていなくても進む前提の実行モードです。GitHub Appのインストールも、MCPサーバーのOAuth認証も、ブラウザを開いて人間の承認を挟む必要があるため、端末なしでは完結できません。Claude Codeはこの矛盾を「拒否して自動的に再開経路へ誘導する」形で解決しています。

拒否されたセッションはagent viewの Needs input(要対応)グループに移動します。ここに並ぶのは、権限確認やサンドボックスのネットワーク許可プロンプト、MCPサーバーからの入力要求など、人間にしか答えられない状態のセッションです。対話コマンドの拒否もこの仲間として扱われ、行の説明に open this session to manage MCP servers のような案内が出ます。

対処法 — agent viewからアタッチして再実行する

もっとも確実な対処は、拒否されたセッションをagent viewから見つけてアタッチし、同じコマンドをもう一度実行することです。端末が接続された状態であれば、/install-github-app も /mcp の設定一覧も通常どおり動きます。

claude agents

Needs input グループに該当セッションが並んでいるので、行を選んで Enter か → でアタッチします。アタッチした状態で同じコマンドを打てば、拒否メッセージは出ずにダイアログが開きます。作業が終わったら ← でdetachすれば、セッションはバックグラウンドに戻ります。

/mcp に限っては、パネルを開かずに済ませる方法もあります。/mcp reconnect <server>、/mcp enable、/mcp disable はアタッチの有無にかかわらず動作するため、サーバー単位の操作だけなら設定一覧を開かなくても完結します。頻繁に同じサーバーを再接続するなら、この形の方がバックグラウンドセッションを止めずに済みます。

操作別の早見表

「拒否されたときにどうすればいいか」は操作によって変わります。よく使う操作をアタッチ要否と代替手段の軸で並べると次のとおりです。

表からわかるとおり、拒否されるのはブラウザを開いて人間の承認を必要とする操作に限られます。/mcp のサーバー単位のサブコマンドのように、承認を挟まない操作はバックグラウンドのままでも問題なく動きます。迷ったら「このコマンドはブラウザを開くか」を基準に考えると判断しやすくなります。逆に言えば、新しいMCPサーバーを追加する設定ファイルの編集や、すでに認証済みのサーバーへの再接続はブラウザを介さないため、バックグラウンドセッションを止めずにそのまま進められます。ブラウザ連携の有無を先に確認しておけば、拒否されてからアタッチ先を探す手間を減らせます。

バージョンによる挙動の違い

同じ「拒否される」という結果でも、Claude Codeのバージョンによって挙動と案内の中身が違います。過去のバージョンを使っている場合は、まずここで自分の状況を確認してください。

v2.1.208から212の期間だけは、端末をアタッチしていても /install-github-app や /mcp が動かない特殊な状態でした。この期間のバージョンを使っている場合、通常のClaude Codeセッション(バックグラウンドでない起動)からコマンドを実行すれば回避できます。もっとも根本的な対処はv2.1.213以降へのアップデートで、アップデートすればアタッチ経由の再実行で通るようになるため、バージョン更新が難しい環境でのみ通常セッションからの実行を選ぶ形になります。なお、v2.1.208限定で /model のモデル選択画面も同じ扱いで拒否され、/model <name> と直接打つとそのセッションだけモデルが切り替わり、デフォルトモデルの設定は更新されませんでした。

v2.1.216以降は、拒否されたセッションがagent viewのNeeds inputグループに確実に表示されるようになりました。それ以前のバージョンでは、拒否メッセージ自体は出てもagent viewの一覧上でセッションを見つけにくいことがありました。

こんなときにも起こる — 見落としやすいケース

/upgrade はダイアログを開くコマンドではないため、このエラーの対象には含まれません。ただしv2.1.208に限り、/upgrade はブラウザを開く代わりにアップグレードURLをテキストで出力する挙動になっていました。これは拒否ではなく代替表示なので、混同しないよう注意してください。

もう一つ見落としやすいのは、MCPサーバーの追加認証(OAuth)を求められる場面です。サーバー側が二段階認証やステップアップ認証を要求すると、Claude CodeはMCPサーバーメニューの認証アクションを呼び出しますが、これも対話ダイアログの一種としてバックグラウンドでは拒否されます。MCPサーバーの接続がバックグラウンドセッションだけ失敗するように見えたら、まずこのエラーを疑ってください。

claude attach <id> でセッションIDを直接指定してアタッチする方法もあります。agent viewの一覧を経由せず、スクリプトやショートカットからピンポイントで復帰したい場合に使えます。Needs input に並んだセッションを自動検知して通知したいなら、claude agents --jsonでバックグラウンドセッションを操作する方法が参考になります。状態をJSONで取得できるため、監視スクリプトから拒否イベントを拾って通知に回せます。

よくある質問

バックグラウンドセッションとは具体的に何を指しますか

claude agents(agent view)、/bg、claude --bg のいずれかで起動した、対話端末を持たないセッションです。並列で複数のタスクを進められる一方、対話ダイアログが必要な操作はこの制約を受けます。

エラーが出たセッションの作業は失われますか

失われません。拒否はコマンド単体に対する処理で、セッションが進めていたコード変更や会話は影響を受けずそのまま保持されます。アタッチして対象コマンドを実行し直せば作業を続けられます。

peekパネルからも再実行できますか

peekパネル(セッション行を選んで内容を覗く機能)は返信の送信はできますが、/install-github-app や /mcp のダイアログ自体はフルアタッチが必要です。Enter か → でアタッチしてから実行してください。

常に人が張り付く必要がありますか

いいえ。日常的なMCPサーバーの再接続やオンオフ切り替えは /mcp reconnect /mcp enable /mcp disable で完結し、アタッチ不要です。人手が要るのは初回の認証やGitHub Appの新規インストールなど、外部サービスとの初期連携だけです。

複数のセッションが同時に拒否された場合はどうすればいいですか

agent viewの Needs input グループには、拒否されたセッションがまとめて並びます。上から順にアタッチして処理する必要はなく、優先度の高いセッションから選んで先に片付けて構いません。他のセッションは拒否された状態のままバックグラウンドで待機し続けるため、後回しにしても作業内容が失われることはなく、順番を気にせず本来の優先度で処理を進められます。件数が多くなりがちなチームでは、claude agents --json で Needs input の一覧を取得し、GitHub Appのインストール待ちとMCP認証待ちを分けて処理する運用が現実的です。処理漏れを防ぐには、朝の作業開始時に一覧を確認する習慣をつけておくとよいでしょう。

まとめ

/install-github-app・/mcp の設定一覧・MCPサーバーの認証アクションは、端末が接続されていないバックグラウンドセッションでは拒否されます。エラーが出たら、agent viewのNeeds inputからセッションを見つけてアタッチし、同じコマンドを実行し直してください。/mcp のサーバー単位の操作だけならアタッチ不要で完結します。v2.1.208から212の間だけは挙動が特殊なので、該当バージョンを使っている場合は通常セッションからの実行に切り替えるのが確実です。

バックグラウンドセッション運用でぶつかりやすい他のエラーは、Claude Codeでよくあるエラー10選で症状別に整理しています。あわせて確認しておくと切り分けが早くなります。