🏗️ 一、核心概念关系图

🔄 二、核心概念关系详解

1. Gateway（网关）- 控制中枢

• 角色：系统的"大脑"和"交通枢纽"
• 职责：
  • 消息路由：接收所有渠道消息，分发给对应Agent
  • 认证授权：管理用户权限和会话安全
  • 服务协调：协调Agent、Skills、Nodes之间的协作
• 位置：~/.openclaw/openclaw.json 配置

2. Agent（智能体）- 执行单元

• 角色：具体的"数字员工"
• 职责：
  • 任务执行：根据用户指令执行具体任务
  • 记忆管理：维护对话历史和上下文
  • 技能调用：选择合适的Skills完成任务
• 位置：~/.openclaw/agents/ 目录下

3. Skills（技能）- 功能模块

• 角色：Agent的"专业技能包"
• 职责：
  • 功能封装：将复杂操作封装为简单接口
  • 标准化：提供统一的调用规范
  • 可复用：跨Agent共享使用
• 来源：
  • 内置技能：系统自带
  • ClawHub社区：上万种社区贡献技能
  • 自定义技能：用户自己开发

4. Tools（工具）- 具体能力

• 角色：Skills的"基础工具集"
• 类型：
  • 浏览器工具：网页自动化
  • 执行工具：系统命令执行
  • Web工具：HTTP请求
  • 自动化工具：定时任务
• 位置：集成在Skills中

5. Channels（渠道）- 交互入口

• 角色：用户的"沟通窗口"
• 功能：
  • 消息接收：从各种平台接收用户消息
  • 格式转换：统一不同平台的消息格式
  • 身份验证：验证用户身份
• 位置：Gateway配置中管理

6. Nodes（节点）- 分布式触手

• 角色：系统的"延伸手臂"
• 功能：
  • 设备接入：将其他设备接入系统
  • 能力扩展：提供设备特有功能
  • 跨设备协作：协调多设备任务执行
• 类型：macOS、iOS、Android等设备节点

---

🛠️ 三、针对各概念的常用指令

Gateway 相关指令

# 启动/停止/重启
openclaw gateway start      # 后台启动
openclaw gateway stop       # 停止服务
openclaw gateway restart    # 重启服务（配置修改后必用）

# 状态检查
openclaw gateway status     # 检查服务状态
openclaw health             # 健康检查

# 配置管理
openclaw config get gateway.port      # 查看端口
openclaw config set gateway.port 18789 # 修改端口

Agent 相关指令

# Agent管理
openclaw agents list        # 列出所有Agent
openclaw agents add         # 添加新Agent
openclaw agents delete <name> # 删除Agent

# 会话管理
openclaw sessions list      # 查看所有会话
openclaw memory search "关键词" # 搜索记忆

Skills 相关指令

# 技能管理
openclaw skills list        # 列出已安装技能
openclaw skills install <name> # 安装技能
openclaw skills enable <name>  # 启用技能
openclaw skills disable <name> # 禁用技能

# ClawHub社区
clawhub search "关键词"     # 搜索技能
clawhub install <skill>     # 安装社区技能

Channels 相关指令

# 渠道管理
openclaw channels list      # 列出已配置渠道
openclaw channels add       # 添加新渠道
openclaw channels status    # 检查渠道状态
openclaw channels login --channel <name> # 登录渠道

Nodes 相关指令

# 节点管理
openclaw nodes              # 查看所有节点
openclaw node start         # 启动节点服务
openclaw node status        # 检查节点状态

通用诊断指令

openclaw doctor             # 全面健康检查（最常用）
openclaw doctor --fix       # 自动修复问题
openclaw logs --follow      # 实时查看日志

---

四、国内可用渠道配置指南

1. 微信（个人号）

配置方法：

# 添加微信渠道
openclaw channels add --channel wechat

# 扫码登录
openclaw channels login --channel wechat

注意事项：

• 需要微信个人号（不支持公众号/小程序）
• 扫码登录后需在手机确认
• 可能面临封号风险，建议使用小号

2. 飞书（企业版）

配置方法：

# 添加飞书渠道
openclaw channels add --channel feishu \
  --app-id "YOUR_APP_ID" \
  --app-secret "YOUR_APP_SECRET" \
  --encrypt-key "YOUR_ENCRYPT_KEY" \
  --verification-token "YOUR_VERIFICATION_TOKEN"

获取凭证步骤：

1. 登录飞书开放平台：https://open.feishu.cn
2. 创建企业自建应用
3. 获取以下信息：
   • App ID
   • App Secret
   • Encrypt Key
   • Verification Token
4. 配置事件订阅和权限

3. 钉钉（企业版）

配置方法：

# 添加钉钉渠道
openclaw channels add --channel dingtalk \
  --app-key "YOUR_APP_KEY" \
  --app-secret "YOUR_APP_SECRET" \
  --robot-code "YOUR_ROBOT_CODE"

