Part 1: 开篇 —— 为什么 OpenClaw 突然火了

1.1 AI应用演进时间线：从被动响应到主动执行

2022-2026：AI应用架构五次范式转变

范式转变的本质：从"被动响应"到"主动执行"

用户视角的转变

传统ChatBot体验：

用户：早上9点打开ChatGPT网页
用户：输入 "帮我查一下今天的日程"
ChatGPT：返回日程列表
用户：关闭网页
ChatGPT：停止运行，等待下次触发

OpenClaw体验：

Gateway：早上9点主动巡查
Gateway：发现今天有重要会议
Agent：主动发送飞书消息："早安！今天10:00有产品评审会议，请提前准备材料"
用户：收到提醒，无需主动询问
Gateway：继续巡查下一个任务...

1.2 三大爆火原因深度剖析

原因一：24小时不间断工作

技术实现：Gateway守护进程 + 心跳巡查机制

心跳巡查的具体内容：

原因二：信任权限高（本地部署，数据不出厂）

为什么信任重要？

OpenClaw的数据隐私保护机制：

企业级场景的信任需求：

原因三：社区生态好（开源+技能市场+活跃社区）

MIT开源的优势：

ClawHub技能市场：

1.3 OpenClaw 核心定位：

定义解析

OpenClaw 是一个自托管的多渠道AI智能体网关，将你常用的聊天应用连接到AI编码代理，实现24小时不间断的智能助手服务。

拆解理解：

类比理解：智能电网模型

1.4 全维度对比分析：OpenClaw vs 其他方案

对比维度矩阵

1.5 核心价值主张总结

OpenClaw 解决的核心痛点

用户视角的完整体验闭环

Part 2: 总体架构 —— 五层模型解析

2.1 五层架构全景图

五层金字塔模型详解

OpenClaw采用分层架构设计：

各层职责详解

2.2 Gateway-centric 设计哲学

核心设计原则：单控制平面

设计格言：

为什么必须是单Gateway？

Gateway架构模型

Wire Protocol：简单但类型化

协议设计原则：

• 不用binary protocol（orchestration系统不需要那点latency gain）
• Text frames with JSON payloads（易debug）
• TypeBox → JSON Schema → Swift codegen（end-to-end typed）

协议格式：

// Request（客户端发起）
{
  "type": "req",
  "id": "abc123",
  "method": "agent",
  "params": {
    "message": "帮我查一下飞书文档",
    "sessionId": "session-xxx"
  }
}

// Response（服务端返回）
{
  "type": "res",
  "id": "abc123",
  "ok": true,
  "payload": {
    "assistantTexts": ["已找到文档..."],
    "toolMetas": [...]
  }
}

// Event（服务端推送）
{
  "type": "event",
  "event": "agent",
  "payload": {
    "sessionId": "session-xxx",
    "status": "running"
  },
  "seq": 42
}

2.3 数据流向完整解析

完整数据流路径

完整数据流（用户消息到结果反馈）：

1. 用户发送消息
   ↓
2. Channel Provider接收
   → 飞书WebSocket接收消息
   → Telegram Bot API接收消息
   ↓
3. Gateway消息路由
   → 解析消息来源（用户ID、群组ID）
   → 根据bindings匹配Agent
   → 创建/复用Session
   ↓
4. Agent会话处理
   → 加载历史记忆
   → 构建System Prompt
   → 加载Skills
   ↓
5. LLM推理
   → 发送到Claude/GPT/GLM API
   → 接收流式响应
   → 解析tool_use
   ↓
6. 工具调用循环
   → 执行工具函数（如read、browser）
   → 获取工具结果
   → 继续LLM推理
   ↓
7. 结果生成
   → 整合assistantTexts
   → 收集toolMetas
   → 计算usage统计
   ↓
8. Gateway记忆刷盘
   → 写入session transcript
   → 提取关键信息到MEMORY.md
   → 写入memory/YYYY-MM-DD.md
   ↓
9. 消息回复
   → 通过Channel Provider发送
   → 支持富文本、图片、文件
   ↓
10. 用户收到回复

并发与队列控制

