【適するケース】ノードはオンラインなのにコマンドが失敗する場合は、配線やネットワークを変更する前に、実行権限と実行先を順番に確認してください。接続済みという表示は接続状態を示すもので、命令の実行許可までは保証しません。
OpenClawとmacOS実行ノードを保守し、Agentのコマンド失敗を調べるエンジニア向けです。
Apple向けCIの実行先を確認したい開発者や、権限を必要以上に広げずに復旧したいDevOps担当者にも役立ちます。
最終更新：2026年10月27日。OpenClawの公式ノード排障、ペアリング、コマンドポリシー、実行承認の資料と、AppleのXcodeコマンドラインツール資料を照合しています。
00OpenClawのリモートMacでコマンド実行に失敗したときの切り分け
この障害は、接続そのものと実行許可を分けて調べます。OpenClawの公式資料では、ノードのペアリング、コマンド面の承認、Gatewayのノードコマンドポリシー、ノード側の実行承認がそれぞれ別の確認境界として扱われています。ノードのトラブルシューティングとノードのペアリング手順を見比べ、最初に「接続できているか」と「命令が許可されているか」を別々に記録します。
| 見えている状態 | そこから分かること | 次に確認する対象 |
|---|---|---|
| ノードがオンライン | ノードとの接続状態を確認できます | ペアリング記録、ノード識別情報 |
| ノードがペアリング済み | ペアリングの状態を確認できます | 利用できるコマンド面、Gatewayのポリシー |
| コマンド要求が拒否される | 実行許可か承認の段階で止まった可能性があります | 拒否ログ、ノード側の承認状態 |
| コマンドが完了するが結果が違う | 実行先や実行環境が想定と異なる可能性があります | 対象ノード、ユーザー、作業ディレクトリ、ツールチェーン |
配線やXcodeを先に疑わない
接続表示が正常でも、実行承認が残っていればコマンドは拒否されます。また、コマンドが成功しても、複数ノードのうち別のMacで実行されていれば、期待したXcodeやプロジェクトの状態とは一致しません。したがって、最初からXcodeを再インストールしたり、Gatewayの制限を解除したりせず、失敗した段階をログで特定します。
01拒否ログから権限境界を特定する
OpenClawのログや管理画面に表示される状態を、ペアリング済みかどうかだけで判断しないでください。ノードが利用可能なコマンドを示しているか、Gatewayがそのコマンドを許可しているか、ノード自身が具体的な要求を承認しているかは別々に確認します。ノードコマンドのポリシーと実行承認の仕組みでは、Gateway側のポリシーとノード側の承認が扱われています。
| ログや表示の手掛かり | 確認する場所 | 安全な確認方法 |
|---|---|---|
| ペアリングに関する保留や不一致 | ノードのペアリング状態 | 要求元とノードの識別情報を照合します |
system.runが使えない、または拒否される |
コマンド面、Gatewayポリシー | 実際のコマンド識別子と許可・拒否の判定を調べます |
approval required |
ノード側の実行承認 | 対象要求の承認待ちと人手確認の手順を確かめます |
allowlist miss |
ノード側の許可リスト | 実際に要求されたコマンドと登録内容の差を確認します |
これらの文字列が表示されない環境もあります。表はエラーの一般的な分類を断定するものではなく、公式資料にある制御境界と照らして、該当するログを調べるための手掛かりです。
拒否を解消するために、全コマンドを許可したり承認を無効にしたりするのは避けてください。まず一つの安全な確認コマンドに絞り、必要な権限だけで再現するかを確かめます。
025段階で要求経路を追う
以下の順に、同じノード、同じ要求、同じログの時間帯を照合します。各確認で状態が変わったら、その時点で短い読み取り専用コマンドを試し、次の段階へ進んでください。
-
ノードの識別と接続を確認します。 OpenClawのノード状態と排障情報を参照し、Agentが参照しているノード識別情報と、管理側に表示される対象が一致しているかを見ます。オンライン表示だけで実行許可まで確認できたとは判断しません。接続とノード状態を別々に確認します。
-
ペアリングとコマンド面を分けて確認します。 ペアリング要求の状態を見たうえで、対象ノードが利用できるコマンド面に
system.runが含まれているかを確認します。ペアリング記録が正常でも、実行に必要なコマンド面が利用可能とは限りません。ノードの説明や状態表示を記録し、承認待ちがあれば、その対象が正しいノードかも照合します。リモートノード実行の説明を参照してください。 -
Gatewayの許可・拒否判定を調べます。 要求されたコマンド識別子を確認し、ポリシーが対象ノードの命令を許可しているかをログで確かめます。全体に適用される制限と、ノードが宣言しているコマンドとの差を切り分け、原因が分からないまま広い許可を追加しないでください。
-
ノード上の個別承認を確認します。
approval requiredと表示された場合は承認待ちの要求、allowlist missと表示された場合は実際のコマンドと許可リストをそれぞれ確認します。ペアリング記録を書き換えても、ノード側の承認問題は解消されない場合があります。必要な場合は、対象コマンドだけを許可し、人による確認が必要な運用はそのまま維持します。 -
実行対象を固定し、最小コマンドで検証します。 複数の実行可能ノードがある場合は、Agentの実行要求が意図したノードを指しているかを確認します。コマンドが拒否されずに実行されたら、まず
whoamiとpwdで実行ユーザーと作業ディレクトリを確かめます。ログに残るノード識別情報と出力も合わせて保存してください。
OpenClaw側の状態を確認した後に初めて、macOS上のツールやプロジェクトパスを調べます。原因が権限や実行先にある段階では、Xcodeの再導入だけでは診断になりません。
03対象MacのXcodeと作業ディレクトリを検証する
コマンドが対象ノードで実行されたと確認できたら、同じ実行経路からユーザー、プロジェクトパス、Xcodeの開発者ディレクトリを調べます。実行結果をローカル端末のシェル出力と混同しないよう、OpenClaw側のノード識別情報とコマンド出力を一組で保存します。
whoami
pwd
xcode-select -p
xcodebuild -version
xcode-select -pで示された開発者ディレクトリと、xcodebuild -versionの結果が期待した環境に合うかを確認します。Appleのコマンドラインツールのインストール資料では、Xcodeを使うにはXcodeをインストールし、アクティブな開発者ディレクトリを設定する必要があると説明されています。表示結果が想定と異なる場合は、ノード上のインストール状態と選択中のディレクトリを確認してから修正してください。
コマンドラインツールの確認だけでは、対象プロジェクトがビルドできるとは限りません。プロジェクトの形式とスキームに合わせ、実際の作業ディレクトリから影響の小さいビルドを一つ実行します。たとえば、プロジェクト側の設定に合う場合は、次のようなコマンドでビルド結果を確認できます。
xcodebuild -project "<project>.xcodeproj" -scheme "<scheme>" -configuration Debug build
ワークスペースを使うプロジェクトでは、-projectではなく適切なワークスペース指定が必要です。プレースホルダーは実際のプロジェクト名とスキームに置き換え、プロジェクト固有の署名や依存関係が必要な場合はその条件も記録します。実行先の確認とビルドの成功は別の証拠として扱い、片方だけで復旧完了としないでください。
04修復後の権限と実行結果をチェックする
復旧後は、最初に失敗した要求を再実行し、どの設定を直したことで成功したのかを記録します。次の項目をすべて確認できるまでは、原因が解消したと判断しないでください。
- [ ] 対象ノードの識別情報と接続状態が、実行要求の宛先と一致している。
- [ ] ペアリング状態とは別に、必要なコマンド面が利用可能だと確認できている。
- [ ] Gatewayのポリシー結果と、要求されたコマンド識別子を記録している。
- [ ] ノード側の承認待ち、許可リスト、人手確認の条件を確認している。
- [ ]
whoamiとpwdの出力が想定した実行ユーザーと作業場所を示している。 - [ ]
xcode-select -pとxcodebuild -versionの結果を保存している。 - [ ] 実際のXcodeビルドを実行し、結果と対象ノードを一緒に記録している。
- [ ] 復旧後も残る権限制限、必要な承認、問題再発時の戻し方を明記している。
障害記録には、失敗時と復旧後の要求、ログ、実行先、許可変更、ビルド結果をまとめます。許可を一時的に変更した場合は、作業後に戻す条件も記録します。こうすれば、コマンドが動いたという結果だけでなく、過剰な権限変更を残していないこともレビューできます。
05よくある原因と確認方法
接続済みでもAgentの命令が拒否される
接続状態だけでは、コマンド面、Gatewayポリシー、ノード上の個別承認は確認できません。失敗した要求のログから、どの境界で止まったかを確かめます。オンライン表示を根拠に、ノードの再登録やネットワーク設定変更へ直行しないでください。
system.runの拒否とペアリングの不備を区別する
system.runの拒否では、要求されたコマンド面とGatewayの判定、ノードの承認記録を順に確認します。ペアリングが済んでいるという事実だけで、これらの確認が不要になるわけではありません。表示された拒否理由と、公式のノード実行の仕様を照らし、必要な範囲だけを修正します。
Xcodeのビルドが別のMacや別の環境で動く
複数ノードがある環境では、Agentの実行先を明示し、ノード識別情報とwhoami、pwdの結果を照合します。その後、xcode-select -pとビルド結果を同じ実行記録に残してください。Xcodeのツールチェーンに関する確認条件はAppleの公式資料に沿って判定します。
06継続稼働が必要なら実行環境も比較する
Linuxのクラウド環境はmacOS専用のXcodeツールチェーンをそのまま検証できず、開発者の手元のMacは、その端末が停止中のときに継続的な実行先として使えません。一方、Macを自前で常時運用する場合は、調達、保守、アクセス管理を継続して担う必要があります。短期間の検証やチームで共有する実行環境が必要なら、リモートMacの接続方法をNUKCLOUDの案内で確認し、既存のOpenClawポリシーと最小権限の手順を適用できるかを先に試してください。
NUKCLOUDのMacレンタルは、手元に実機を用意せずにmacOSの実行環境を確保したい場合の選択肢です。継続的な高負荷運用や物理ポートへの直接アクセスが必要なら、自社保有のMacのほうが合う場合もあります。必要な実行期間、チームのアクセス方法、承認の運用を整理したうえで、NUKCLOUDのサービス情報を参照し、実際のワークフローで適合性を確認してください。