OpenClaw 安装与使用指南

OpenClaw 是一个开源的 AI 助手平台，支持多种模型和渠道，可以在本地部署自己的 AI 伙伴。本文记录从安装到配置的完整过程。

环境说明

操作系统： Ubuntu 22.04 / Debian 12 (x64)
Node.js 版本： >= 18.0
内存要求： 建议 2GB 以上
前置条件： 已安装 Git、curl

安装步骤

1. 安装 Node.js

如果系统没有 Node.js 或版本过低：

# 使用 NodeSource 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 验证安装
node -v  # 应显示 v22.x.x
npm -v

2. 安装 OpenClaw

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
npm install

# 构建项目
npm run build

3. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，配置必要的 API Key
vim .env

最小配置示例：

# 必需：选择一个默认模型
OPENAI_API_KEY=your_openai_key_here
# 或
ANTHROPIC_API_KEY=your_anthropic_key_here

# 可选：其他模型配置
DEEPSEEK_API_KEY=your_deepseek_key_here

4. 启动服务

# 开发模式
npm run dev

# 或生产模式
npm start

服务默认运行在 http://localhost:3000

基础配置

配置文件位置

主配置文件：config/openclaw.yaml

# 复制示例配置
cp config/openclaw.example.yaml config/openclaw.yaml

关键配置项

# 模型配置
models:
  default: openai/gpt-4o
  available:
    - openai/gpt-4o
    - anthropic/claude-3-sonnet
    - deepseek/deepseek-chat

# 渠道配置（可选）
channels:
  webchat:
    enabled: true
    port: 3000
  
  # 如需 Telegram/Discord，取消注释并配置
  # telegram:
  #   enabled: true
  #   bot_token: your_bot_token

使用方法

Web 界面

浏览器访问 http://localhost:3000，即可开始对话。

常用命令

命令	功能
`/status`	查看当前会话状态
`/model`	切换模型
`/reasoning`	开启/关闭推理模式
`/clear`	清空当前对话

工作目录说明

OpenClaw 会在用户目录创建 workspace：

~/openclaw-workspace/
├── AGENTS.md      # 工作手册
├── IDENTITY.md    # AI 身份配置
├── USER.md        # 用户信息
├── SOUL.md        # 行为准则
├── TOOLS.md       # 工具配置
├── MEMORY.md      # 长期记忆
├── memory/        # 每日日志
└── ...

首次使用建议：

编辑 IDENTITY.md — 给 AI 起名字、设定性格
编辑 USER.md — 填写你的信息、时区
阅读 AGENTS.md — 了解工作流程

Workspace 详解

OpenClaw 的 Workspace 是 AI 助手的工作空间，也是人机协作的核心枢纽。理解 Workspace 的结构和使用方法，可以大幅提升使用效率。

Workspace 目录结构

~/openclaw-workspace/                 # 主工作目录
├── AGENTS.md                         # 智能体工作手册
├── IDENTITY.md                       # AI 身份与形象配置
├── USER.md                           # 用户信息档案
├── SOUL.md                           # 行为准则与安全边界
├── TOOLS.md                          # 本地工具与环境配置
├── MEMORY.md                         # 长期记忆（仅主会话加载）
├── HEARTBEAT.md                      # 定时任务配置
├── BOOTSTRAP.md                      # 首次启动引导（可删除）
├── memory/                           # 每日日志目录
│   ├── 2026-04-09.md                # 今日对话记录
│   ├── 2026-04-08.md                # 昨日记录
│   └── ...
└── [其他项目文件或子目录]

核心文件详解

1. AGENTS.md — 智能体工作手册

这是 AI 的”入职手册”，定义了工作流程和最佳实践。

内容通常包括：

会话启动时必须读取的文件清单
Memory 管理规范（每日日志 vs 长期记忆）
安全红线（不执行的操作）
群聊行为准则
工具使用规范

示例内容：

## Session Startup

Before doing anything else:
1. Read `SOUL.md` — this is who you are
2. Read `USER.md` — this is who you're helping
3. Read `memory/YYYY-MM-DD.md` (today + yesterday)

## Memory Rules

- **Daily notes:** `memory/YYYY-MM-DD.md` — raw logs
- **Long-term:** `MEMORY.md` — curated wisdom
- **ONLY load MEMORY.md in main session** (security)

2. IDENTITY.md — AI 身份配置

定义 AI 的名字、性格、形象。

