---
created: "2026-03-22"
type: resource
tags: [resource, openclaw, ai-gateway, architecture, reference, homelab]
source: "https://docs.openclaw.ai/ 系统性整理"
---

# OpenClaw 架构与配置全览

## 概述

OpenClaw 是一个自托管 AI 网关，将 30+ 聊天渠道（WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Matrix, Teams 等）连接到 AI 编码代理。支持 35+ 模型提供商、多 agent 隔离路由、技能/插件扩展、定时任务和 webhook 自动化。

- 配置文件: `~/.openclaw/openclaw.json`（JSON5 格式，热重载）
- 默认端口: `18789`
- 文档: https://docs.openclaw.ai/

## 目录结构

```
~/.openclaw/
├── openclaw.json                    # 主配置文件
├── .env                             # 环境变量
├── workspace/                       # 默认 agent workspace
├── workspace-{agent-id}/            # 各 agent 独立 workspace
│   ├── AGENTS.md                    # 操作指令 + 记忆
│   ├── SOUL.md                      # 人格/边界/语气
│   ├── TOOLS.md                     # 工具使用说明
│   ├── IDENTITY.md                  # 名称/风格
│   ├── USER.md                      # 用户画像
│   ├── BOOTSTRAP.md                 # 一次性引导（运行后删除）
│   ├── MEMORY.md                    # 记忆
│   ├── HEARTBEAT.md                 # 心跳
│   ├── skills/                      # workspace 级技能（最高优先级）
│   │   └── skill-name/SKILL.md
│   └── hooks/                       # workspace 级钩子
├── agents/{agent-id}/
│   ├── agent/                       # agentDir: auth/model 配置
│   │   ├── auth-profiles.json
│   │   └── models.json
│   └── sessions/                    # 会话存储
│       ├── sessions.json
│       └── {session-id}.jsonl
├── skills/                          # managed 技能（中优先级）
│   └── skill-name/SKILL.md
├── hooks/                           # managed 钩子
├── plugins/                         # 已安装插件
├── browser/                         # 浏览器数据
└── xiaohongshu-mcp/                 # Docker 部署的 MCP 服务
```

### 关键区分: workspace vs agentDir

| 目录 | 用途 | 放什么 |
|------|------|--------|
| `workspace-{id}/` | agent 的工作目录 | **所有 .md 文件**、skills/、hooks/ |
| `agents/{id}/agent/` | agent 的状态目录 | auth-profiles.json、models.json |
| `agents/{id}/sessions/` | 会话存储 | 自动生成的 .jsonl 文件 |

**重要**: Bootstrap 文件（AGENTS.md, SOUL.md 等）必须放在 **workspace** 目录，不是 agentDir。agentDir 只放 JSON 配置文件。

## Agent 配置

### 添加 Agent

```json
{
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" },
      "workspace": "~/.openclaw/workspace"
    },
    "list": [
      {
        "id": "agent-id",
        "name": "agent-id",
        "workspace": "/home/yiukai/.openclaw/workspace-agent-id",
        "agentDir": "/home/yiukai/.openclaw/agents/agent-id/agent",
        "model": "kimi-coding/k2p5",
        "identity": { "name": "显示名称" },
        "groupChat": {
          "mentionPatterns": ["<@!?BOT_USER_ID>", "中文名称", "BOT_USER_ID"]
        },
        "subagents": {
          "allowAgents": ["other-agent-id"]
        }
      }
    ]
  }
}
```

### Agent 间通信

默认禁用，需显式启用:

```json
{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["agent-a", "agent-b"]
    }
  }
}
```

## 渠道配置

### Discord

```json
{
  "channels": {
    "discord": {
      "enabled": true,
      "groupPolicy": "allowlist",
      "accounts": {
        "account-id": {
          "name": "显示名称",
          "enabled": true,
          "token": "BOT_TOKEN",
          "groupPolicy": "open",
          "streaming": "off",
          "guilds": {
            "GUILD_ID": {
              "requireMention": false,
              "users": ["OWNER_ID", "BOT_ID"],
              "channels": { "CHANNEL_ID": { "allow": true } }
            }
          }
        }
      }
    }
  }
}
```

#### DM 策略

| 策略 | 说明 |
|------|------|
| `pairing` | 需要配对码（默认） |
| `allowlist` | 仅允许指定用户 |
| `open` | 允许所有 |
| `disabled` | 禁用 DM |

#### Bot 必需权限

View Channels, Send Messages, Read Message History, Embed Links, Attach Files

#### Bot 必需 Intent

Message Content Intent（必须），Server Members Intent（推荐）

### 路由绑定 (Bindings)

将消息路由到特定 agent:

```json
{
  "bindings": [
    {
      "agentId": "agent-id",
      "match": {
        "channel": "discord",
        "accountId": "account-id"
      }
    }
  ]
}
```

匹配优先级: peer > parent-peer > guild+roles > guild > team > account > channel > default

## Skills 技能系统

### 加载优先级（高到低）

