OpenClaw 基础配置详解:从入门到理解工作原理

OpenClaw 基础配置详解：从入门到理解工作原理

🦞 刚接触"龙虾"？这篇文章帮你彻底理解 OpenClaw 的工作原理

📖 前言

如果你刚接触 OpenClaw，可能会被一堆配置文件和目录搞晕。别担心，这篇文章会带你从零开始，理解 OpenClaw 的核心概念、配置结构，以及各个组件是如何协作的。

读完这篇文章，你将能够： - ✅ 理解 OpenClaw 的整体架构 - ✅ 知道每个配置目录的作用 - ✅ 明白大模型、Skill、Channel、MCP 之间的关系 - ✅ 能够独立排查和修改配置

🏗️ 一、OpenClaw 是什么？

一句话总结：OpenClaw 是一个自托管的 AI 网关，它把你常用的聊天软件（微信、飞书、Telegram、Discord 等）和 AI 大模型连接起来。

📊 核心架构

OpenClaw 的工作流程可以用下图表示：

你（微信/飞书等）
     ↓ 发送消息
OpenClaw Gateway
     ↓ 调用 API
大模型（通义千问/豆包等）
     ↓ 返回回复
你（微信/飞书等）

更详细地说：

┌──────────────┐
│   你（用户）   │
│ 微信/飞书等   │
└──────┬───────┘
       │ 发送消息
       ▼
┌─────────────────────────────┐
│   OpenClaw Gateway（网关）   │
│  • Channel：渠道管理         │
│  • Session：会话管理         │
│  • Memory：记忆管理          │
│  • Skill：技能管理           │
│  • MCP：工具扩展             │
│  • Model：模型调用           │
└──────┬──────────────────────┘
       │ 调用 API
       ▼
┌─────────────────────────────┐
│      大模型 API              │
│ 通义千问/豆包/GPT-4/Claude  │
└─────────────────────────────┘

5 步工作流程：

你发送消息 → 微信/飞书
Gateway 接收 → 创建会话、加载记忆
Skill 检测 → 匹配技能、准备上下文
调用大模型 → 发送请求、生成回复
返回结果 → 通过原渠道发回给你

📁 二、核心配置目录详解

OpenClaw 的主要配置都在 ~/.openclaw/ 目录下，让我们逐个了解：

2.1 根目录结构

~/.openclaw/
├── openclaw.json          # 主配置文件（核心！）
├── models.json            # 大模型配置
├── gateway.env            # 环境变量
├── workspace/             # 工作区（你的文件、技能、记忆）
├── agents/                # Agent 配置
├── channels/              # 渠道配置
├── credentials/           # 认证凭据
├── devices/               # 设备配对
├── extensions/            # 扩展插件
├── skills/                # 技能库
├── sessions/              # 会话历史
├── logs/                  # 日志
└── ...

2.2 核心配置文件

📄 `openclaw.json` - 主配置文件

作用：控制 OpenClaw 的全局行为

关键配置项：

{
  "gateway": {
    "port": 8080,              // Gateway 服务端口
    "host": "127.0.0.1"        // 监听地址
  },
  "channels": {
    "openclaw-weixin": {       // 微信渠道配置
      "enabled": true,
      "type": "wechat"
    },
    "feishu": {                // 飞书渠道配置
      "enabled": true,
      "type": "feishu"
    }
  },
  "models": {
    "default": "qwen3.5-plus"  // 默认使用的模型
  },
  "skills": {
    "external_dirs": [         // 外部技能目录
      "~/.openclaw/workspace/skills"
    ]
  },
  "dmScope": "main"            // 多通道记忆共享（重要！）
}

💡 重要提示： - dmScope: "main" 表示所有渠道共享同一份记忆 - 如果设为 channel，微信和飞书的记忆是隔离的

📄 `models.json` - 大模型配置

作用：配置可用的大模型和 API Key

示例配置：

{
  "qwen3.5-plus": {
    "provider": "dashscope",
    "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api_key": "sk-xxxxxxxxxxxxx"
  },
  "doubao-seed-2.0-pro": {
    "provider": "arkcode",
    "base_url": "https://ark.cn-beijing.volces.com/api/coding",
    "api_key": "xxxx-xxxx-xxxx"
  }
}

💡 重要提示： - 可以配置多个模型，通过 default 指定默认使用哪个 - 支持模型故障转移（failover）

📄 `gateway.env` - 环境变量

作用：设置全局环境变量（API Key 等）

示例：

DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxx
ARK_API_KEY=xxxx-xxxx-xxxx
BAIDU_API_KEY=xxxxxxxxxxxxx

💡 重要提示： - 这里配置的 API Key 对所有技能生效 - 比 models.json 优先级低，但更通用