Session Lane机制：

Session Lane（会话车道）：

每个Session有一个独立的车道（Lane）

Session A → Lane A → 串行执行所有runs
Session B → Lane B → 串行执行所有runs
Session C → Lane C → 串行执行所有runs

防止同一Session内的并发冲突

Global Lane（可选）：

Global Lane（全局车道）：

跨Session的并发控制
防止过多Agent同时运行LLM调用

配置示例：
{
  agents: {
    globalLane: {
      maxConcurrent: 5,  // 最多5个Agent同时运行
      queueSize: 100      // 队列容量100
    }
  }
}

2.4 Gateway连接握手流程

完整握手协议

Scope权限控制：

2.5 Gateway常用命令详解

状态查看命令

# 查看Gateway基本状态
openclaw gateway status

输出示例：
┌─────────────────────────────────┐
│ Gateway Status                   │
│                                  │
│ Status:     Running              │
│ Port:       18789                │
│ Uptime:     3d 12h 30m           │
│ Agents:     2 running            │
│ Sessions:   15 active            │
│ Channels:   3 connected          │
│                                  │
└─────────────────────────────────┘

# 深度检查（包含详细诊断）
openclaw gateway status --deep

输出示例：
┌─────────────────────────────────┐
│ Deep Gateway Status              │
│                                  │
│ WebSocket Connections:           │
│   - macOS App: Connected         │
│   - iOS Node: Connected          │
│                                  │
│ Channel Providers:               │
│   - Feishu: Connected ✓          │
│   - Telegram: Connected ✓        │
│   - Discord: Disconnected ✗     │
│                                  │
│ Agent Instances:                 │
│   - main: Running, 8 sessions    │
│   - work: Running, 3 sessions    │
│                                  │
│ Memory:                          │
│   - Total: 1.2GB                 │
│   - Sessions: 800MB              │
│                                  │
│ Errors (last 24h):               │
│   - 2 rate limit errors          │
│   - 1 timeout                    │
│                                  │
└─────────────────────────────────┘

健康检查命令

# Gateway健康检查
openclaw gateway health

输出示例：
Gateway health check:
  ✓ Gateway process running
  ✓ WebSocket server responsive
  ✓ HTTP API responsive
  ✓ Channels connected (2/3)
  ✓ Agents healthy
  ✓ Memory usage normal
  
Status: HEALTHY

# 渠道状态检查
openclaw channels status --probe

输出示例：
Channel Status:
  Feishu:
    ✓ WebSocket connected
    ✓ Message receive OK
    ✓ Message send OK
    Last message: 2 minutes ago
    
  Telegram:
    ✓ Bot API connected
    ✓ Polling active
    Last message: 5 minutes ago
    
  Discord:
    ✗ Gateway disconnected
    Error: Token expired
    Action needed: Refresh token

日志查看命令

# 实时日志跟踪
openclaw logs --follow

输出示例：
2026-04-24 00:00:00 [INFO] Gateway heartbeat check
2026-04-24 00:00:05 [INFO] Session main:user:ou_xxx received message
2026-04-24 00:00:10 [INFO] Agent started reasoning
2026-04-24 00:00:15 [INFO] Tool call: feishu_fetch_doc
2026-04-24 00:00:20 [INFO] Tool result: doc content retrieved
2026-04-24 00:00:25 [INFO] Agent generated response
2026-04-24 00:00:30 [INFO] Message sent to Feishu

# 错误日志过滤
openclaw logs --filter error

# 最近100条日志
openclaw logs --limit 100

Part 3: 核心16模块

3.1 Gateway网关核心模块

Gateway六大核心功能详解

功能一：不关机（守护进程）

技术实现：

Gateway Daemon 代码逻辑（简化版）：

async function main() {
  // 初始化
  const gateway = await initializeGateway();
  
  // 无限循环
  while (true) {
    try {
      // 心跳检查
      await heartbeatCheck();
      
      // 处理消息队列
      await processMessageQueue();
      
      // 执行Cron任务
      await executeCronJobs();
      
      // 刷盘记忆
      await flushMemory();
      
      // 等待下一个周期
      await sleep(config.heartbeatInterval);
      
    } catch (error) {
      // 错误处理
      await handleError(error);
      
      // 自动恢复
      if (shouldRestart(error)) {
        await restartGateway();
      }
    }
  }
}

