OpenClaw 完整配置指南：架构设计、多Agent管理与安全防护

介绍OpenClaw架构设计、多Agent协作管理、安全防护三大核心内容，提供从个人使用到企业级部署的全场景完整配置指南与模板。

一、OpenClaw 概述与设计哲学

1.1 项目背景

在AI Agent爆发的2026年，OpenClaw（前身为ClawdBot/Moltbot）以175k+ GitHub星标成为开源个人AI助手领域的标杆项目。由PSPDFKit创始人Peter Steinberger打造，是一套完整的Agent架构范式，支持完全开源可定制。

OpenClaw的设计核心哲学：

声明式优于命令式：大量使用MD配置文件（AGENTS.md/SOUL.md等）而非硬编码控制行为，易读易维护
分层与模块化：从System Prompt到工具权限均采用分层设计，各层职责清晰
用户可控：默认配置合理，同时所有配置均可被用户覆盖定制
安全优先：多层防御机制，从Prompt护栏到沙箱隔离全方位保障安全
开放扩展：Skills技能系统与插件机制支持无限扩展能力

1.2 核心架构组件

OpenClaw采用”一个Gateway + 多个Channel + 可扩展Agent系统”架构：

Gateway（网关）：控制平面，管理所有消息通道连接，提供WebSocket API
Agent（代理）：独立AI实例，拥有独立上下文、工具集和记忆空间
Channel（通道）：外部交互接口，支持WhatsApp/Telegram/Slack/Discord等
Skill（技能）：可扩展功能模块，通过SKILL.md定义能力边界
Memory（记忆）：持久化存储，支持向量检索和日志记录

1.3 配置文件体系总览

配置文件采用多层级设计：

层级	位置	说明
项目级配置	仓库根目录	.eslintrc/.prettierrc/tsconfig.json等构建规则
Gateway核心配置	~/.openclaw/openclaw.json	运行时核心配置，包含模型、工具、Agent等所有参数
工作空间配置	~/.openclaw/workspace/	Agent运行时文件系统，包含注入式配置文件
环境配置	~/.openclaw/.env	存储敏感信息（API Key/Token等），不进入版本控制
注入式配置	AGENTS.md/SOUL.md/IDENTITY.md/USER.md	直接注入System Prompt，控制Agent行为

二、核心配置模块详解

2.1 身份配置文件

AGENTS.md - 代理行为规范

定义Agent的行为准则、工作流程和编码规范，启动时自动注入System Prompt：

身份定义：明确Agent角色定位
行为准则：交互与任务处理规则
编码规范：技术细节要求
安全边界：禁止行为清单

SOUL.md - 价值观与个性

定义Agent的人格特质，可选配置：

核心价值观：如诚实、专业、友善
沟通风格：正式/随意、简洁/详细
决策原则：模糊需求处理策略
边界意识：人格化的行为边界

IDENTITY.md - 身份档案

存储Agent身份信息：

基本信息：名称、版本、创建时间
形象描述：多模态交互的视觉描述
声音特征：语音交互参数
签名语：标志性问候语

USER.md - 用户画像

存储用户偏好，实现个性化服务：

基本信息：名称、联系方式、时区
技术背景：编程语言偏好、技术栈熟悉度
交互偏好：沟通方式、回复详细程度
隐私设置：数据存储与敏感信息处理规则

2.2 System Prompt 构建机制

采用模块化设计，核心模块包括：

Tooling：可用工具列表
Safety：安全护栏提示
Skills：可用技能列表
OpenClaw Self-Update：自更新操作说明
Workspace：工作目录路径
Documentation：本地文档路径
Sandbox：沙箱运行时信息
Current Date & Time：时区信息
Runtime：主机/OS/模型等运行时信息
Reasoning：推理可见性配置

支持三种Prompt模式：

full模式：默认，包含所有模块，适用于主Agent
minimal模式：子Agent使用，省略非核心模块，节省token
none模式：仅返回基础身份行，用于特殊测试场景