1. **Workspace skills**: `<workspace>/skills/skill-name/SKILL.md`
2. **Managed skills**: `~/.openclaw/skills/skill-name/SKILL.md`
3. **Bundled skills**: 内置技能

### SKILL.md 格式

```markdown
---
name: skill-name
description: "一行描述"
homepage: https://example.com
metadata: { "openclaw": { "emoji": "📕", "requires": { "bins": ["curl"] } } }
---

# 技能说明

工具定义和使用指南...
```

### 技能配置

```json
{
  "skills": {
    "entries": {
      "skill-name": { "enabled": true },
      "other-skill": { "enabled": true, "apiKey": "..." }
    },
    "load": { "extraDirs": [], "watch": true }
  }
}
```

## Plugins 插件系统

### 安装

```bash
openclaw plugins install plugin-name          # 从 npm
openclaw plugins install -l ./local-plugin    # 从本地
```

### 插件能力注册

| 能力 | 注册方法 |
|------|---------|
| 文本推理 | `api.registerProvider(...)` |
| 语音 | `api.registerSpeechProvider(...)` |
| 图片生成 | `api.registerImageGenerationProvider(...)` |
| 网络搜索 | `api.registerWebSearchProvider(...)` |
| 消息渠道 | `api.registerChannel(...)` |

### MCP 适配器插件

`openclaw-mcp-adapter` 将 MCP 服务器工具注册为原生 agent 工具:

```json
{
  "plugins": {
    "entries": {
      "openclaw-mcp-adapter": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "server-name",
              "transport": "http",
              "url": "http://localhost:18060/mcp"
            }
          ]
        }
      }
    }
  }
}
```

支持 `stdio`（启动子进程）和 `http`（连接运行中的服务）两种传输方式。

## Hooks 钩子系统

### 事件类型

| 事件 | 触发时机 |
|------|---------|
| `command:new` | /new 命令 |
| `command:reset` | /reset 命令 |
| `command:stop` | /stop 命令 |
| `message:received` | 收到消息 |
| `message:sent` | 发送消息 |
| `agent:bootstrap` | Agent 启动 |
| `gateway:startup` | Gateway 启动 |

### 内置钩子

| 钩子 | 功能 |
|------|------|
| `session-memory` | /new 时保存上下文快照 |
| `bootstrap-extra-files` | 启动时注入额外文件 |
| `command-logger` | 命令审计日志 |
| `boot-md` | 启动时执行 BOOT.md |

## Cron 定时任务

```json
{
  "cron": {
    "enabled": true,
    "entries": [
      {
        "name": "job-name",
        "schedule": "0 8 * * 1-5",
        "timezone": "Europe/Stockholm",
        "agentId": "agent-id",
        "message": "执行任务",
        "deliver": {
          "channel": "discord",
          "target": "channel:CHANNEL_ID"
        }
      }
    ]
  }
}
```

## Subagents 子代理

后台生成独立会话执行任务，完成后报告结果。

```json
{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 1,
        "maxConcurrent": 8,
        "runTimeoutSeconds": 300,
        "allowAgents": ["*"]
      }
    }
  }
}
```

命令: `/subagents list|info|log|kill|spawn|send`

## Session 会话管理

### 作用域

| 模式 | 说明 |
|------|------|
| `main` | 每个 agent 单一 session |
| `per-peer` | 每个发送者独立 |
| `per-channel-peer` | 每个渠道+发送者独立 |
| `per-account-channel-peer` | 完全隔离 |

### 重置

```json
{
  "session": {
    "reset": {
      "mode": "idle",
      "idleMinutes": 120
    }
  }
}
```

## Gateway 配置

```json
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": { "mode": "token", "token": "..." },
    "controlUi": { "enabled": true },
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": false },
        "responses": { "enabled": false }
      }
    }
  }
}
```

### 热重载

三种模式:
- `hybrid`（默认）: 安全变更即时生效，关键变更自动重启
- `hot`: 仅安全变更生效，关键变更需手动重启
- `restart`: 任何变更都重启

## Webhook (外部触发)

```json
{
  "hooks": {
    "enabled": true,
    "token": "shared-secret",
    "path": "/hooks"
  }
}
```

端点:
- `POST /hooks/wake` - 入队系统事件
- `POST /hooks/agent` - 运行隔离的 agent turn
- `POST /hooks/<name>` - 自定义映射钩子

## 环境变量

```json
{
  "env": {
    "API_KEY": "value",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}
```

支持 `${VAR_NAME}` 语法引用环境变量，支持 SecretRef 对象（env/file/exec 来源）。

## 诊断命令

```bash
openclaw doctor [--fix]          # 诊断并修复
openclaw status --deep           # 完整状态审计
openclaw config validate         # 配置校验
openclaw channels status --probe # 渠道连通性检查
openclaw gateway probe           # Gateway 连通性检查
openclaw logs --follow           # 尾随日志
```

## Related

- [[OpenClaw-Skill-Reference]]
- [[OpenClaw 部署配置分析]]
- [[OpenClaw Stock Agent 配置详情]]
- [[OpenClaw Agent 创建指南]]