配置参数：

{
  gateway: {
    daemon: {
      enabled: true,
      heartbeatInterval: 300000,  // 5分钟
      autoRestart: true,
      maxRestartAttempts: 3
    }
  }
}

功能二：连接平台（多渠道接入）

渠道架构：

渠道特性对比表：

功能三：会话隔离

隔离机制：

配置示例：

{
  session: {
    dmScope: "per-channel-peer",  // DM隔离策略
    groupScope: "per-channel-group",  // 群聊隔离策略
    
    // Session过期策略
    reset: {
      daily: { hour: 4 },  // 每天4:00重置
      idleMinutes: 120     // 120分钟无活动重置
    }
  }
}

功能四：排队控制

Task Queue架构：

功能五：心跳巡查

心跳检查内容详解：

心跳配置示例：

{
  gateway: {
    heartbeat: {
      enabled: true,
      interval: 300000,  // 5分钟
      
      checks: [
        { type: "messages", interval: 300000 },
        { type: "calendar", interval: 600000 },
        { type: "cron", interval: 60000 },
        { type: "system", interval: 1800000 }
      ]
    }
  }
}

功能六：记忆刷盘

记忆存储流程：

记忆刷盘流程：

实时交互
  ↓
短期记忆（Session Transcript）
  → 存储在内存中
  → 实时记录所有消息、工具调用、结果
  ↓
定期刷盘（每1分钟）
  ↓
长期记忆文件
  → memory/YYYY-MM-DD.md（每日记忆）
  → MEMORY.md（关键信息提取）
  ↓
会话重启恢复
  → 加载MEMORY.md
  → 加载最近的daily memory
  → 恢复上下文

存储内容详解：

3.2 Agentic Loop 推理循环

推理循环核心架构

四层架构：

详细流程解析

单次推理尝试完整流程：

runEmbeddedAttempt() 详细流程：

工具调用循环详解

工具循环工作原理：

关键调用链

完整调用链（从用户消息到结果）：

用户消息
  ↓
runAgentTurnWithFallback()
  (agent-runner-execution.ts)
  ↓
runEmbeddedPiAgent()
  (pi-embedded-runner/run.ts)
  ↓ [while循环 - 重试]
runEmbeddedAttempt()
  (pi-embedded-runner/run/attempt.ts)
  ↓
createAgentSession()
  + activeSession.prompt()
  ↓ [LLM调用 + 工具循环]
subscribeEmbeddedPiSession()
  (pi-embedded-subscribe.ts)
  ↓
事件分发
  → message_start/update/end
  → tool_execution_*
  ↓
返回payloads

工具调用循环（Tool Loop）：

工具调用循环（Tool Loop）：

LLM Response (包含 tool_use)
  ↓
SDK识别 tool_use
  ↓
handleToolExecutionStart
  → 解析工具名称、参数
  → 检查工具是否在allowlist
  → 检查是否需要approval
  ↓
Execute Tool Function
  → 执行具体工具函数
  → 可能是read、exec、browser等
  ↓
handleToolExecutionUpdate
  → 流式报告执行进度
  ↓
handleToolExecutionEnd
  → 收集工具结果
  → 格式化为tool_result
  ↓
添加 tool_result 到历史
  ↓
继续调用 LLM
  → LLM看到工具结果
  → 可能继续调用工具
  → 或生成最终回复
  ↓
循环继续...

3.3 Channels多渠道系统

渠道全景分类

三大类渠道：

渠道配置详解

飞书渠道配置：

{
  channels: {
    feishu: {
      enabled: true,
      
      // 应用配置
      appId: "cli_xxx",
      appSecret: "xxx",
      
      // DM访问策略
      dmPolicy: "allowlist",  // 或 pairing/open/disabled
      allowFrom: ["ou_xxx", "ou_yyy"],
      
      // 群聊配置
      groups: {
        "*": { requireMention: true },  // 所有群需@提及
        "oc_xxx": { requireMention: false }  // 特定群无需@
      },
      
      // 消息配置
      messages: {
        mentionPatterns: ["@OpenClaw", "openclaw"],
        replyQuoted: true  // 支持引用回复
      }
    }
  }
}

