Exec host のリファクタリング：安全で柔軟なコマンド実行の実現

AI エージェントにローカルコマンドを実行させる際、セキュリティの境界線に悩むことはありませんか？ すべての操作を許可するのは危険ですが、制限が厳しすぎると AI の能力を十分に発揮できません。開発者にとって、実行環境の分離と安全な権限管理の両立は常に大きな課題です。

今回のリファクタリングでは、実行場所を柔軟に切り替えつつ、デフォルトの安全性を確保する新しい仕組みを導入しました。

必要なもの

設定を始める前に、以下のコンポーネントが動作していることを確認してください。

• Bridge
• Gateway
• Node identity (nodeId)

クイックスタート

コマンドの実行環境を制御するには、exec.host と exec.security の 2 つの設定を組み合わせます。

1. 実行ホストの選択

exec.host を設定して、コマンドをどこで実行するかを指定します。デフォルトは sandbox です。

• sandbox: Docker 内で実行します。
• gateway: Gateway ホスト上で実行します。
• node: Bridge 経由で特定のノード上で実行します。
• system.run: macOS アプリなどの UI コンテキストで実行します。

2. セキュリティポリシーの設定

exec.security を使用して、実行の許可レベルを決定します。

• deny: すべての実行をブロックします（デフォルト）。
• allowlist: 許可リストに一致するものだけを実行します。
• full: すべての実行を許可します（/elevated と同等）。
• ask: 実行前にユーザーの承認を求めます。

3 設定ファイルの作成

承認設定や許可リストは ~/.openclaw/exec-approvals.json に保存されます。以下は設定の例です。

{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64-opaque-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny"
  },
  "agents": {
    "agent-id-1": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [
        {
          "pattern": "~/Projects/**/bin/rg",
          "lastUsedAt": 0,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

4. スラッシュコマンドでの操作

チャットインターフェースから直接設定を変更することも可能です。

/exec host=node security=allowlist ask=on-miss node=my-macbook

また、一時的に権限を昇格させる場合は /elevated on を使用します。

トラブルシューティング

設定中に問題が発生した場合は、以下の点を確認してください。

• UI が表示されない: 承認が必要な場面で UI アプリが起動していない場合、askFallback の設定が適用されます。デフォルトでは deny になり、安全のために実行が拒否されます。
• ノードの特定に失敗する: exec.node で指定した ID や名前が正しくない場合、実行エラーになります。nodeId の完全一致、または 6 文字以上のプレフィックスを使用してください。
• 出力が途切れる: 出力サイズは合計 200k に制限されています。これを超える場合は末尾の 20k のみが保持され、残りは切り捨てられます。
• 権限エラー: exec-approvals.json のファイルパーミッションが 0600 になっているか確認してください。

設定の詳細や具体的な構成案については、AI Setup Assistant に相談してください。

次のステップ

• Exec tool
• Exec approvals
• Nodes
• Elevated mode