2.3 工具系统配置

工具系统是Agent能力的核心载体，通过openclaw.json的tools字段配置：

{
  "tools": {
    "allow": ["*"],
    "deny": ["browser"],
    "profile": "coding",
    "byProvider": {
      "google-antigravity": {
        "profile": "minimal"
      }
    }
  }
}

内置工具Profile：

minimal：仅允许session_status，最严格限制
coding：允许文件系统、运行时、会话、内存和图像工具
messaging：允许消息相关工具和基本会话管理
full：无限制

工具组简化配置：

group:fs：文件系统工具（read/write/apply_patch等）
group:runtime：运行时工具（exec/process等）
group:sessions：会话管理工具
group:memory：记忆系统工具
group:messaging：消息相关工具

2.4 技能（Skills）系统配置

Skills是OpenClaw的扩展机制，每个Skill是独立目录，包含SKILL.md定义文件和可选代码：

skills/my-skill/
  ├── SKILL.md          # 技能定义（必需）
  ├── index.js          # 技能入口（可选）
  └── utils/            # 辅助文件（可选）

SKILL.md规范包含：技能名称、功能描述、使用场景、调用方式、参数说明、示例。

ClawHub技能注册中心：

{
  "clawhub": {
    "enabled": true,
    "registry": "https://clawhub.openclaw.ai"
  }
}

2.5 记忆系统配置

采用分层记忆设计：

短期记忆：会话上下文
长期记忆：持久化存储，包括每日日志（memory/YYYY-MM-DD.md）和精选记忆（MEMORY.md）

向量搜索配置：

{
  "memory": {
    "backend": "memory-core",
    "embedding": {
      "provider": "local",
      "model": "all-MiniLM-L6-v2"
    }
  }
}

2.6 Gateway 配置

Gateway是系统核心枢纽，配置如下：

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "canvasHost": {
      "enabled": true,
      "port": 18793
    },
    "reload": {
      "mode": "hybrid"
    }
  }
}

热重载模式：

hybrid（默认）：热应用安全变更，关键变更时重启
off：禁用热重载
restart：任何变更都触发重启

三、多Agent 架构与管理

3.1 多Agent设计思想

单Agent模式存在上下文污染、人格冲突、安全隔离不足、无法按需路由等问题，多Agent架构通过”扁平路由模型”解决这些问题，没有管理者Agent，Gateway直接根据消息来源路由到对应Agent。

每个Agent完全独立：

资源	是否共享	说明
工作空间	否	独立工作目录
记忆文件	否	独立MEMORY.md和日志
会话历史	否	完全隔离的对话记录
认证凭证	否	独立auth-profiles.json
技能配置	可选	可配置Agent级技能白名单
AI模型	可选	可指定不同模型

3.2 Agent配置与角色定义

创建Agent：

openclaw agents add coding
openclaw agents add social
openclaw agents add work

Agent核心配置示例：

{
  agents: {
    defaults: {
      model: "anthropic:claude-opus-4-6",
      maxTokens: 8192,
      temperature: 0.7,
    },
    list: [
      {
        agentId: "main",
        workspace: "~/.openclaw/workspace",
        model: "anthropic:claude-opus-4-6",
      },
      {
        agentId: "coding",
        workspace: "~/.openclaw/workspace-coding",
        temperature: 0.3,
        skills: {
          enabled: ["coding-agent", "github", "gh-issues", "tmux"],
        },
        bindings: [
          {
            channel: "discord",
            guildId: "123456789",
            channelId: "987654321",
          },
        ],
      },
      {
        agentId: "social",
        workspace: "~/.openclaw/workspace-social",
        model: "openai:gpt-5.2-mini",
        temperature: 0.9,
        skills: {
          enabled: ["summarize", "weather", "goplaces"],
        },
        bindings: [
          {
            channel: "telegram",
            chatId: "-100123456789",
          },
        ],
      },
    ],
  },
}