DM配对策略详解

配对流程：

DM配对流程（pairing策略）：

未知发送者发送消息
  ↓
Gateway检测到未知ID
  ↓
发送配对请求
  → "你是谁？请输入配对码以验证身份"
  → 显示6位配对码（如123456）
  ↓
用户输入配对码
  ↓
Gateway验证
  → 配对码正确 → 批准配对
  → 配对码错误 → 拒绝或重试
  ↓
批准后
  → 添加到trusted list
  → 允许后续对话

管理员手动批准：
openclaw pairing approve feishu 123456

3.4 Nodes设备节点系统

Nodes架构详解

Node概念：Node = 设备（IOS、Android，PC），连接Gateway WebSocket，暴露命令表面。

Node类型与能力

Node命令表面详解

Part 4: 核心16模块详解

4.1 Tools工具三层架构

三层架构详解

Layer 1: Built-in Tools（内置工具）

Layer 2: Skills（技能系统）

Skills = 基础工具 + 专业知识 + 工作流程

Layer 3: External Tools（外部工具）

4.2 Skills技能系统详解

Skills核心公式

Skills加载优先级

Skills加载顺序（从高到低优先级）：

1. <workspace>/skills
   → 工作区技能（项目特定）
   → 最高优先级
   
2. <workspace>/.agents/skills
   → 项目Agent技能
   → 项目团队共享
   
3. ~/.agents/skills
   → 个人Agent技能
   → 个人私有
   
4. ~/.openclaw/skills
   → 托管技能
   → 从ClawHub安装
   
5. bundled skills
   → 内置技能
   → OpenClaw自带
   
6. skills.load.extraDirs
   → 额外目录
   → 自定义位置

同一技能名，优先级高的覆盖低的

Skills文件格式详解

---
name: github
description: GitHub操作技能 - issue/PR/CI管理
metadata: {
  "openclaw": {
    "requires": {
      "bins": ["gh"],      // 需要gh CLI
      "env": ["GITHUB_TOKEN"]  // 需要环境变量
    },
    "homepage": "https://clawhub.ai/skills/github"
  }
}
---

# GitHub操作技能

使用 gh CLI 进行 GitHub 操作。

## 使用场景
- 创建/管理 GitHub Issue
- 提交/审核 Pull Request
- 查看 CI/CD 运行状态
- 搜索代码仓库

## 工具列表
- gh issue create/list/view
- gh pr create/list/merge
- gh run list/view

## 工作流程

### 创建Issue
1. 确认Issue标题和描述
2. 构建gh命令：gh issue create --title "..." --body "..."
3. 执行命令
4. 解析结果，返回Issue URL

### 提交PR
1. 确认分支名称和目标
2. gh pr create --base main --head feature-xxx
3. 添加reviewers
4. 返回PR URL

## 注意事项
- 需要先配置GITHUB_TOKEN
- 确保gh CLI已安装
- 注意权限控制

4.3 Session会话管理详解

Session Key格式解析

Session Key格式：
agent:<agentId>:<mainKey>

mainKey类型：
- user:<openId>         // DM私聊
- chat:<chatId>         // 群聊
- thread:<threadId>     // 话题
- guild:<guildId>       // Discord服务器
- account:<accountId>   // 账户级别

示例：
agent:main:user:ou_xxx           → 主Agent与用户ou_xxx的私聊
agent:work:chat:oc_xxx           → Work Agent与群oc_xxx的群聊
agent:family:thread:omt_xxx      → Family Agent在话题omt_xxx中
agent:main:guild:discord_xxx     → 主Agent在Discord服务器中

Session路由规则

Session生命周期

Session生命周期：

创建
  → 用户首次发送消息
  → Gateway创建Session
  → 分配Session Key
  
复用
  → 同一用户/群组再次发消息
  → 复用已有Session
  → 加载历史记忆
  