示例：

# IDENTITY.md - Who Am I?

- **Name:** 关关
- **Creature:** 互联网全知全能的存在
- **Vibe:** 严谨专业，偶尔有点小幽默
- **Emoji:** 🎯

3. USER.md — 用户信息

记录用户的基本信息、偏好、时区等。

示例：

# USER.md - About Your Human

- **Name:** 开开
- **What to call them:** 开开
- **Timezone:** Asia/Shanghai (GMT+8)
- **Notes:** 为我取名"关关"

4. SOUL.md — 行为准则

这是 AI 的”灵魂文件”，定义了核心行为原则。

关键内容：

核心真理（如何与用户互动）
安全边界（什么不能做）
身份验证规则（群聊中的权限控制）
隐私保护原则
群聊行为准则

安全相关：

### Restricted Paths (Never Access Unless Admin)

Do not open, parse, or copy from:
- `~/.ssh/`, `~/.gnupg/`, `~/.aws/`
- Anything that looks like secrets: `*key*`, `*secret*`, `*password*`

5. TOOLS.md — 工具配置

记录本地环境特有的工具配置，如：

SSH 主机别名
摄像头位置
TTS 语音偏好
设备昵称

示例：

### SSH
- home-server → 192.168.1.100, user: admin

### TTS
- Preferred voice: "Nova"
- Default speaker: Kitchen HomePod

6. MEMORY.md — 长期记忆

⚠️ 安全注意：只在主会话（直接对话）中加载

这是 AI 的”长期记忆”，包含：

用户的重要信息
历史决策和约定
项目约定和流程
个人偏好

与每日日志的区别：

	memory/YYYY-MM-DD.md	MEMORY.md
内容	原始对话记录	提炼后的重要信息
用途	追溯具体对话	快速恢复上下文
更新频率	每天自动创建	手动维护
加载场景	所有会话	仅主会话

7. HEARTBEAT.md — 定时任务

配置 AI 的”心跳”检查任务。

用途：

定期检查邮件、日历
监控项目状态
执行周期性维护任务

示例：

# 检查邮件和日历
- Check unread emails
- Check upcoming events (< 2h)
- Update MEMORY.md if needed

Workspace 使用最佳实践

1. 养成记录习惯

每次会话后，AI 会自动记录到 memory/YYYY-MM-DD.md。定期：

回顾日志，发现重复问题
整理有价值的信息到 MEMORY.md
删除过时的记忆

2. 主动更新 MEMORY.md

当发生以下情况时，告诉 AI “记住这个”：

做了重要决策
发现了有用的信息
建立了新的工作流程

3. 保持文件整洁

定期归档旧的 memory/ 文件
更新过时的 TOOLS.md 配置
删除不再需要的 BOOTSTRAP.md

4. 安全使用 MEMORY.md

主会话（直接对话）：可以读取和更新 MEMORY.md
群聊/共享会话：不加载 MEMORY.md，保护隐私
子会话/ACP：不加载 MEMORY.md，保持隔离

会话与 Workspace 的关系

会话类型	加载 AGENTS.md	加载 MEMORY.md	写入权限
Main（主会话）	✅	✅	✅
群聊	✅	❌	受限
子会话	❌	❌	隔离
ACP	❌	❌	绑定目录

快速开始建议

如果你是新用户，按这个顺序配置：

编辑 IDENTITY.md — 给 AI 起个名字
编辑 USER.md — 填写你的基本信息
阅读 AGENTS.md — 了解工作流程
开始对话 — AI 会自动创建每日日志
定期整理 — 把重要信息写入 MEMORY.md

进阶配置

接入 Telegram

找 @BotFather 创建 Bot，获取 token
在 openclaw.yaml 中配置：

channels:
  telegram:
    enabled: true
    bot_token: "your_bot_token_here"

重启服务

自定义模型

支持任何 OpenAI 兼容格式的 API：

models:
  custom:
    - id: my-model
      name: "自定义模型"
      base_url: "https://api.example.com/v1"
      api_key: "your_key"

设置系统提示词

编辑 SOUL.md 中的内容，可以：

定义 AI 的性格和说话方式
设置安全边界
添加群聊规则

常见问题

启动时报错 `Cannot find module`

原因： 依赖未正确安装
解决：

rm -rf node_modules package-lock.json
npm install
npm run build

模型响应超时

原因： 网络问题或模型服务不稳定
解决：

