OpenClaw 完全指南:海外疯传的免费 AI 代理构建全流程课程

前置条件很简单：熟悉命令行操作，了解 API 调用机制，理解上下文存储的基本概念。

安装命令执行后，系统会在 ~/.openclaw 创建运行时目录。

这个目录与 ~/.openclaw/workspace 有本质区别：前者存放系统配置、日志、缓存、会话记录，后者存放 Agent 的人格定义和能力规则。

初始化向导 openclaw onboard 会带你逐项配置，关键决策点在于模型选择：

- 更大参数的模型对提示注入攻击有更强的抵抗力，小模型容易被恶意构造的提示操纵。

- 建议在预算允许范围内选择最强模型作为主力。

使用 --install-damon 参数可将 Gateway 注册为系统后台服务，macOS 上用 launchd，Linux 上用 systemd，实现开机自动启动，无需保持终端窗口。

本地运行意味着 Agent 拥有访问你文件系统的完整权限。给了足够权限，它确实可能误删文件。

两种风险缓解策略：

- 一是部署在 VPS 云服务器上，与本地工作机物理隔离；

- 二是启用 Docker 沙盒模式

沙盒配置有三组参数：

- sandbox.mode 控制隔离范围，off 关闭，non-main 仅隔离非主会话，all 全部隔离。

- sandbox.scope 控制容器生命周期，session 会话级，agent 代理级，shared 所有代理共享一个容器。

- workspaceAccess 限制文件访问，none 禁止访问工作区，ro 只读，rw 读写。

启用沙盒后，工具在 ~/.openclaw/sandboxes 下的隔离环境中运行，保护主机系统。代价是功能受限，因为容器内无法直接访问桌面文件。

安全审计工具包括：

- openclaw status 查看通道健康状态和最近会话

- openclaw security audit --deep 执行深度配置审计，识别安全漏洞

- openclaw security audit --fix 自动应用安全修复

- openclaw doctor 运行全面健康检查并尝试修复问题

~/.openclaw/workspace 是 OpenClaw 的核心概念，相当于 Agent 的“内存”，这个目录下的每个文件都有明确用途：

- AGENTS.md 定义代理的操作规则、优先级设定、行为准则，每次会话开始都会加载。

- SOUL.md 设定人物形象、语气风格、行为边界，决定 AI 是热情还是冷静，是直接还是委婉。

- USER.md 记录用户身份信息和称呼偏好，让 AI 知道“你是谁”。

- IDENTITY.md 定义代理名称、气质标签、表情符号，在初始化仪式期间创建。

- TOOLS.md 记录本地工具使用惯例，不控制工具可用性，只提供使用指导。

- HEARTBEAT.md 定义心率监测任务清单，Agent 会按设定间隔主动检查列表项，适合用于轮询监控或定期任务。

- BOOT.md 启用内部钩子时，Gateway 重启会执行这里的启动检查清单。

- BOOTSTRAP.md 一次性的首轮仪式配置，仪式结束后可以删除。

- memory/YYYY-MM-DD.md 每日内存日志，建议每天开始时阅读今天和昨天的记录。

- MEMORY.md（可选）精心设计的长期记忆文件，仅在私聊会话中加载。

- skills/ 工作区专属技能，当与系统级技能名称冲突时，工作区版本会覆盖。

- canvas/ 用于节点显示的 Canvas UI 文件。

OpenClaw 的会话隔离粒度非常精细。Session Key 的格式通常是 agent: main: discord: channel: ID 这样的结构，包含代理类型、代理名称、平台、隔离维度、具体 ID。

这种设计实现三种隔离：

- 多平台隔离：Discord 和 Telegram 即使频道 ID 相同，平台标识不同，session key 就不同，Discord 上的对话不会污染 Telegram 上下文。

- 多频道隔离：Discord 里不同频道的 channelId 不同，每个频道拥有独立的会话上下文。

- 多用户隔离：通过 dmScope 配置实现，默认群聊共享上下文，可以改为 per-channel-peer 让每个用户拥有独立 session。

记忆系统方面：

- 当前会话的历史存储在 ~/.openclaw/agents//sessions/ 目录下的 JSONL 文件中。

- 输入 /new 或 /reset 会创建新会话

- /compact 可以压缩会话上下文并报告剩余 token 预算

长期记忆需要配置 embedding provider，默认情况下语义搜索不可用。

doctor 命令会提示 SQLite unavailable、no embedding provider，这时记忆模块启用但无法检索。

真正发给 LLM 的内容不是你在对话框看到的那句话，而是经过多层拼接的完整提示词，拼接顺序如下：

- Core System Layer 内置的不可见系统规则，绝不删除。

- Workspace Layer SOUL、IDENTITY、USER、TOOLS 的人格定义，几乎不删除。

- Agent Runtime Layer 动态注入的会话信息，包括 session id、平台、dmPolicy、可用工具列表、模型能力说明。

- Memory Layer 语义检索到的相关记忆片段，插入位置在 system 与 conversation 之间。

- Conversation Layer 最近 N 轮对话历史，按 token 窗口动态裁剪。

- User Input 最后才是你的问题。

当 token 超出限制时，Prompt Composer 会进入裁剪模式，从最旧的对话开始删除，直到符合预算。

Memory 结果通常最先被移除，因为它是增强而非必需。

真正成熟的 Agent 会总结旧对话，把摘要插入 memory，然后删除原始记录。