运行
  → Agent处理消息
  → 调用工具
  → 生成回复
  → 刷盘记忆
  
过期
  → 触发重置条件
  → Daily reset（每天4:00）
  → Idle reset（120分钟无活动）
  
销毁
  → Session过期后
  → 清理session transcript
  → 保留MEMORY.md（长期记忆）

4.4 Memory记忆管理详解

Memory存储结构

Memory刷盘机制

刷盘流程：

实时记录
  → 每条消息、工具调用、结果
  → 写入Session Transcript
  → 内存中
  
定期刷盘（每1分钟）
  → Session Transcript写入sessions/<id>.jsonl
  → 提取关键信息写入memory/YYYY-MM-DD.md
  → 重要决策、用户偏好写入MEMORY.md
  
会话重启
  → 加载MEMORY.md（长期记忆）
  → 加载最近3天的memory/YYYY-MM-DD.md
  → 恢复上下文

4.5 Cron定时任务系统详解

Cron任务类型

调度模式详解

投递方式详解

Cron配置完整示例

{
  cron: {
    jobs: [
      // 早间提醒（工作日9点）
      {
        name: "早间提醒",
        schedule: { kind: "cron", expr: "0 9 * * 1-5", tz: "Asia/Shanghai" },
        payload: { 
          kind: "systemEvent", 
          text: "早安！今日日程提醒：检查邮件和日程安排" 
        },
        delivery: { mode: "announce" },
        sessionTarget: "main"
      },
      
      // 每日日报（每天18点）
      {
        name: "每日日报",
        schedule: { kind: "cron", expr: "0 18 * * *", tz: "Asia/Shanghai" },
        payload: { 
          kind: "agentTurn", 
          message: "生成今日工作日报并发送到飞书群",
          timeoutSeconds: 300
        },
        delivery: { mode: "announce", channel: "feishu", to: "oc_xxx" },
        sessionTarget: "isolated"
      },
      
      // 每小时数据监控
      {
        name: "数据监控",
        schedule: { kind: "every", everyMs: 3600000 },
        payload: { 
          kind: "agentTurn", 
          message: "检查关键数据指标，如有异常发送告警"
        },
        delivery: { mode: "webhook", to: "https://api.example.com/callback" },
        sessionTarget: "isolated"
      }
    ]
  }
}

Part 5: 安全机制 —— 沙箱隔离与权限设计

5.1 安全设计哲学

核心原则：Strong defaults + Explicit knobs

设计权衡：

5.2 Sandbox沙箱机制详解

Docker隔离架构

Sandbox配置详解

{
  sandbox: {
    enabled: true,
    
    // Docker配置
    dockerImage: "openclaw-sandbox:latest",
    dockerOptions: {
      memory: "512m",
      cpuShares: 512
    },
    
    // 工具策略
    toolPolicy: {
      browser: "deny",        // 禁止浏览器
      exec: "allowlist",      // 仅允许白名单命令
      system: "deny",         // 禁止系统命令
      canvas: "deny"          // 禁止Canvas
    },
    
    // 命令白名单
    execAllowlist: [
      "/usr/bin/git",
      "/usr/bin/node",
      "/usr/bin/npm",
      "/usr/bin/python3"
    ],
    
    // 文件访问限制
    fsPolicy: {
      allowPaths: [
        "/tmp/sandbox",
        "/workspace/sandbox"
      ],
      denyPaths: [
        "~/.openclaw",
        "~/.ssh"
      ]
    }
  }
}

5.3 DM Policy详解

四种Policy对比

配置示例

