openclaw组成与配置简介

OpenClaw 是一款本地运行的开源个人 AI Agent 平台 ，核心思路是把 LLM（大脑）放进一个有会话管理、工具沙箱、消息路由、长期记忆的完整运行系统。下面从架构组件 和配置文件详解两个维度说明。

---

一、核心架构组件

OpenClaw 采用「入口层 → 控制平面(Gateway) → 执行平面(Agent) → 能力层」的分层架构：

组件	定位	说明
Channels（渠道适配器）	入口层	对接 WhatsApp/Telegram/Discord/飞书/Slack/iMessage 等 IM 平台，统一做认证、消息解析、白名单过滤、出站格式化
Gateway（网关）	控制平面	系统的中枢，长期运行的 WS/HTTP 服务（默认 127.0.0.1:18789），负责连接 Channel 与 Agent、鉴权、会话路由(lane/queue)、事件广播、热加载配置
Agent（智能体运行时）	执行平面	每个 Agent 有独立 workspace/Memory/SOUL.md，接收路由后的消息→组装上下文→调 LLM→执行 Tools（Browser/Exec/Web...）→流式输出回复
Tools & Skills	能力层	Tools 是内置能力（文件读写、终端执行、浏览器自动化、Web 搜索等）；Skills 是可扩展的外部功能插件（邮件、日历、自定义 API）
Providers（模型供应商）	模型调度	抽象层支持 Anthropic/OpenAI/Google/DeepSeek/本地 Ollama 等，按 provider/model 寻址，支持主备 fallback
Memory（记忆系统）	数据层	默认 SQLite 存储对话历史与长期记忆，可替换为向量数据库插件
Cron / Heartbeat	自动化	Cron 定时任务、Heartbeat 让 Agent 定期主动"醒来"执行指定流程

💡 多 Agent 模式下，每个 Agent 有独立 workspace（SOUL.md、USER.md、AGENTS.md、MEMORY.md 等），通过 Bindings 路由不同 Channel/Sender 到不同 Agent。

---

二、配置文件结构与位置

主配置文件：~/.openclaw/openclaw.json（支持 JSON5 格式，可写注释）

最小可用配置示例：

{
  // Agent 默认设置
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-sonnet-4-5",
        "fallbacks": ["openai/gpt-4o"]
      }
    }
  },
  // 渠道------这里只允许指定手机号跟你对话
  "channels": {
    "whatsapp": { "enabled": true, "allowFrom": ["+86138xxxxxxxxx"] },
    "telegram": { "enabled": true, "botToken": "123:ABC...", "dmPolicy": "pairing" }
  },
  // Gateway 网络配置（默认端口 18789）
  "gateway": { "host": "127.0.0.1", "port": 18789 }
}

---

三、各配置段详解

1. models --- 模型供应商（Provider）

"models": {
  "providers": {
    "anthropic": { "apiKey": "sk-ant-xxx" },
    "openai":    { "apiKey": "sk-xxx" },
    "deepseek":  { "apiKey": "sk-xxx" },
    "ollama":    { "baseURL": "http://127.0.0.1:11434/v1" }
  }
}

模型引用格式 provider/model，如 anthropic/claude-sonnet-4-5、ollama/qwen2.5:7b。

2. agents --- 智能体与多 Agent

"agents": {
  "defaults": {
    "model": { "primary": "anthropic/claude-sonnet-4-5" },
    "workspace": "~/.openclaw/workspace",
    "thinking": { "enabled": false },       // 扩展思考
    "heartbeat": { "enabled": true, "every": "30m" },
    "memorySearch": { "enabled": true }
  },
  // 多 Agent（可选）
  "list": [
    {
      "id": "stock",
      "workspace": "~/.openclaw/workspace-stock",
      "model": { "primary": "openai/gpt-4o" }
    }
  ],
  // 路由：哪个 channel/sender 用哪个 agent
  "multiAgent": {
    "bindings": [
      { "channel": "telegram", "sender": "tg:123456", "agent": "stock" }
    ]
  }
}

每个 Agent workspace 下的关键文件：

workspace/
├── AGENTS.md      # Agent 人设、职责说明（系统提示核心）
├── SOUL.md        # 性格/语气风格
├── USER.md        # 用户画像与偏好
├── IDENTITY.md    # 身份与操作边界
├── TOOLS.md       # 注册/描述可用工具
├── HEARTBEAT.md   # 心跳唤醒时的指令
├── memory/        # 向量/SQLite 长期记忆
└── skills/        # 项目级自定义技能（最高优先级）

3. channels --- 消息渠道

"channels": {
  "telegram": {
    "enabled": true,
    "botToken": "123456:ABC...",
    "dmPolicy": "pairing",     // pairing(需审批) | allowlist | open | disabled
    "allowFrom": ["tg:123456"]
  },
  "whatsapp": {
    "enabled": true,
    "allowFrom": ["+86138xxxxxxxxx"],
    "groups": { "*": { "requireMention": true } }
  },
  "discord": { "enabled": true, "botToken": "..." }
}

4. tools --- 工具权限与安全沙箱

"tools": {
  "profile": "coding",     // minimal | coding | full
  "deny": ["browser"],     // 拒绝优先
  "elevated": {
    "enabled": true,
    "allowFrom": { "whatsapp": ["+86138xxxxxxxxx"] }
  },
  "exec": { "timeoutSec": 1800 },
  "web": {
    "search": { "enabled": true, "apiKey": "${BRAVE_API_KEY}" },
    "fetch": { "enabled": true }
  }
}

工具分组：group:fs（文件）、group:runtime（exec）、group:web、group:sessions、group:memory 等，可按 Provider/Sender 细粒度控制。

5. skills --- 技能扩展

"skills": {
  "allowBundled": ["peekaboo"],
  "load": { "extraDirs": ["~/Projects/my-skills"] },
  "entries": {
    "email": { "enabled": true },
    "calendar": { "enabled": false }
  }
}

加载优先级：Workspace skills/ > ~/.openclaw/skills/ > 内置 Bundled。

6. mcp --- MCP Server 接入

"mcp": {
  "servers": {
    "fetch": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"] }
  }
}

7. gateway --- 网关基础

"gateway": {
  "host": "127.0.0.1",
  "port": 18789,
  "auth": { "token": "your-admin-token" }  // 远程访问时建议配置
}

---

四、常用管理命令

openclaw onboard          # 交互式初始化向导
openclaw gateway start    # 启动网关
openclaw gateway status   # 查看状态
openclaw dashboard        # 打开 Web UI (http://127.0.0.1:18789)
openclaw config get agents.defaults.model
openclaw config set agents.defaults.heartbeat.every "1h"
openclaw doctor           # 健康检查与排错

配置文件修改后会热加载（Hot Reload），Gateway 自动应用新配置。

---