检查 API Key 是否正确
在配置中增加超时时间：
models:
timeout: 60000 # 60秒

如何更新 OpenClaw

cd openclaw
git pull
npm install
npm run build

个人使用技巧

1. 养成记录习惯

每次会话后，AI 会记录到 memory/YYYY-MM-DD.md。定期回顾这些日志，可以：

追踪问题解决过程
发现重复询问的问题
整理成正式文档

2. 利用 MEMORY.md

把重要信息写入 MEMORY.md，比如：

常用服务器地址
项目关键决策
个人偏好设置

这样每次新会话 AI 都能记住。

3. 技能扩展

OpenClaw 支持技能系统，位于 node_modules/openclaw/skills/：

coding-agent — 代码助手
weather — 天气查询
video-frames — 视频处理

也可以自己编写技能，参考现有技能结构。

会话机制详解

OpenClaw 支持多种会话类型，理解它们的区别有助于更好地使用：

Main 会话（主会话）

特点：

通过 Web 界面、Telegram、Discord 等渠道直接对话
持续的历史记录，上下文连贯
可以访问 MEMORY.md 等长期记忆文件
适合日常对话、任务执行

使用场景：

日常问答、闲聊
文件操作、代码编写
需要上下文记忆的任务

子会话（Subagent）

特点：

独立的隔离会话，不影响主会话
可以指定不同的模型或参数
适合并行处理多个任务
完成后结果返回主会话

使用场景：

并行处理多个独立任务
需要不同模型处理同一问题（对比结果）
长时间运行的任务（避免阻塞主会话）
敏感操作（隔离风险）

如何创建：

# 在主会话中调用
spawn subagent "任务描述"

ACP 会话（Agent Coding Protocol）

特点：

专门用于代码编写和开发任务
支持 Codex、Claude Code、Pi 等编码助手
可以绑定到特定目录或项目
支持线程模式（Discord 等群聊场景）

使用场景：

大型项目开发
代码审查和重构
多文件协同修改
需要深度代码分析的任务

如何创建：

# 在 Discord 等支持线程的渠道
spawn acp "实现一个用户认证模块"

会话对比表

特性	Main 会话	子会话	ACP 会话
上下文连续性	✅ 完整历史	❌ 独立	⚠️ 线程内连续
访问 MEMORY.md	✅ 可以	❌ 不可以	❌ 不可以
并行执行	❌ 顺序	✅ 并行	✅ 并行
适合任务	日常对话	独立子任务	代码开发
生命周期	长期	任务完成即结束	可长期/临时

最佳实践

简单任务 → 直接在 Main 会话完成
多个独立任务 → 使用子会话并行处理
复杂开发 → 使用 ACP 会话，绑定到项目目录
需要记忆 → 确保在 Main 会话，或主动更新 MEMORY.md

总结

OpenClaw 的核心优势：

本地部署 — 数据隐私可控
多模型支持 — 随时切换不同 AI
多渠道接入 — Web、Telegram、Discord 等
可扩展 — 技能系统、自定义配置

建议从 Web 界面开始使用，熟悉后再配置其他渠道。

OpenClaw 安装与使用指南

环境说明

安装步骤

1. 安装 Node.js

2. 安装 OpenClaw

3. 配置环境变量

4. 启动服务

基础配置

配置文件位置

关键配置项

使用方法

Web 界面

常用命令

工作目录说明

Workspace 详解

Workspace 目录结构

核心文件详解

1. AGENTS.md — 智能体工作手册

2. IDENTITY.md — AI 身份配置

3. USER.md — 用户信息

4. SOUL.md — 行为准则

5. TOOLS.md — 工具配置

6. MEMORY.md — 长期记忆

7. HEARTBEAT.md — 定时任务

Workspace 使用最佳实践

1. 养成记录习惯

2. 主动更新 MEMORY.md

3. 保持文件整洁

4. 安全使用 MEMORY.md

会话与 Workspace 的关系

快速开始建议

进阶配置

接入 Telegram

自定义模型

设置系统提示词

常见问题

启动时报错 Cannot find module

模型响应超时

如何更新 OpenClaw

个人使用技巧

1. 养成记录习惯

2. 利用 MEMORY.md

3. 技能扩展

会话机制详解

Main 会话（主会话）

子会话（Subagent）

ACP 会话（Agent Coding Protocol）

会话对比表

最佳实践

总结

参考链接

启动时报错 `Cannot find module`