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 — 了解工作流程

进阶配置

接入 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 界面

常用命令

工作目录说明

进阶配置

接入 Telegram

自定义模型

设置系统提示词

常见问题

启动时报错 Cannot find module

模型响应超时

如何更新 OpenClaw

个人使用技巧

1. 养成记录习惯

2. 利用 MEMORY.md

3. 技能扩展

会话机制详解

Main 会话（主会话）

子会话（Subagent）

ACP 会话（Agent Coding Protocol）

会话对比表

最佳实践

总结

参考链接

启动时报错 `Cannot find module`