2.3 功能目录

📂 `workspace/` - 工作区

作用：你的个人工作空间，包含：

workspace/
├── SOUL.md              # AI 人格设定（我是谁）
├── USER.md              # 用户信息（你是谁）
├── IDENTITY.md          # 身份配置
├── MEMORY_PUBLIC.md     # 公共记忆（所有会话共享）
├── MEMORY_PRIVATE.md    # 私密记忆（仅私聊）
├── memory/              # 每日记忆记录
│   ├── 2026-04-17.md
│   └── ...
├── skills/              # 自定义技能
├── docs/                # 文档
└── blog-project/        # 你的项目文件

💡 重要提示： - SOUL.md 决定 AI 的性格和行为方式 - MEMORY_PUBLIC.md 是所有会话共享的核心记忆 - 每日记忆文件会自动创建

📂 `channels/` - 渠道配置

作用：存储各聊天渠道的认证信息

channels/
├── wechat/
│   └── credentials.json   # 微信认证
├── feishu/
│   └── credentials.json   # 飞书认证
└── telegram/
    └── bot_token.txt      # Telegram Bot Token

💡 重要提示： - 每个渠道有独立的认证文件 - 不要手动修改，使用 openclaw pairing 命令配置

📂 `credentials/` - 认证凭据

作用：存储 OAuth token、API Key 等敏感信息

安全提示： - 此目录权限为 700（仅所有者可读写） - 不要上传到 Git 仓库

📂 `skills/` - 技能库

作用：存储内置技能

skills/
├── weather/               # 天气查询技能
├── stock-trader/          # 股票分析技能
├── browser/               # 浏览器自动化技能
└── ...

技能结构：

weather/
├── SKILL.md               # 技能描述（触发条件、使用方法）
├── script.py              # 执行脚本
└── references/            # 参考资料

📂 `sessions/` - 会话历史

作用：存储对话历史

sessions/
├── agent-main-main/       # 主会话
│   └── messages.json
└── agent-xxx-yyy/         # 其他会话

💡 重要提示： - 会话会自动压缩（compaction）以节省空间 - 使用 openclaw sessions list 查看

📂 `logs/` - 日志目录

作用：存储运行日志

logs/
├── gateway.log            # Gateway 主日志
├── agent.log              # Agent 日志
└── error.log              # 错误日志

排查问题：

tail -f ~/.openclaw/logs/gateway.log

🔧 三、核心概念详解

3.1 大模型（Model）

是什么：AI 的"大脑"，负责理解你的话并生成回复

常见模型：

模型	提供商	特点
`qwen3.5-plus`	阿里云	中文能力强，性价比高
`doubao-seed-2.0-pro`	字节跳动	理解能力强
`gpt-4`	OpenAI	最强，但贵
`claude-sonnet`	Anthropic	长文本处理优秀

配置位置：models.json

3.2 渠道（Channel）

是什么：你和 OpenClaw 沟通的"管道"

支持渠道： - 💬 微信（企业微信/个人微信） - 📱 飞书 - ✈️ Telegram - 💙 Discord - 📧 Slack - 🍎 iMessage - ...（30+ 渠道）

配置位置：openclaw.json + channels/

3.3 技能（Skill）

是什么：OpenClaw 的"超能力"，让它能完成特定任务

技能示例：

技能	功能	触发词
`weather`	查天气	"天气怎么样"
`stock-trader`	查股票	"看看茅台"
`browser`	上网	"搜索 XXX"
`aliyun-image`	生成图片	"生成一张图片"

技能工作流程：

用户说"查天气" 
  → Skill 检测到触发词 
  → 调用天气 API 
  → 返回结果

配置位置：openclaw.json → skills.external_dirs

3.4 MCP（Model Context Protocol）

是什么：一种标准化的工具扩展协议，让 AI 能调用外部工具

MCP vs Skill 对比：

对比项	Skill	MCP
格式	OpenClaw 自定义	标准协议
开发难度	简单	需要遵循协议
复用性	仅 OpenClaw	跨平台通用
示例	`weather`	`mcp-server-puppeteer`

MCP 配置：

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

配置位置：openclaw.json → mcp

3.5 记忆（Memory）

是什么：AI 的"记忆力"，让它记得你说过的话

记忆类型：

类型	文件	加载场景
公共记忆	`MEMORY_PUBLIC.md`	私聊 + 群聊
私密记忆	`MEMORY_PRIVATE.md`	仅私聊
每日记忆	`memory/2026-04-17.md`	自动创建

记忆搜索命令：openclaw memory search "关键词"

配置位置：workspace/MEMORY_*.md

openclaw memory search "上次说的股票"

配置位置：workspace/MEMORY_*.md