{
  channels: {
    // 飞书：白名单策略
    feishu: {
      dmPolicy: "allowlist",
      allowFrom: [
        "ou_ee09fa76de1e9e130bf6c3857034674a",  // 军哥
        "ou_xxx",  // 其他团队成员
        "ou_yyy"
      ]
    },
    
    // Telegram：配对策略
    telegram: {
      dmPolicy: "pairing",
      pairingTimeout: 60000  // 配对码有效期60秒
    },
    
    // Discord：仅群聊
    discord: {
      dmPolicy: "disabled",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

5.4 Tool Approval Gates

工具批准机制

需要批准的操作类型：

配置示例

{
  tools: {
    exec: {
      security: "ask",        // 执行前询问
      ask: "elevated",        // 提升权限命令需批准
      
      // 白名单命令（无需批准）
      allowlist: [
        "git status",
        "git log",
        "ls",
        "cat"
      ],
      
      // 黑名单命令（禁止）
      denylist: [
        "rm -rf",
        "sudo rm",
        "format"
      ]
    }
  }
}

Part 6: 企业级智能体演进

6.1 Multi-Agent架构详解

Multi-Agent核心概念

一个Gateway运行多个隔离Agent：

Multi-Agent架构：

Gateway进程
  ├── Agent: main
  │   ├── Workspace: ~/.openclaw/workspace
  │   ├── agentDir: agents/main/
  │   ├── Sessions: 独立存储
  │   ├── Auth Profiles: 独立配置
  │   ├── Skills: github, weather, feishu-doc
  │   └── Persona: 龙虾仔仔 🦞
  │
  ├── Agent: work
  │   ├── Workspace: ~/workspace-work
  │   ├── agentDir: agents/work/
  │   ├── Sessions: 独立存储
  │   ├── Skills: github, slack, calendar
  │   └ Persona: 工作助手 💼
  │
  └── Agent: family
      ├── Workspace: ~/workspace-family
      ├── agentDir: agents/family/
      ├── Sessions: 独立存储
      ├── Skills: weather, calendar, todo
      └ Persona: 家庭助手 🏠

完整配置示例

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"]
      }
    },
    
    list: [
      {
        id: "main",
        workspace: "~/.openclaw/workspace",
        skills: ["github", "weather", "feishu-doc"]
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        skills: ["github", "slack", "calendar"],
        model: {
          primary: "anthropic/claude-opus-4"  // 更强模型
        }
      },
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        skills: ["weather", "calendar", "todo"],
        model: {
          primary: "openai/gpt-4o-mini"  // 更便宜模型
        }
      }
    ]
  },
  
  bindings: [
    // 军哥的飞书私聊 → main Agent
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_ee09fa76de1e9e130bf6c3857034674a" }
      }
    },
    
    // Discord技术群 → work Agent
    {
      agentId: "work",
      match: {
        channel: "discord",
        guildId: "xxx"
      }
    },
    
    // WhatsApp家庭群 → family Agent
    {
      agentId: "family",
      match: {
        channel: "whatsapp",
        peer: { kind: "group", id: "+1555xxx" }
      }
    }
  ]
}

6.2 Sub-Agent子智能体

sessions_spawn详解

创建隔离子智能体：

// Spawn参数
{
  runtime: "subagent",  // 或 "acp"
  mode: "run",          // 或 "session"
  
  task: "分析这份飞书文档并生成摘要",
  model: "anthropic/claude-opus-4",  // 可指定更强模型
  
  timeoutSeconds: 300,
  thinking: "enabled",  // 或 "disabled"
  
  cwd: "/workspace/subagent-tasks",
  sandbox: "require",   // 要求沙箱隔离
  
  attachments: [
    { name: "doc.pdf", content: "...", mimeType: "application/pdf" }
  ]
}

runtime模式对比

6.3 自进化机制详解

三层自进化机制

自进化三层机制：

1. Skill Workshop
   → 从观察到的工作流程创建Skills
   → 分析Agent执行的任务模式
   → 自动生成SKILL.md文件
   → 添加到Skills目录
   
2. Hermes Evolution
   → 根据经验优化行为规则
   → 分析Agent的成功/失败案例
   → 更新AGENTS.md中的规则
   → 自动改进Agent行为
   
3. Memory Reflection
   → 定期反思更新长期记忆
   → 回顾memory/YYYY-MM-DD.md
   → 提取关键经验写入MEMORY.md
   → 保持记忆的连贯性

Part 7: 最佳实践与部署

7.1 快速部署完整指南

安装步骤详解

完整安装流程：

步骤1: 安装Node.js
  → 推荐v24 LTS
  → macOS: brew install node@24
  → Windows: 官网下载安装包
  