每个Agent的工作空间下都有独立的SOUL.md定义其人格、工作规则和沟通风格。

3.3 消息路由与绑定

Gateway路由规则：

检查bindings配置，匹配到则路由到对应Agent
未匹配且是私聊，路由到main Agent
其他情况回退到main Agent

支持的绑定类型：

Discord：指定服务器/频道
Telegram：指定群组/私聊
Slack：指定团队/频道
WhatsApp：指定群组

查看路由状态：

openclaw agents list

3.4 Agent间通信机制

直接通信（Sessions工具）

sessions_list：发现活跃会话
sessions_history：获取会话日志
sessions_send：向另一个会话发消息（支持reply-back ping-pong和announce step模式）
sessions_spawn：生成新会话

间接通信方式

共享文件：公共目录读写
用户中转：手动传递结果
定时任务串联：Cron按顺序执行
Webhook触发：任务完成后调用下一个Agent的Webhook

3.5 任务协作策略

按职能分工：每个Agent负责一个领域（编程/办公/社交/研究）
按平台分工：每个Agent负责一个消息平台
按安全等级分工：按操作风险分配不同权限的Agent
流水线协作：多Agent按顺序处理任务的不同阶段

3.6 实战案例

客服+技术支持双Agent

Community Agent处理#general频道闲聊，用GPT-5.2-mini降低成本
Tech Support Agent处理#support频道技术问题，用Claude Sonnet保证专业度
私聊消息由main Agent处理

内容创作流水线

Translator Agent翻译中文内容
Writer Agent润色英文表达
Reviewer Agent审核内容质量
通过定时任务或共享文件串联流程

四、安全配置与防护

4.1 安全架构概述

采用纵深防御五层安全模型：

网络边界安全：TLS 1.3/防火墙/IP白名单
认证与授权：Gateway Token/配对系统/用户权限
输入验证与过滤：提示词护栏/消息过滤/长度限制
执行隔离：Docker沙箱/文件系统隔离/资源限制
审计与监控：操作日志/异常检测/告警通知

遵循零信任原则：不信任任何输入、任何网络、任何执行，最小权限，持续验证。

4.2 API Key 安全管理

基本原则：永远不要硬编码，使用环境变量存储：

# 方式一：系统环境变量（服务器推荐）
echo 'export OPENAI_API_KEY="sk-proj-xxxxx"' >> ~/.bashrc
source ~/.bashrc

# 方式二：.env文件（开发推荐）
cat > ~/.openclaw/.env << 'EOF'
OPENAI_API_KEY=sk-proj-xxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxx
EOF
chmod 600 ~/.openclaw/.env

密钥轮换策略：每90天轮换一次，泄露时立即撤销并更换。

4.3 沙箱系统配置

沙箱确保Agent执行的命令被隔离在受控环境中：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // non-main/always/never
        toolAllowlist: [
          "bash",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
        ],
        toolDenylist: [
          "browser",
          "canvas",
          "nodes",
          "cron",
          "discord",
          "gateway",
        ],
        securityOpt: ["no-new-privileges:true"],
        capDrop: ["ALL"],
        readOnlyRootfs: true,
        tmpfsSize: "64m",
        noSetuid: true,
      },
    },
  },
}

沙箱模式说明：

non-main：非主会话在Docker沙箱中运行（推荐默认值）
always：所有会话都在沙箱中运行（高安全要求场景）
never：禁用沙箱（仅限开发调试）

4.4 权限控制

Gateway认证（必须设置）

# 生成强随机Token
openssl rand -hex 32
export OPENCLAW_GATEWAY_TOKEN="随机Token"

DM Pairing配对系统（默认启用）

控制谁可以给Agent发私信，默认策略pairing需要手动批准未知发送者：

{
  channels: {
    dmPolicy: "pairing", // pairing/open
  },
}

