OpenClaw Agent 工具权限配置详解：从 gateway 权限管控到 tools.deny / alsoAllow / profile 最佳实践

// 全局默认使用 coding profile
{
  "tools": {
    "profile": "coding",
    "agentToAgent": { "enabled": true },
    "sessions": { "visibility": "all" }
  }
}

// kb-writer：拒绝 gateway 管理工具
{
  "agents": {
    "list": [
      {
        "id": "kb-writer",
        "tools": {
          "profile": "coding",
          "alsoAllow": ["message"],
          "deny": ["gateway"]
        }
      },
      // 所有其他非主 Agent 统一模式
      {
        "id": "design-yuntianguang",
        "tools": {
          "alsoAllow": ["exec", "image", "read", "write", "edit", "web_fetch"],
          "deny": ["gateway"]
        }
      },
      {
        "id": "editor-blog-yuntianchen",
        "tools": {
          "deny": ["gateway"]
        }
      }
    ]
  }
}

{
  "tools": {
    "deny": ["group:runtime", "group:fs"]
  }
}

// ❌ 错误：allow 和 alsoAllow 不能共存
{
  "tools": {
    "allow": ["read", "write"],
    "alsoAllow": ["message"]  // 配置校验会直接拒绝
  }
}

// ✅ 正确：二选一
{
  "tools": {
    "allow": ["read", "write", "message"]  // 合并到 allow
  }
}

// ✅ 正确：用 profile + alsoAllow 替代 allow
{
  "tools": {
    "profile": "coding",
    "alsoAllow": ["message"]  // 在 coding 基础上追加
  }
}

// oc-engineer：messaging profile 基础上追加运维工具
{
  "agents": {
    "list": [
      {
        "id": "oc-engineer",
        "tools": {
          "alsoAllow": [
            "exec", "read", "write", "edit",
            "web_fetch", "process", "gateway",
            "cron",
            "feishu_calendar_calendar",
            "feishu_chat", "feishu_oauth",
            "feishu_sheet", "feishu_task_task",
            "feishu_task_agent", "feishu_task_attachment",
            "sessions_spawn"
          ],
          "profile": "messaging"
        }
      }
    ]
  }
}

// kb-writer：coding profile 基础上追加 message 工具
{
  "agents": {
    "list": [
      {
        "id": "kb-writer",
        "tools": {
          "profile": "coding",
          "alsoAllow": ["message"],
          "deny": ["gateway"]
        }
      }
    ]
  }
}

{
  "tools": {
    "profile": "coding",
    "byProvider": {
      // 所有 google 提供商的模型使用 minimal profile
      "google-antigravity": {
        "profile": "minimal"
      },
      // 仅 openai/gpt-5.4 使用扩展权限
      "openai/gpt-5.4": {
        "allow": ["group:fs", "sessions_list"]
      }
    }
  }
}

{
  "tools": {
    "sandbox": {
      "tools": {
        "alsoAllow": [
          "web_search", "web_fetch",
          "memory_search", "memory_get",
          "bundle-mcp"  // 放行所有 MCP 工具
        ]
      }
    }
  }
}

{
  "id": "main",
  "tools": {
    "profile": "full",           // 全部工具
    "alsoAllow": [
      "feishu_calendar_calendar",
      "feishu_chat",
      "feishu_oauth",
      "feishu_sheet",
      "feishu_task_task",
      "exec", "read", "edit",
      "write", "sessions_history",
      "sessions_spawn", "sessions_send"
    ],
    "deny": ["gateway"]          // 不允许管理网关（避免自操作冲突）
  }
}

{
  "id": "kb-writer",
  "tools": {
    "profile": "coding",         // 文件读写 + 会话管理 + 媒体生成
    "alsoAllow": ["message"],    // 追加飞书消息能力
    "deny": ["gateway"]          // 禁止网关操作
  }
}

{
  "id": "oc-engineer",
  "tools": {
    "profile": "messaging",      // 消息 + 会话基础
    "alsoAllow": [
      "exec", "read", "write",
      "edit", "web_fetch",
      "process", "gateway",      // 运维核心能力
      "cron",
      "feishu_calendar_calendar",
      "feishu_chat", "feishu_oauth",
      "feishu_sheet",
      "feishu_task_task",
      "feishu_task_agent",
      "feishu_task_attachment",
      "sessions_spawn"
    ]
    // 无 deny → 所有工具均可用（除被 sandbox 限制的）
  }
}

{
  "id": "editor-blog-yuntianchen",
  "tools": {
    "deny": ["gateway"]          // 极简配置：仅禁止网关
    // 继承全局 coding profile
  }
}

{
  "id": "design-yuntianguang",
  "tools": {
    "alsoAllow": [
      "exec", "image",
      "read", "write", "edit",
      "web_fetch"
    ],
    "deny": ["gateway"]
    // 继承全局 coding profile
  }
}

// ❌ 错误：配置校验会拒绝
{
  "tools": {
    "allow": ["read", "write"],
    "alsoAllow": ["message"]
  }
}

// ✅ 正确：统一使用 alsoAllow + profile
{
  "tools": {
    "profile": "coding",
    "alsoAllow": ["message"]
  }
}

// ✅ 正确：统一使用 allow（显式列出所有工具）
{
  "tools": {
    "allow": ["read", "write", "message"]
  }
}

# 验证配置语法
openclaw config validate

# 重启 Gateway（热加载）
openclaw gateway restart

openclaw doctor 2>&1 | grep -A5 "kb-writer"

{
  "tools": {
    "allow": ["read", "write", "exec"],
    "deny": ["exec"]  // exec 虽然在了 allow 中，但仍然不可用
  }
}

# 排查：检查沙箱工具策略
openclaw sandbox explain --agent kb-writer

# 修复：在 sandbox.tools 中添加 bundle-mcp
{
  "tools": {
    "sandbox": {
      "tools": {
        "alsoAllow": ["bundle-mcp"]
      }
    }
  }
}

// ❌ 错误：大小写不匹配
{
  "tools": {
    "alsoAllow": ["Message", "EXEC"]
  }
}

// ✅ 正确
{
  "tools": {
    "alsoAllow": ["message", "exec"]
  }
}

// ❌ 错误：只 deny write，apply_patch 仍然可用
{
  "tools": {
    "deny": ["write"]
  }
}

// ✅ 正确：同时 deny 所有写操作工具
{
  "tools": {
    "deny": ["write", "edit", "apply_patch"]
  }
}

// ✅ 更简洁：deny 整个文件系统组
{
  "tools": {
    "deny": ["group:fs"]
  }
}

# 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d-%H%M%S)

# 验证并重启
openclaw config validate && openclaw gateway restart

# 验证权限状态
openclaw doctor