为刚接触 OpenClaw 的新手提供完整指南

基础术语速查

大模型常识

从产业视角、工程视角和 OpenClaw 架构，体系化了解 AI 大模型行业

上游：基础提供方
芯片厂商
NVIDIA、AMD
云服务商
AWS、阿里云
基础模型公司
OpenAI、Anthropic
技术支撑
中游：技术集成方
AI应用框架
LangChain、OpenClaw
向量数据库
Pinecone、Milvus
AI中间件
监控、安全、计费
解决方案
下游：应用落地
行业应用
医疗、金融、教育
企业数字化
智能客服、办公助手
7 应用产品层 把能力变成产品
AI应用
SaaS产品
行业方案
6 Agent与工作流层 让模型具备任务执行能力
Agent协作
工作流
任务规划
5 能力增强层 突破模型原始能力边界
RAG
微调
Tool Use
Prompt工程
4 模型服务层 提供稳定可扩展的推理能力
基础模型
推理服务
模型路由
3 数据与知识层 构建企业级记忆系统
向量数据库
知识图谱
记忆管理
2 AI工程与中间件层 把AI从实验变成可运营系统
监控日志
安全审计
成本控制
1 算力基础设施层 物理与资源底座
GPU/TPU
云平台
容器化

OpenClaw 架构和目录介绍

OpenClaw 层级架构

L7

应用层 (Application)

Skill、Bot、Dashboard 等用户交互界面

L6

Agent 层

任务规划、工具编排、多模型协作

L5

模型层 (Model)

多模型接入（Claude、GPT、Gemini 等）

L4

记忆层 (Memory)

向量数据库、长期记忆、会话管理

L3

Gateway 层

请求路由、限流、认证、会话管理

L2

频道层 (Channel)

Telegram、Discord、Slack、Web 等接入

L1

核心层 (Core)

配置管理、日志、监控、插件系统

配置目录说明

~/.openclaw/
OpenClaw 主目录，所有数据存储位置
openclaw.json
主配置文件，包含 API Key、模型选择、频道配置等
workspace/
工作区目录，存放 Skill、项目文件和数据
soul.md
行为宪法：定义 AI 身份、能力、风格、底线
USER.md
用户画像：用户背景、偏好、沟通风格
IDENTITY.md
身份定义：AI 角色设定、行为准则
memory.md
长期记忆：工作方法论、用户偏好、项目背景
agents.md
工作流规范：工具使用、协作机制、错误处理
skills/
已安装的 Skill 集合
<skill-name>/
单个 Skill 目录
skill.json
Skill 元信息配置
index.js
Skill 入口文件，定义激活/停用逻辑
server.js
Skill Web 服务入口（如有独立服务）
web/
Web 静态资源（HTML/CSS/JS/图片）
memory/
向量数据存储与日期记忆文件
YYYY-MM-DD.md
按日期维度的记忆文件
vector/
向量数据库存储（Chroma 等）
logs/
日志目录
openclaw.log
主程序运行日志
gateway.log
Gateway 运行日志
error.log
错误日志
gateway.pid
Gateway 进程 ID 文件
gateway.sock
Gateway Unix Socket 文件，Gateway 与 CLI 之间的 IPC 通信

常见问题解答

常用命令大全

推荐规范与实践

OpenClaw 知识库组织规范与最佳实践

soul.md 行为宪法

  • 你是谁：定义 AI 助手的身份定位和角色
  • 你的能力：明确技能范围、技术栈、擅长领域
  • 你的风格：设定交流语气、回复风格、沟通习惯
  • 你的底线：划定红线、禁止行为、伦理边界

memory.md 记忆管理

  • 长期记忆：记录工作方法论、用户偏好、项目背景
  • 日期记忆：memory/YYYY-MM-DD.md 按日期维度组织
  • 会话记忆：按会话维度记录上下文
  • 记忆更新：定期回顾和清理过时信息

agents.md 工作流规范

  • 工作流定义：记录自动化任务流程和执行顺序
  • 工具规范：定义工具使用场景、参数、返回值格式
  • 协作机制：多 Agent 协作模式与通信协议
  • 错误处理：异常捕获、降级策略、重试逻辑