步骤2: 安装OpenClaw
  → macOS/Linux: curl -fsSL https://openclaw.ai/install.sh | bash
  → Windows: iwr -useb https://openclaw.ai/install.ps1 | iex
  → npm: npm install -g openclaw@latest
  
步骤3: 运行onboarding
  → openclaw onboard --install-daemon
  → 配置渠道（飞书/Telegram等）
  → 选择模型（Claude/GPT/GLM）
  → 设置Workspace
  
步骤4: 验证Gateway
  → openclaw gateway status
  → 确认Running状态
  → 检查Channels连接
  
步骤5: 打开Dashboard
  → openclaw dashboard
  → 浏览器打开 http://localhost:18789
  → 管理Agent、查看日志

7.2 配置文件结构详解

完整配置文件结构：

~/.openclaw/
├── openclaw.json           # 主配置文件（JSON5格式）
│   ├── agents              # Agent配置
│   ├── bindings            # 路由规则
│   ├── channels            # 渠道配置
│   ├── gateway             # Gateway配置
│   ├── sandbox             # 沙箱配置
│   ├── tools               # 工具配置
│   ├── cron                # 定时任务
│   └── memory              # 记忆配置
│
├── agents/
│   ├── main/
│   │   ├── agent/
│   │   │   ├── auth-profiles.json    # API认证
│   │   │   ├── model-registry.json   # 模型注册
│   │   │   └── skills-snapshot.json  # Skills快照
│   │   └── sessions/
│   │   │   ├── sessions.json         # Session索引
│   │   │   └── <session-id>.jsonl    # Session transcript
│   │
│   └── work/
│   │   ├── agent/
│   │   └── sessions/
│
├── workspace/              # 默认工作区
│   ├── AGENTS.md           # Agent行为规则
│   ├── SOUL.md             # Agent性格定义
│   ├── USER.md             # 用户信息
│   ├── MEMORY.md           # 长期记忆
│   ├── TOOLS.md            # 工具本地配置
│   ├── HEARTBEAT.md        # 心跳任务
│   ├── skills/             # 工作区技能
│   └── memory/             # 每日记忆
│       └── YYYY-MM-DD.md
│
└── skills/                 # 托管技能目录
    ├── github/
    │   └── SKILL.md
    ├── feishu-doc/
    │   └ SKILL.md
    └── ...

7.3 常见问题排查手册

问题诊断表

7.4 资源汇总

关键资源汇总

附录：Q&A预设问题

Q1: OpenClaw和Claude Code有什么本质区别？

核心区别：主动执行能力

Q2: Gateway为什么被称为"心脏"？

Gateway是统一控制平面，负责所有关键功能：

Q3: Skills如何理解？

公式：Skills = 基础工具 + 专业知识 + 工作流程

示例：

• read是基础工具
• github是Skills
• github = exec工具 + GitHub专业知识 + Issue/PR工作流程

Q4: Multi-Agent有什么实际应用场景？

三大场景：

Q5: 如何保证安全？

五层安全机制：

Q6: 数据隐私如何保证？

本地部署，数据不出厂：

Q7: Gateway心跳巡查具体做什么？

六大检查项：

Q8: 如何快速上手？

4步快速上手：

1. 安装OpenClaw
   curl -fsSL https://openclaw.ai/install.sh | bash
   
2. 运行onboarding
   openclaw onboard --install-daemon
   
3. 配置飞书机器人
   在飞书开放平台创建应用，获取AppId/AppSecret
   
4. 发送第一条消息
   在飞书中@机器人，开始对话

Q9: Cron定时任务怎么配置？

完整示例：

{
  cron: {
    jobs: [
      {
        name: "每日日报",
        schedule: { kind: "cron", expr: "0 18 * * *", tz: "Asia/Shanghai" },
        payload: { kind: "agentTurn", message: "生成今日工作日报" },
        delivery: { mode: "announce", channel: "feishu", to: "oc_xxx" },
        sessionTarget: "isolated"
      }
    ]
  }
}

Q10: 如何诊断问题？

诊断命令矩阵：