获取凭证步骤：

1. 登录钉钉开放平台：https://open.dingtalk.com
2. 创建企业内部应用/H5微应用
3. 获取AppKey和AppSecret
4. 配置机器人权限

4. 企业微信

配置方法：

# 添加企业微信渠道
openclaw channels add --channel wecom \
  --corp-id "YOUR_CORP_ID" \
  --corp-secret "YOUR_CORP_SECRET" \
  --agent-id "YOUR_AGENT_ID"

获取凭证步骤：

1. 登录企业微信管理后台
2. 创建应用
3. 获取以下信息：
   • 企业ID（CorpID）
   • 应用Secret
   • 应用AgentId

5. Telegram（需科学上网）

配置方法：

# 添加Telegram渠道
openclaw channels add --channel telegram \
  --token "YOUR_BOT_TOKEN"

# 获取Bot Token步骤：
# 1. 在Telegram中搜索 @BotFather
# 2. 发送 /newbot 创建新机器人
# 3. 获取并保存Token

6. 邮件（SMTP）

配置方法：

# 添加邮件渠道
openclaw channels add --channel email \
  --smtp-host "smtp.example.com" \
  --smtp-port 587 \
  --smtp-username "your-email@example.com" \
  --smtp-password "your-password" \
  --imap-host "imap.example.com" \
  --imap-port 993

渠道配置对比表

渠道	类型	配置复杂度	稳定性	适用场景
微信	个人社交	简单	中等	个人使用、小团队
飞书	企业协作	复杂	高	企业办公、团队协作
钉钉	企业协作	中等	高	企业办公、项目管理
企业微信	企业通讯	中等	高	企业内部沟通
Telegram	国际通讯	简单	高	技术社区、国际团队
邮件	异步通讯	中等	高	正式通知、报告推送

---

🛠️ 五、常用Skills配置指南

1. 浏览器控制技能

安装：

clawhub install browser-control

配置：

// 在Agent配置中启用
{
  "skills": {
    "browser-control": {
      "enabled": true,
      "config": {
        "headless": false,      // 是否无头模式
        "timeout": 30000,       // 超时时间(ms)
        "viewport": {           // 视口设置
          "width": 1280,
          "height": 800
        }
      }
    }
  }
}

常用功能：

• 网页抓取和数据提取
• 表单自动填写
• 截图和PDF生成
• 自动化测试

2. 文件操作技能

安装：

clawhub install file-operations

配置：

{
  "skills": {
    "file-operations": {
      "enabled": true,
      "config": {
        "allowed_directories": [
          "~/Documents",
          "~/Downloads",
          "/tmp"
        ],
        "max_file_size": 10485760,  // 10MB
        "allowed_extensions": [".txt", ".pdf", ".docx", ".xlsx"]
      }
    }
  }
}

常用功能：

• 文件读写和编辑
• 批量重命名
• 格式转换
• 目录整理

3. 定时任务技能

安装：

clawhub install scheduler

配置：

{
  "skills": {
    "scheduler": {
      "enabled": true,
      "config": {
        "timezone": "Asia/Shanghai",
        "max_concurrent_tasks": 5,
        "retry_attempts": 3
      }
    }
  }
}

常用功能：

• 定时数据备份
• 定期报告生成
• 网站监控
• 自动化数据同步

4. 天气查询技能

安装：

clawhub install weather

配置：

{
  "skills": {
    "weather": {
      "enabled": true,
      "config": {
        "provider": "qweather",      // 和风天气
        "api_key": "YOUR_API_KEY",
        "default_city": "北京",
        "units": "metric"           // 公制单位
      }
    }
  }
}

获取API Key：

1. 访问和风天气官网：https://dev.qweather.com
2. 注册开发者账号
3. 创建应用获取Key

5. 邮件处理技能

安装：

clawhub install email-handler

配置：

{
  "skills": {
    "email-handler": {
      "enabled": true,
      "config": {
        "imap": {
          "host": "imap.example.com",
          "port": 993,
          "username": "your-email@example.com",
          "password": "your-password"
        },
        "smtp": {
          "host": "smtp.example.com",
          "port": 587,
          "username": "your-email@example.com",
          "password": "your-password"
        },
        "check_interval": 300,  // 检查间隔(秒)
        "auto_reply_rules": []   // 自动回复规则
      }
    }
  }
}

6. 数据库操作技能

安装：

clawhub install database

配置：

{
  "skills": {
    "database": {
      "enabled": true,
      "config": {
        "connections": {
          "main": {
            "type": "mysql",
            "host": "localhost",
            "port": 3306,
            "database": "mydb",
            "username": "user",
            "password": "pass"
          },
          "cache": {
            "type": "redis",
            "host": "localhost",
            "port": 6379
          }
        },
        "query_timeout": 30,
        "max_rows": 1000
      }
    }
  }
}