配对操作：

openclaw pairing approve <channel> <code>  # 批准配对
openclaw pairing list                      # 查看待配对请求
openclaw pairing revoke <contact>          # 撤销配对

用户权限分级

{
  permissions: {
    roles: {
      admin: {
        tools: ["*"],
        agents: ["*"],
        maxTokensPerDay: -1,
        canModifyConfig: true,
      },
      user: {
        tools: ["search", "calendar", "reminder", "weather"],
        agents: ["assistant", "researcher"],
        maxTokensPerDay: 100000,
        canModifyConfig: false,
      },
      guest: {
        tools: ["search", "weather"],
        agents: ["assistant"],
        maxTokensPerDay: 10000,
        canModifyConfig: false,
      },
    },
    userRoles: {
      "my-telegram-id": "admin",
      "friend-telegram-id": "user",
      default: "guest",
    },
  },
}

文件访问权限

{
  filesystem: {
    defaultPolicy: "deny",
    rules: [
      {
        path: "~/.openclaw/workspace",
        permissions: ["read", "write", "create", "delete"],
      },
      {
        path: "~/Documents",
        permissions: ["read"],
      },
      {
        path: "~/.openclaw/openclaw.json",
        permissions: [],
      },
      {
        path: "~/.ssh",
        permissions: [],
      },
    ],
  },
}

4.5 网络安全

TLS 1.3强制启用

{
  gateway: {
    tls: {
      enabled: true,
      minVersion: "1.3",
      certFile: "/path/to/cert.pem",
      keyFile: "/path/to/key.pem",
    },
  },
}

远程访问推荐方案

不要直接暴露Gateway端口，使用：

SSH隧道：ssh -L 18789:127.0.0.1:18789 user@your-server
Tailscale Serve/Funnel：零配置安全隧道
WireGuard VPN

IP白名单与速率限制

{
  gateway: {
    security: {
      ipWhitelist: {
        enabled: true,
        allowedIPs: ["127.0.0.1", "::1", "192.168.1.0/24"],
      },
      rateLimiting: {
        enabled: true,
        maxRequestsPerMinute: 60,
        maxRequestsPerHour: 1000,
        burstSize: 10,
      },
    },
  },
}

4.6 数据隐私保护

静态数据加密

{
  storage: {
    encryption: {
      enabled: true,
      algorithm: "aes-256-gcm",
      keyDerivation: "argon2id",
    },
  },
}

本地模型隐私方案

如果不希望数据发送到第三方AI服务商，使用本地模型：

{
  providers: {
    ollama: {
      type: "ollama",
      baseUrl: "http://127.0.0.1:11434",
      models: ["llama3.1", "qwen2.5"],
    },
  },
  agents: {
    defaults: {
      provider: "ollama",
      model: "llama3.1",
    },
  },
}

4.7 日志审计

{
  logging: {
    audit: {
      enabled: true,
      level: "info",
      file: "~/.openclaw/logs/audit.log",
      maxSize: "100m",
      maxFiles: 30,
      compress: true,
      events: [
        "auth.success",
        "auth.failure",
        "pairing.request",
        "pairing.approve",
        "tool.execute",
        "tool.blocked",
        "config.change",
        "injection.detected",
      ],
    },
  },
}

4.8 安全最佳实践清单

必须做（CRITICAL）

强烈建议（HIGH）

防火墙已配置，端口不对外暴露
使用SSH隧道/VPN远程访问
审计日志已启用
速率限制已配置
文件访问权限defaultPolicy为deny
禁用不需要的工具
Webhook签名验证已启用

五、最终完整配置模板