模型分组调用

  • 简单任务：使用轻量模型（如 claude-sonnet-4-20250514）
  • 复杂推理：使用强力模型（如 claude-opus-4-5-20251114）
  • 代码任务：使用代码优化模型
  • 成本控制：根据任务难度自动选择模型

Session 会话管理

  • 配置 session.reset 设置会话重置策略（daily/idle）
  • 使用 session.idleMinutes 控制空闲超时
  • 通过 session.sendPolicy 控制消息发送策略
  • 利用 compaction 管理长会话压缩

网络与安全

  • 配置代理解决国际网络访问问题
  • 启用 retry 自动重试失败请求
  • 设置 API Key 环境变量保障安全
  • 配置请求并发限制防止 API 限流

Heartbeat 心跳配置

  • 使用 heartbeat.every 设置检查间隔
  • 配置 heartbeat.activeHours 限定活跃时段
  • 通过 heartbeat.prompt 自定义检查任务
  • 利用 heartbeat.target 指定消息推送目标

Cron 定时任务

  • 使用 cron.enabled 启用定时任务
  • 配置 cron.maxConcurrentRuns 控制并发数
  • 通过 cron.store 管理任务持久化
  • 结合 webhook 实现外部触发

Plugins 插件扩展

  • 使用 plugins.enabled 全局启用/禁用插件
  • 通过 plugins.allow 和 plugins.deny 控制插件白名单
  • 配置 plugins.slots.memory 选择记忆插件后端
  • 安装外部插件扩展功能

Tools 工具权限

  • 使用 tools.profile 选择工具配置集（minimal/coding/messaging/full）
  • 通过 tools.allow 和 tools.deny 细粒度控制工具
  • 配置 tools.exec 控制shell命令执行（host/security/ask）
  • 使用 tools.web.search 启用网页搜索

Memory Search 记忆搜索

  • 启用 memorySearch.enabled 开启向量记忆搜索
  • 配置 memorySearch.sources 选择索引源（memory/sessions）
  • 使用 memorySearch.sync 控制自动同步策略
  • 配置 memorySearch.query 优化搜索结果

Context 上下文管理

  • 使用 contextTokens 限制上下文token上限
  • 配置 contextPruning 控制上下文修剪策略
  • 使用 compaction 管理长会话压缩
  • 配置 contextPruning.softTrim 保留关键内容

Subagents 子代理

  • 使用 subagents.maxConcurrent 控制并发子代理数
  • 配置 subagents.archiveAfterMinutes 设置自动归档时间
  • 通过 subagents.model 为子代理指定专用模型
  • 使用 subagents.thinking 控制子代理思考模式

Sandbox 沙箱安全

  • 使用 sandbox.mode 选择沙箱模式（off/non-main/all）
  • 配置 sandbox.workspaceAccess 控制工作区访问权限
  • 通过 sandbox.docker 配置容器化隔离
  • 使用 sandbox.browser 控制浏览器隔离

Messages 消息处理

  • 使用 messages.queue 配置消息队列策略
  • 配置 messages.tts 控制语音合成
  • 通过 messages.ackReaction 设置消息确认反应
  • 使用 messages.inbound.debounceMs 处理高频消息

Auth 认证管理

  • 使用 auth.profiles 配置多个认证配置
  • 通过 auth.order 设置认证优先级
  • 配置 auth.cooldowns 控制失败后冷却时间
  • 使用账单限流避免意外超额

Telegram 配置

  • 使用 channels.telegram.dmPolicy 控制DM权限
  • 配置 channels.telegram.streamMode 选择流式响应模式
  • 通过 channels.telegram.groups 配置群组设置
  • 使用 channels.telegram.retry 配置重试策略

Discord 配置

  • 使用 channels.discord.dm.policy 控制DM权限
  • 配置 channels.discord.intents 启用特权intent
  • 通过 channels.discord.pluralkit 集成 PluralKit
  • 使用 channels.discord.maxLinesPerMessage 控制消息长度

Timeout 超时控制

  • 使用 timeoutSeconds 设置请求超时
  • 配置 typingIntervalSeconds 控制打字间隔
  • 通过 humanDelay 模拟人类输入延迟
  • 使用 mediaMaxMb 限制媒体文件大小