7. API调用技能

安装：

clawhub install api-client

配置：

{
  "skills": {
    "api-client": {
      "enabled": true,
      "config": {
        "timeout": 30000,
        "retry_count": 3,
        "default_headers": {
          "User-Agent": "OpenClaw/1.0"
        },
        "endpoints": {
          "github": {
            "base_url": "https://api.github.com",
            "auth": "token YOUR_GITHUB_TOKEN"
          },
          "openai": {
            "base_url": "https://api.openai.com/v1",
            "auth": "Bearer YOUR_OPENAI_KEY"
          }
        }
      }
    }
  }
}

8. 办公自动化技能

安装：

clawhub install office-automation

功能：

• Word文档处理
• Excel表格操作
• PDF生成和编辑
• 幻灯片制作

Skills配置最佳实践

1. 按需安装

# 工作场景
clawhub install browser-control file-operations scheduler

# 开发场景  
clawhub install api-client database git-operations

# 生活场景
clawhub install weather news-aggregator shopping-assistant

2. 权限控制

{
  "skills": {
    "file-operations": {
      "enabled": true,
      "permissions": {
        "read": ["~/Documents", "~/Downloads"],
        "write": ["~/Documents/OpenClaw"],
        "execute": []  // 禁止执行命令
      }
    }
  }
}

3. 技能组合

# 创建自动化工作流
clawhub install web-scraper    # 网页抓取
clawhub install data-processor # 数据处理
clawhub install report-generator # 报告生成

# 配置技能链
# 1. web-scraper抓取数据
# 2. data-processor清洗数据  
# 3. report-generator生成报告

4. 安全配置

{
  "skills": {
    "system-commands": {
      "enabled": true,
      "config": {
        "allowed_commands": [
          "ls", "cat", "grep", "find",
          "df", "du", "ps", "top"
        ],
        "blocked_commands": [
          "rm -rf", "format", "dd",
          "shutdown", "reboot"
        ],
        "require_approval": true  // 危险操作需要确认
      }
    }
  }
}

---

🚀 六、完整配置示例

典型个人助理配置

# 1. 基础安装
openclaw setup
openclaw onboard

# 2. 配置模型（智谱AI）
openclaw config set providers.zhipu.apiKey "YOUR_ZHIPU_API_KEY"
openclaw models set glm-4.7-flash

# 3. 添加渠道（微信）
openclaw channels add --channel wechat
openclaw channels login --channel wechat

# 4. 安装常用技能
clawhub install browser-control
clawhub install file-operations  
clawhub install weather
clawhub install scheduler

# 5. 启动服务
openclaw gateway start

企业工作流配置

# 1. 基础配置
openclaw setup --profile work
openclaw onboard

# 2. 配置企业渠道（飞书）
openclaw channels add --channel feishu \
  --app-id "YOUR_APP_ID" \
  --app-secret "YOUR_APP_SECRET"

# 3. 安装办公技能
clawhub install office-automation
clawhub install email-handler
clawhub install meeting-scheduler
clawhub install report-generator

# 4. 配置数据库连接
openclaw config set skills.database.connections.main.host "db.company.com"

# 5. 设置定时任务
openclaw cron add "0 9 * * 1-5" "daily-report"

---

🔧 七、故障排查与维护

常见问题解决

# 1. 服务无法启动
openclaw doctor --fix
openclaw gateway restart

# 2. 渠道连接失败
openclaw channels status --probe
openclaw logs --filter error

# 3. 技能加载失败
openclaw skills check
clawhub sync --all

# 4. 内存不足
openclaw config set gateway.memory.limit 2048  # 限制2GB内存

定期维护命令

# 每周维护
openclaw update                    # 更新版本
clawhub sync --all                 # 同步技能
openclaw backup create             # 创建备份

# 每月维护  
openclaw security audit            # 安全审计
openclaw memory index              # 重建记忆索引
openclaw config validate           # 校验配置

---

📊 八、总结与建议

核心关系回顾

1. Gateway是大脑，Agent是员工
2. Skills是专业技能，Tools是工具
3. Channels是沟通方式，Nodes是延伸手臂
4. 所有组件通过Gateway协调工作

配置优先级建议

1. 先配置Gateway和模型 - 确保核心运行
2. 再添加1-2个渠道 - 建立沟通通道
3. 然后安装核心技能 - 浏览器、文件、定时任务
4. 最后按需扩展 - 根据实际需求添加其他技能

国内用户特别建议

1. 渠道选择：优先考虑飞书/钉钉/企业微信，稳定性更好
2. 模型选择：智谱GLM、百度文心、阿里通义等国内模型
3. 技能来源：关注ClawHub上的中文技能包
4. 网络配置：确保能访问必要的API服务