Day1我们讲了什么是Agentic AI。今天进入实操环节，手把手教你用OpenClaw搭建AI Agent。
OpenClaw是独立开源的AI Agent运行时框架。它的核心特点是：全栈能力、Skills架构、多Agent协作。适合企业级应用场景。
这篇文章会用到真实的命令和截图，确保你跟着做能跑通。
一、环境准备
1.1 系统要求
OpenClaw支持Linux、macOS、Windows（WSL2）。
推荐配置：
- CPU：4核以上
- 内存：8GB以上（运行Agent建议16GB）
- 磁盘：20GB以上
我的测试环境是Ubuntu 22.04，4核8GB。
1.2 安装Node.js
OpenClaw基于Node.js运行，需要先安装Node.js环境。
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
export NVM_DIR="$HOME/.nvm"
source "$NVM_DIR/nvm.sh"
nvm install 22
nvm use 22
node –version # 确认显示 v22.x.x
1.3 安装OpenClaw
npm install -g openclaw
# 确认安装成功
openclaw –version
二、初始化配置
2.1 运行初始化向导
这个命令会引导你完成基础配置：
- 工作目录：选择你的项目目录，默认是
~/.openclaw/workspace - 模型配置：选择使用的AI模型（支持OpenAI、Anthropic、Azure等）
- 渠道配置：配置消息渠道（QQ/微信/飞书/Telegram等）
2.2 配置文件结构
初始化完成后，在~/.openclaw/目录下会生成以下文件：
├── openclaw.json # 主配置文件
├── workspace/ # 工作区目录
├── memory/ # 记忆存储
├── skills/ # 技能目录
└── sessions/ # 会话存储
2.3 主配置文件解析
openclaw.json是OpenClaw的核心配置文件：
// Agent默认配置
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: "minimax-portal/MiniMax-M2.7",
}
},
// 渠道配置（QQ为例）
channels: {
qqbot: {
enabled: true,
token: "YOUR_BOT_TOKEN"
}
},
// Skills配置
skills: {
load: {
extraDirs: ["~/.openclaw/workspace/skills"]
}
}
}
三、快速验证
3.1 启动Gateway
启动后，打开浏览器访问 http://127.0.0.1:18789 进入控制台。
在控制台你可以：
- 查看运行状态
- 管理配置文件
- 查看日志
- 管理会话
3.2 发送第一条消息
在控制台的”对话”界面，输入：
如果Agent回复了，说明环境搭建成功。
3.3 查看日志
如果遇到问题，查看日志排查：
或者实时查看：
四、核心概念解析
4.1 Agent
Agent是OpenClaw的核心执行单元。它有以下几个关键属性：
- workspace：工作目录，Agent读写文件的位置
- model：使用的模型
- skills：Agent可用的技能列表
- memory：Agent的记忆系统
4.2 Skills
Skills是Agent的能力扩展。每个Skill是一个独立的功能模块，比如：
browser-automation：浏览器自动化feishu-doc：飞书文档操作weather：天气查询
自定义开发Skill是Day3的内容。
4.3 Channels
Channels是Agent的接入渠道。OpenClaw支持：
- QQ（qqbot）
- 微信（wechat）
- 飞书（feishu）
- Telegram
- Discord
4.4 Memory
OpenClaw有三级记忆系统：
- 短期记忆：当前会话上下文
- 长期记忆：跨会话积累的知识
- 工作记忆：任务执行中的中间状态
五、配置你的第一个渠道
以QQ机器人为例，展示如何配置渠道。
5.1 获取QQ机器人Token
- 打开QQ开放平台：https://q.qq.com
- 创建应用，获取AppID和Token
5.2 配置QQ渠道
编辑~/.openclaw/openclaw.json：
channels: {
qqbot: {
enabled: true,
account: {
appId: "YOUR_APP_ID",
token: "YOUR_TOKEN"
}
}
}
}
5.3 重启Gateway
重启后，机器人就会上线，可以接收消息了。
六、常用命令速查
| 命令 | 说明 |
|---|---|
openclaw gateway start |
启动Gateway |
openclaw gateway stop |
停止Gateway |
openclaw gateway restart |
重启Gateway |
openclaw status |
查看状态 |
openclaw logs |
查看日志 |
openclaw config get <path> |
获取配置项 |
openclaw config set <path> <value> |
设置配置项 |
openclaw skills list |
列出已安装技能 |
openclaw skills add <name> |
安装技能 |
openclaw sessions list |
列出会话 |
七、常见问题排查
问题1：端口被占用
解决方案：
lsof -i :18789
# 杀掉进程
kill -9 <PID>
# 或者修改配置使用其他端口
openclaw config set server.port 18790
问题2：模型连接失败
解决方案：
- 检查网络能否访问模型服务商
- 确认API Key配置正确
- 查看日志获取详细错误信息
问题3：Skill加载失败
解决方案：
openclaw logs | grep -i skill
# 禁用出问题的Skill
openclaw config set skills.entries.xxx.enabled false
问题4：内存不足
Agent运行需要足够内存。如果遇到OOM：
- 关闭其他占用内存的程序
- 增加虚拟内存
- 减少模型上下文长度
八、进阶配置
8.1 配置多个Agent
OpenClaw支持配置多个Agent：
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: "minimax-portal/MiniMax-M2.7"
},
// 为不同渠道配置不同Agent
entries: {
"work-agent": {
workspace: "~/work",
model: "openai/gpt-4",
skills: ["coding", "docs"]
},
"life-agent": {
workspace: "~/life",
model: "anthropic/claude-3",
skills: ["weather", "calendar"]
}
}
}
}
8.2 配置多Agent协作
在Day4会详细讲解，这里先了解基本配置：
multiAgent: {
enabled: true,
defaultBroker: "local",
bindings: {
"work-agent": {
channels: ["qqbot"]
}
}
}
}
8.3 配置记忆系统
agents: {
defaults: {
memory: {
search: {
provider: "local",
topK: 5
},
compaction: {
interval: "1h",
threshold: 100
}
}
}
}
}
九、工作目录结构
建议的工作目录结构：
├── workspace/ # 主工作区
│ ├── agents/ # Agent配置
│ ├── skills/ # 自定义Skills
│ ├── scripts/ # 自动化脚本
│ └── memory/ # 长期记忆
├── logs/ # 日志目录
├── data/ # 数据存储
└── config/ # 配置文件备份
在openclaw.json中配置：
agents: {
defaults: {
workspace: "~/openclaw-work"
}
}
}
十、实际案例：搭建一个天气查询Agent
这一节用一个完整的案例，帮助你理解OpenClaw的工作流程。
10.1 需求分析
我们需要一个天气查询Agent，功能包括：
- 查询指定城市的当前天气
- 展示温度、湿度、风速等信息
- 支持未来三天的天气预报
10.2 环境检查
首先确认OpenClaw已正常启动：
确认Gateway运行状态为”running”。
10.3 安装天气Skill
OpenClaw内置了天气查询功能：
10.4 配置天气渠道
编辑openclaw.json：
skills: {
entries: {
weather: {
enabled: true,
config: {
provider: "openweather",
apiKey: "YOUR_API_KEY"
}
}
}
}
}
10.5 测试对话
配置完成后，重启Gateway：
在控制台发送消息：
Agent应该回复类似：
10.6 调试技巧
如果Agent没有正确回复，检查：
- 日志中是否有错误：
openclaw logs - Skill是否正确加载：
openclaw skills list - 网络是否能访问天气API
十一、环境变量的最佳实践
11.1 为什么需要环境变量
在配置文件中直接写入API Key存在安全风险。更安全的做法是使用环境变量：
channels: {
qqbot: {
token: { source: "env", id: "QQ_BOT_TOKEN" }
}
}
}
11.2 设置环境变量
Linux/macOS：
Windows：
11.3 永久保存环境变量
推荐将环境变量写入Shell配置：
echo 'export QQ_BOT_TOKEN="your_token_here"' >> ~/.bashrc
source ~/.bashrc
十二、性能优化建议
12.1 模型选择
不同场景适合不同的模型：
- 日常对话：使用轻量级模型（如MiniMax-M2.7），成本低、响应快
- 复杂推理：使用旗舰模型（如GPT-4、Claude-3），能力强但成本高
- 开发调试：使用中等规模模型，平衡性能和成本
12.2 上下文长度
较长的上下文会消耗更多Token。如果任务不需要很长的上下文，可以在配置中限制：
agents: {
defaults: {
maxContextTokens: 8192
}
}
}
12.3 记忆管理
OpenClaw的长期记忆会随时间积累，可能影响检索效率。建议定期清理：
12.4 并发限制
如果Agent响应变慢，可能是并发请求过多。可以通过配置限制：
agents: {
defaults: {
concurrency: {
maxConcurrent: 5
}
}
}
}
十三、安全配置
13.1 访问控制
配置允许访问的用户列表：
channels: {
qqbot: {
allowFrom: ["USER_ID_1", "USER_ID_2"]
}
}
}
13.2 数据加密
敏感数据建议加密存储：
security: {
encryption: {
enabled: true,
algorithm: "AES-256-GCM"
}
}
}
13.3 审计日志
开启操作审计日志：
security: {
audit: {
enabled: true,
retention: "90d"
}
}
}
十四、总结与作业
14.1 本章要点
- 环境准备：Node.js 22 + OpenClaw
- 初始化配置：通过
openclaw onboard引导配置 - 核心概念：Agent、Skills、Channels、Memory
- 常用命令：start、stop、restart、logs、config
- 进阶配置：多Agent、记忆系统、安全设置
14.2 课后作业
- 在你的电脑上完成OpenClaw环境搭建
- 配置QQ或Telegram机器人渠道
- 实现一个简单的天气查询功能
- 尝试配置多Agent协作
14.3 扩展学习
- 阅读OpenClaw官方文档：docs.openclaw.ai
- 学习Skill开发（Day3内容）
- 探索多Agent协作（Day4内容）
有问题欢迎在评论区留言，我会帮你解答。
下期预告：Day3 自定义Skill开发：从概念到实战——手把手教你开发第一个Skill
来源：OpenClaw官方文档（docs.openclaw.ai）、鲲鹏昇腾开发者大会2026（2026年5月22日）
14.4 常见错误与解决方案
在实际搭建过程中，你可能会遇到以下问题：
错误一：Node版本不兼容
如果遇到”ERR_INVALID_PACKAGE_CONFIG”错误，检查Node版本：
如果版本不对，使用nvm切换：
nvm use 22
错误二：权限不足
Linux/macOS安装时遇到EACCES错误：
或者配置npm的全局目录：
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
错误三：端口被防火墙拦截
如果外部无法访问18789端口：
sudo ufw status
# 开放端口
sudo ufw allow 18789
错误四：消息发送失败
检查机器人是否正确连接到频道：
如果显示”Connection refused”，检查Token配置是否正确。
14.5 最佳实践总结
经过多次环境搭建，我总结了以下最佳实践：
实践一：目录结构清晰
将工作区、配置、日志分开存放，便于管理：
├── config/ # 配置文件备份
├── workspace/ # 工作区
├── logs/ # 日志
├── skills/ # 技能
└── sessions/ # 会话
实践二：版本控制配置
将openclaw.json纳入版本控制，但排除敏感信息：
openclaw.json
sessions/
memory/
使用环境变量存储敏感配置：
实践三：定期备份
重要配置和记忆数据定期备份：
cp ~/.openclaw/openclaw.json ~/.openclaw/config/backup-$(date +%Y%m%d).json
实践四：监控运行状态
使用监控工具跟踪Agent运行状态：
crontab -e
# 添加：每5分钟检查一次Gateway状态
*/5 * * * * openclaw status | grep running || notify-send "OpenClaw down"
14.6 资源推荐
官方资源
- OpenClaw文档：docs.openclaw.ai
- GitHub仓库：github.com/openclaw/openclaw
- 社区论坛：discord.gg/openclaw
学习资源
- 官方示例库：包含多种场景的配置参考
- Skill市场：可安装社区开发的Skills
- 视频教程：B站搜索”OpenClaw教程”
工具推荐
- JSON验证：jsonlint.com（验证配置文件语法）
- API测试：Postman（测试Agent的API接口）
- 日志分析：jq（格式化日志输出）
下期预告：Day3 自定义Skill开发：从概念到实战——手把手教你开发第一个Skill
来源：OpenClaw官方文档（docs.openclaw.ai）、鲲鹏昇腾开发者大会2026（2026年5月22日）
14.7 为什么要学OpenClaw
在众多Agent开发框架中，为什么选择OpenClaw？
第一，OpenClaw是企业级应用的首选。相比其他框架，OpenClaw在稳定性、安全性、可扩展性方面更适合企业环境。OpenClaw作为开源项目，有着深厚的技术积累和服务能力。
第二，OpenClaw的Skills架构非常灵活。每一个Skill都是独立的功能模块，可以单独开发、测试、部署、升级。这种模块化设计让大型项目的协作变得简单。
第三，OpenClaw的多Agent协作能力强大。在Day4中我们会详细讲解如何配置多个Agent协同工作，这在复杂业务场景中非常有用。
第四，OpenClaw有完善的生态。从官方文档到社区论坛，从Skill市场到示例代码，学习资源丰富，遇到问题容易找到解决方案。
14.8 学习路线建议
对于零基础的学习者，我建议按以下路线学习：
第一步，先把环境搭好，能让Agent回复消息。这个过程会遇到各种问题，解决问题的过程就是学习的过程。
第二步，了解核心概念。Agent、Skills、Channels、Memory这些概念必须清晰，不能含糊。
第三步，动手写一个简单的Skill。不需要多么复杂，一个查询天气的Skill就足够。这个过程会让你理解Skill的工作原理。
第四步，尝试配置多Agent。这是进阶内容，在理解单Agent的基础上再学习多Agent协作会容易很多。
14.9 常见误区
学习过程中新手容易犯几个错误。
错误一，只看文档不动手。OpenClaw的文档很详细，但只看不动手永远学不会。一定要跟着教程实际操作。
错误二，过于追求完美配置。刚开始学习时，不需要把配置弄得面面俱到。先让基本功能跑起来，然后逐步优化。
错误三，不看日志直接问问题。很多问题其实在日志里已经有说明。看懂日志是开发者的基本功。
错误四，忽略安全配置。测试环境可以随意，但生产环境必须配置访问控制和数据加密。
14.10 社区资源
OpenClaw有活跃的社区，遇到问题可以先在社区搜索。
官方Discord服务器是最大的社区，有几千名开发者在里面活跃。提问时记得把问题描述清楚，附上日志截图，这样更容易得到有用的回答。
GitHub的Issues也是一个很好的资源。很多常见问题在Issues里都能找到解决方案。
下期预告：Day3 自定义Skill开发：从概念到实战——手把手教你开发第一个Skill
来源：OpenClaw官方文档（docs.openclaw.ai）、鲲鹏昇腾开发者大会2026（2026年5月22日）
14.11 实践是最好的老师
学习OpenClaw最有效的方法就是动手实践。
不要担心把环境搞乱。大不了重装一次系统，或者在虚拟机里全新安装。折腾的过程中你会学到很多东西。
不要害怕看日志。日志看起来复杂，但只要耐心读，都能看懂。绝大部分的错误信息在日志里已经写得清清楚楚。
不要急于求成。先让基本功能跑起来，在这个基础上逐步增加复杂度。罗马不是一天建成的，OpenClaw高手也不是一天练成的。
记住，实践是最好的老师。看十遍不如动手一遍。
我要评论