🔄 四、完整工作流程示例

让我们通过一个实际例子，理解 OpenClaw 是如何工作的：

场景：你在微信问"今天天气怎么样"

1️⃣ 你发送消息
   微信 → "今天天气怎么样"

2️⃣ Gateway 接收
   openclaw-weixin 渠道收到消息
   ↓
   创建会话（如果首次）
   ↓
   加载记忆（MEMORY_PUBLIC.md + MEMORY_PRIVATE.md）

3️⃣ Skill 检测
   扫描所有技能的触发词
   ↓
   发现 `weather` 技能匹配"天气"
   ↓
   加载技能上下文

4️⃣ 调用大模型
   构建 Prompt：
   "用户问：今天天气怎么样
    记忆：用户在北京
    技能：weather 可用"
   ↓
   发送到大模型 API（qwen3.5-plus）

5️⃣ 大模型回复
   "我来帮你查一下北京的天气..."
   ↓
   调用 weather 技能的实际 API

6️⃣ 返回结果
   "北京 ☀️ +25°C，晴朗"
   ↓
   通过微信发回给你

🛠️ 五、常用配置操作

5.1 查看当前配置

# 查看 Gateway 状态
openclaw gateway status

# 查看已配置的模型
openclaw models list

# 查看已启用的渠道
openclaw channels list

# 查看已加载的技能
openclaw skills list

5.2 修改默认模型

编辑 ~/.openclaw/models.json：

{
  "default": "qwen3.5-plus"
}

然后重启：

openclaw gateway restart

5.3 添加新渠道

# 配对微信
openclaw pairing wechat

# 配对飞书
openclaw pairing feishu

# 配对 Telegram
openclaw pairing telegram

5.4 查看日志

# 实时查看 Gateway 日志
tail -f ~/.openclaw/logs/gateway.log

# 查看错误日志
cat ~/.openclaw/logs/error.log

5.5 排查问题

# 检查整体状态
openclaw status

# 检查配置
openclaw doctor

# 查看会话
openclaw sessions list

🎯 六、最佳实践

6.1 配置管理

✅ 推荐做法： - 使用 openclaw CLI 修改配置 - 定期备份 ~/.openclaw/ 目录 - API Key 使用环境变量或 credentials/

❌ 避免做法： - 手动编辑 credentials/ 下的文件 - 把 API Key 写到代码里 - 忽略日志报错

6.2 性能优化

会话压缩：定期清理旧会话
技能加载：只启用需要的技能
模型选择：根据任务选择合适模型（简单任务用便宜模型）

6.3 安全建议

定期更新 OpenClaw：openclaw update
检查安全配置：openclaw health
不要开放 Gateway 端口到公网（除非必要）

📚 七、进阶话题

7.1 多 Agent 路由

OpenClaw 支持同时运行多个 Agent： - agent-main：主助手 - agent-coder：编程专家 - agent-analyst：数据分析师

配置示例：

{
  "agents": {
    "main": {
      "model": "qwen3.5-plus",
      "skills": ["weather", "stock"]
    },
    "coder": {
      "model": "claude-sonnet",
      "skills": ["github", "code-review"]
    }
  }
}

7.2 自定义技能

创建技能目录：

mkdir -p ~/.openclaw/workspace/skills/my-skill

编写 SKILL.md：

# my-skill

## 触发词
- "我的技能"
- "自定义"

## 功能
描述你的技能能做什么

7.3 记忆管理

手动添加记忆：

openclaw memory add "用户喜欢简洁的回复"

搜索记忆：

openclaw memory search "股票"

🎓 八、总结

核心要点回顾

组件	作用	配置位置
Gateway	核心网关	`openclaw.json`
Channel	沟通渠道	`channels/`
Model	AI 大脑	`models.json`
Skill	特殊能力	`skills/`
MCP	工具扩展	`openclaw.json` → `mcp`
Memory	记忆系统	`workspace/MEMORY_*.md`

工作流程回顾

用户消息 → Channel → Gateway → Skill/Memory → Model → 回复

下一步学习

📖 阅读官方文档：https://docs.openclaw.ai
🔧 尝试自定义技能
🌐 配置更多渠道
🤖 探索多 Agent 路由

❓ 常见问题

Q: 修改配置后需要重启吗？ A: 大部分配置需要 openclaw gateway restart

Q: 如何备份配置？ A: cp -r ~/.openclaw ~/.openclaw.backup

Q: 技能不生效怎么办？ A: 检查 openclaw.json 中 skills.external_dirs 是否包含技能目录

Q: 如何切换模型？ A: 修改 models.json 中的 default 字段，然后重启

🦞 祝你使用 OpenClaw 愉快！

有问题？随时在微信/飞书问我！