// ~/.openclaw/openclaw.json 最终版完整配置
{
  // Gateway配置
  gateway: {
    host: "127.0.0.1",
    port: 18789,
    canvasHost: {
      enabled: true,
      port: 18793,
    },
    reload: {
      mode: "hybrid",
    },
    auth: {
      mode: "token",
    },
    tls: {
      enabled: true,
      minVersion: "1.3",
      certFile: "/etc/letsencrypt/live/your-domain.com/fullchain.pem",
      keyFile: "/etc/letsencrypt/live/your-domain.com/privkey.pem",
    },
    security: {
      ipWhitelist: {
        enabled: true,
        allowedIPs: ["127.0.0.1", "::1", "192.168.1.0/24"],
      },
      rateLimiting: {
        enabled: true,
        maxRequestsPerMinute: 60,
        maxRequestsPerHour: 1000,
        burstSize: 10,
      },
    },
  },

  // 模型与Provider配置
  agents: {
    defaults: {
      model: "anthropic:claude-opus-4-6",
      fallbackModels: ["openai/gpt-4.5", "google/gemini-pro"],
      maxTokens: 8192,
      temperature: 0.7,
      sandbox: {
        mode: "non-main",
        toolAllowlist: [
          "bash",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
        ],
        toolDenylist: [
          "browser",
          "canvas",
          "nodes",
          "cron",
          "discord",
          "gateway",
        ],
        securityOpt: ["no-new-privileges:true"],
        capDrop: ["ALL"],
        readOnlyRootfs: true,
        tmpfsSize: "64m",
        noSetuid: true,
      },
      systemPrompt: {
        guardrails: true,
        maxLength: 10000,
        injection: {
          detection: true,
          action: "block",
          logAttempts: true,
        },
      },
    },
    list: [
      {
        agentId: "main",
        workspace: "~/.openclaw/workspace",
        model: "anthropic:claude-opus-4-6",
      },
      {
        agentId: "coding",
        workspace: "~/.openclaw/workspace-coding",
        temperature: 0.3,
        skills: {
          enabled: ["coding-agent", "github", "gh-issues", "tmux"],
        },
        bindings: [
          {
            channel: "discord",
            guildId: "123456789",
            channelId: "987654321",
          },
        ],
      },
      {
        agentId: "social",
        workspace: "~/.openclaw/workspace-social",
        model: "openai:gpt-5.2-mini",
        temperature: 0.9,
        skills: {
          enabled: ["summarize", "weather", "goplaces"],
        },
        bindings: [
          {
            channel: "telegram",
            chatId: "-100123456789",
          },
        ],
      },
      {
        agentId: "work",
        workspace: "~/.openclaw/workspace-work",
        model: "anthropic:claude-sonnet-4-6",
        skills: {
          enabled: ["gog", "slack", "notion", "trello", "summarize"],
        },
        bindings: [
          {
            channel: "slack",
            teamId: "T01234567",
            channelId: "C01234567",
          },
        ],
      },
    ],
  },

  // 工具配置
  tools: {
    profile: "coding",
    deny: ["browser"],
    byProvider: {
      "google-antigravity": {
        profile: "minimal",
      },
    },
    permissions: {
      shell: {
        enabled: false,
        allowedUsers: ["admin"],
        requireConfirmation: true,
        blockedCommands: [
          "rm -rf",
          "dd if=",
          "mkfs",
          "shutdown",
          "reboot",
          "curl.*|.*sh",
          "wget.*|.*sh",
        ],
      },
      fileWrite: {
        enabled: true,
        allowedPaths: ["~/.openclaw/workspace/**"],
        blockedPaths: [
          "~/.openclaw/openclaw.json",
          "~/.ssh/**",
          "~/.gnupg/**",
          "/etc/**",
          "/usr/**",
        ],
        maxFileSize: "10m",
      },
      fileRead: {
        enabled: true,
        allowedPaths: ["~/.openclaw/workspace/**", "~/Documents/**"],
        blockedPaths: [
          "~/.openclaw/.env",
          "~/.openclaw/credentials",
          "~/.ssh/**",
          "~/.gnupg/**",
          "/etc/shadow",
          "/etc/passwd",
        ],
      },
      httpRequest: {
        enabled: true,
        allowedDomains: ["api.openai.com", "api.anthropic.com"],
        blockedDomains: ["*.onion", "localhost", "127.0.0.1"],
        maxRequestsPerMinute: 30,
      },
    },
  },

  // 技能注册中心
  clawhub: {
    enabled: true,
    registry: "https://clawhub.openclaw.ai",
  },

  // 记忆系统
  memory: {
    backend: "memory-core",
    embedding: {
      provider: "local",
      model: "all-MiniLM-L6-v2",
    },
  },

  // 通道配置
  channels: {
    dmPolicy: "pairing",
    telegram: {
      security: {
        verifyWebhook: true,
        secretToken: "your-webhook-secret",
        allowedUpdates: ["message", "callback_query"],
      },
    },
    discord: {
      security: {
        verifySignature: true,
        publicKey: "your-discord-public-key",
      },
    },
  },

  // 文件系统权限
  filesystem: {
    defaultPolicy: "deny",
    rules: [
      {
        path: "~/.openclaw/workspace",
        permissions: ["read", "write", "create", "delete"],
      },
      {
        path: "~/Documents",
        permissions: ["read"],
      },
      {
        path: "~/Downloads",
        permissions: ["read"],
      },
      {
        path: "~/.openclaw/openclaw.json",
        permissions: [],
      },
      {
        path: "~/.openclaw/credentials",
        permissions: [],
      },
      {
        path: "~/.ssh",
        permissions: [],
      },
    ],
  },

  // 用户权限
  permissions: {
    roles: {
      admin: {
        tools: ["*"],
        agents: ["*"],
        maxTokensPerDay: -1,
        canModifyConfig: true,
      },
      user: {
        tools: ["search", "calendar", "reminder", "weather"],
        agents: ["assistant", "researcher"],
        maxTokensPerDay: 100000,
        canModifyConfig: false,
      },
      guest: {
        tools: ["search", "weather"],
        agents: ["assistant"],
        maxTokensPerDay: 10000,
        canModifyConfig: false,
      },
    },
    userRoles: {
      "my-telegram-id": "admin",
      "friend-telegram-id": "user",
      default: "guest",
    },
  },

  // 存储与加密
  storage: {
    encryption: {
      enabled: true,
      algorithm: "aes-256-gcm",
      keyDerivation: "argon2id",
    },
    retention: {
      chatHistory: "90d",
      auditLogs: "365d",
      memories: "forever",
      tempFiles: "7d",
    },
  },

  // 日志审计
  logging: {
    audit: {
      enabled: true,
      level: "info",
      file: "~/.openclaw/logs/audit.log",
      maxSize: "100m",
      maxFiles: 30,
      compress: true,
      events: [
        "auth.success",
        "auth.failure",
        "pairing.request",
        "pairing.approve",
        "tool.execute",
        "tool.blocked",
        "config.change",
        "agent.create",
        "agent.delete",
        "injection.detected",
      ],
    },
  },

  // 定时任务
  schedules: [
    {
      name: "health-check",
      cron: "*/30 * * * *",
      agentId: "devops",
      prompt: "执行服务器健康检查，如果发现异常，通过Slack通知#ops频道",
    },
    {
      name: "daily-report",
      cron: "0 18 * * *",
      agentId: "devops",
      prompt: "生成今日运维日报，发送到Slack #ops频道",
    },
  ],
}

六、总结

OpenClaw的配置体系从设计之初就兼顾了易用性、灵活性和安全性。通过本指南，你可以：

理解OpenClaw的核心设计思想和架构
配置多Agent协作系统，实现任务分流和专业分工
搭建完整的安全防护体系，防范各类安全威胁
使用最终配置模板快速部署适合自己场景的OpenClaw实例

建议根据实际使用场景裁剪配置，优先保障安全配置项，定期运行openclaw doctor检查配置健康状态。