Claude CodeでOperation not permittedの原因 — macOSのバックグラウンドセッション
macOSのバックグラウンドセッションで出るOperation not permittedとno route to hostの原因は、端末とは別に求められるフォルダとローカルネットワークの許可です。
端末で動くClaude Codeは~/Documentsを読めるのに、バックグラウンドセッションだけOperation not permittedになる。LAN内のサーバーへcurlが通るのに、バックグラウンドではconnect: no route to hostで落ちる。macOSでこの組み合わせが出たら、原因はClaude Codeの不具合ではなく、macOSの権限が「プロセスごと」に判定されている点にあります。
結論から書くと、バックグラウンドセッションを動かすホストは端末とは別のプロセスです。保護フォルダ(Desktop・Documents・Downloadsなど)への許可と、macOS 15以降のローカルネットワークへの許可を、端末とは別に求められます。端末に与えた許可は引き継がれません。
エラー文と許可の対応表
| 出ているメッセージ | 起きる場面 | 足りない許可 |
|---|---|---|
Operation not permitted | 起きる場面~/Desktop・~/Documents・~/Downloadsなどの保護フォルダを読む | 足りない許可ファイルとフォルダ、またはフルディスクアクセス |
connect: no route to host | 起きる場面LAN内のアドレスへ接続するコマンド(macOS 15以降) | 足りない許可ローカルネットワーク |
Operation not permitted(touch ~/sandbox-probe) | 起きる場面サンドボックス内で~に書く | 足りない許可許可の問題ではなくサンドボックスの正常な動作 |
3行目は紛らわしいので、あとで見分け方を書きます。
なぜバックグラウンドだけ失敗するのか
agent viewに出るセッションは、すべてバックグラウンドセッションとして扱われます。これらを動かすのは「supervisor」と呼ばれるバックグラウンドサービスで、各セッションはその下で別々のClaude Codeプロセスとして動きます。端末を閉じても動き続けるのはこの構造のためです。
macOSの権限確認(TCC)は、操作したプロセスを単位に判定します。端末から起動したclaudeは、端末アプリの許可で保護フォルダに届きます。supervisor配下のセッションは端末の子ではないので、同じ許可は使えません。ドキュメントには、バックグラウンドセッションのホストが保護フォルダへのアクセスを端末とは別に要求する、と書かれています。
自分のセッションがどちらの種類かは、セッション内で/statusを実行すれば分かります。
/statusSession kindの行がbackground job · attachedかbackground job · unattendedなら、権限の判定は端末ではなくバックグラウンドホスト側です。interactiveなら、通常の端末セッションです。
Operation not permittedを直す: ファイルとフォルダの許可
保護フォルダでOperation not permittedが出たときは、macOSのシステム設定で許可を与えます。
保護フォルダへの許可を与える手順
- 1
システム設定を開く
「プライバシーとセキュリティ」>「ファイルとフォルダ」を開きます。
- 2
Claude Codeの項目を探す
ネイティブインストーラーで入れた場合、項目はClaude Codeという名前で現れます。HomebrewやnpmではバイナリのパスがそのままUIに出ます。
- 3
該当フォルダをオンにする
Desktop・Documents・Downloadsのうち、セッションが触る場所をオンにします。範囲を絞りたくないときは、同じ項目にフルディスクアクセスを与える選択肢もあります。
- 4
セッションを再開して確かめる
失敗していた読み取りをもう一度やらせます。確かめ方は、下の動作確認で示します。
フルディスクアクセスは保護フォルダ全体に効く強い許可です。必要な場所が決まっているなら、ファイルとフォルダで個別にオンにするほうが与える範囲が小さくなります。
インストール方法で許可の残り方が変わる
許可の見え方と持続性は、インストール方法で分かれます。
| インストール方法 | 設定画面での項目名 | 更新後の許可 |
|---|---|---|
| ネイティブインストーラー | 設定画面での項目名Claude Code | 更新後の許可保持される |
| Homebrew・npmなど | 設定画面での項目名バイナリのパス | 更新後の許可付け直しが必要になることがある |
更新のたびに許可を求められるという報告と、その仕組みはmacOSの権限が更新で消える原因と再許可の手順に詳しくあります。インストール方法そのものを選び直したいときは、macOSへのインストール手順が入口になります。
connect: no route to hostを直す: ローカルネットワークの許可
macOS 15以降は、ローカルネットワーク上の機器へ届くプロセスに、ユーザーの許可を求めます。許可がないプロセスからLANアドレスへ接続すると、通信が成立せずconnect: no route to hostのようなエラーになります。端末では通るのにバックグラウンドで落ちるのは、許可を持つプロセスが違うためです。
直し方は単純です。バックグラウンドセッションでLANアドレスへ接続するコマンドを最初に実行すると、macOSがClaude Code向けのローカルネットワーク許可のプロンプトを出します。ここで許可すれば、以降は端末と同じように届きます。許可は一度で足ります。
プロンプトを見逃した、または拒否した場合の戻し方は、agent viewのドキュメントには書かれていません。macOSの「プライバシーとセキュリティ」画面で、ローカルネットワークの項目にClaude Codeが並んでいるかを確かめます。
v2.1.198より前は挙動が違う
v2.1.198で、バックグラウンドセッションのホストが初回のLANアクセス時にmacOSのローカルネットワーク許可を求めるようになりました。変更前は許可を求めずにconnect: no route to hostで失敗していました。
プロンプトがまったく出ずに失敗するなら、まずclaude --versionでバージョンを確かめます。古ければ更新したうえで、バックグラウンドのsupervisorを入れ替えます。入れ替えの手順は、後の動作確認に書きました。この版の他の変更点はv2.1.198のリリースノートにあります。
サンドボックスのOperation not permittedとの見分け方
Operation not permittedは、macOSの権限以外でも出ます。サンドボックスを有効にしていると、サンドボックス内のコマンドが許可されていない場所に書こうとしたときに、macOSでは同じメッセージで失敗します。サンドボックスの動作確認として挙げられているtouch ~/sandbox-probeも、サンドボックスの内側ではこのエラーで失敗するのが正常です。
見分けるポイントは次の3つです。
- 失敗するのがバックグラウンドセッションだけで、同じ操作が端末の通常セッションでは通る → TCCの許可を疑う
- 通常セッションでも、サンドボックス内のコマンドだけが失敗する → サンドボックスの書き込み許可を疑う
~/Desktop・~/Documents・~/Downloadsで起き、サンドボックスが無効 → TCC。サンドボックスの設定はsandbox.enabledで確かめる
サンドボックス側の原因では、システム設定のフォルダ許可を変えても直りません。逆にTCC側の原因では、サンドボックスの設定を変えても直りません。
端末側のEPERMは別の話
errorsのドキュメントには、Claude Codeを起動した作業ディレクトリが読めないケースが載っています。~/Desktop・~/Documents・~/DownloadsやiCloud DriveのフォルダでEPERMになる場合は、macOSが端末アプリからそのフォルダへのアクセスを止めている状態です。このとき、同じフォルダを読む他のコマンドも同じように失敗し、lsがOperation not permittedを返します。sudoを付けても変わりません。
対処は、端末アプリをCmd+Qで終了して開き直し、そのフォルダに移ってからclaudeを実行することです。それでもlsが失敗するなら、「ファイルとフォルダ」で端末アプリのフォルダをオンにして、端末を開き直します。
これはバックグラウンドホストの許可ではなく、端末アプリの許可です。ただし表に出るメッセージは同じなので、端末でls ~/Documentsが通るかを先に試せば、問題の側を絞れます。
動作確認の手順
許可を与えたら、新しいバックグラウンドセッションを1つ起動して、権限が必要な操作をやらせれば確かめられます。
claude --bg "ls ~/Documents を実行して、先頭の10件を報告して"claude --bgは、セッションをバックグラウンドで直接始めるコマンドです。プロンプトは位置引数で渡し、-pとは併用できません。
許可を変えても古いsupervisorが動き続けて反映されないのでは、と疑うときは、状態を確認します。
claude daemon status
claude daemon logsclaude daemon statusは、supervisorに接続できるか、プロセスID、バージョン、動いているバックグラウンドセッションの数を出します。claude daemon logsは~/.claude/daemon.logを追いかけて表示します。実行中のsupervisorが、手元のclaudeと別のバージョンのときは、警告も出ます。
更新後の入れ替えが必要なら、次の2手を使います。
claude daemon stop --any --keep-workers
claude agents--keep-workersを付けると、動いているバックグラウンドセッションを残したまま止められます。約1分以内にclaude agentsを実行すれば、新しいsupervisorが残ったセッションへ再接続します。それを過ぎるとmacOSではセッションが止まりますが、保存済みの会話はディスクに残り、開くか返信すれば再開します。
切り分けの順番
原因の見当がつかないときは、次の順で絞ります。
最初に確かめる2点
1. 通常セッションで通るか
同じ操作が端末の通常セッションで通るなら、バックグラウンドホスト側の許可が候補です。通常セッションでも失敗するなら、端末アプリの許可かサンドボックスを疑います。
2. インストール方法とバージョンを見る
Homebrewやnpmなら、更新後に許可が外れていないかを確かめます。
no route to hostでプロンプトが出ないなら、バージョンがv2.1.198より前でないかを確かめます。
バックグラウンドセッションが起動すらしない場合は、権限ではなく別の原因です。npm更新中の差し替えやWindowsの制限ポリシーで起きるEACCES・EUNKNOWNは、バックグラウンドセッションが起動しない原因にまとめています。agent view全体の仕組みや使い方は、agent viewで複数セッションを並列に動かすで扱っています。
まとめ
バックグラウンドセッションでOperation not permittedが出るのは、保護フォルダへの許可が、端末とは別のホストプロセスに必要だからです。ファイルとフォルダ(またはフルディスクアクセス)で与えます。connect: no route to hostは、macOS 15以降のローカルネットワーク許可で、初回のLAN接続時のプロンプトに応じれば足ります。
どちらも、端末で通るから設定は済んでいる、とは判断できません。許可が効く主体が違う、という一点を押さえておけば、メッセージから足りない許可を逆算できます。HomebrewとnpmではバイナリのパスがUIに出るため、更新後の再許可が要る前提で運用すると、同じエラーに再び当たったときにも落ち着いて対処できます。