AI 学习进阶实战 · 更新于 2026年10月3日 · 约 13 分钟

【AI Agent开发实战】Day2——用OpenClaw搭建你的第一个AI Agent

【AI Agent开发实战】Day2——用OpenClaw搭建你的第一个AI Agent
本文目录

Day1我们讲了什么是Agentic AI。今天进入实操环节,手把手教你用OpenClaw搭建AI Agent。

OpenClaw是独立开源的AI Agent运行时框架。它的核心特点是:全栈能力、Skills架构、多Agent协作。适合企业级应用场景。

这篇文章会用到真实的命令和截图,确保你跟着做能跑通。

一、环境准备

1.1 系统要求

你手上的系统是Windows还是Mac?要不要额外装WSL?

OpenClaw支持Linux、macOS、Windows(WSL2)。

推荐配置:

  • CPU:4核以上
  • 内存:8GB以上(运行Agent建议16GB)
  • 磁盘:20GB以上

我的测试环境是Ubuntu 22.04,4核8GB。

1.2 安装Node.js

Node版本装错了,会在哪一步报出来?

OpenClaw基于Node.js运行,需要先安装Node.js环境。

# 使用nvm安装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安装OpenClaw
npm install -g openclaw
# 确认安装成功
openclaw –version

二、初始化配置

初始化向导里,哪一项你会填错?

2.1 运行初始化向导

向导跑完,你第一件事是确认什么?

openclaw onboard

这个命令会引导你完成基础配置:

  1. 工作目录:选择你的项目目录,默认是~/.openclaw/workspace
  2. 模型配置:选择使用的AI模型(支持OpenAI、Anthropic、Azure等)
  3. 渠道配置:配置消息渠道(QQ/微信/飞书/Telegram等)

2.2 配置文件结构

这几个文件里,你打算先打开哪一个?

初始化完成后,在~/.openclaw/目录下会生成以下文件:

~/.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

控制台能打开但没反应,你会先查哪一项?

openclaw gateway start

启动后,打开浏览器访问 http://127.0.0.1:18789 进入控制台。

在控制台你可以:

  • 查看运行状态
  • 管理配置文件
  • 查看日志
  • 管理会话

3.2 发送第一条消息

在控制台的”对话”界面,输入:

你好,请介绍一下你自己

如果Agent回复了,说明环境搭建成功。

3.3 查看日志

如果遇到问题,查看日志排查:

openclaw logs

或者实时查看:

openclaw logs –follow

四、核心概念解析

这四个概念里,你最难分清的是哪两个?

4.1 Agent

一个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
  • WhatsApp

4.4 Memory

OpenClaw有三级记忆系统:

  • 短期记忆:当前会话上下文
  • 长期记忆:跨会话积累的知识
  • 工作记忆:任务执行中的中间状态

五、配置你的第一个渠道

以QQ机器人为例,展示如何配置渠道。

5.1 获取QQ机器人Token

Token泄露了怎么补救?

  1. 打开QQ开放平台:https://q.qq.com
  2. 创建应用,获取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 restart

重启后,机器人就会上线,可以接收消息了。

六、常用命令速查

配图

命令 说明
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:端口被占用

端口被占,你是杀掉原进程还是改端口?

Error: listen EADDRINUSE 127.0.0.1:18789

解决方案:

# 查看哪个进程占用了端口
lsof -i :18789
# 杀掉进程
kill -9 <PID>
# 或者修改配置使用其他端口
openclaw config set server.port 18790

问题2:模型连接失败

连接不上时,你怀疑过Key还是怀疑过网络?

Error: Connection refused to model provider

解决方案:

  1. 检查网络能否访问模型服务商
  2. 确认API Key配置正确
  3. 查看日志获取详细错误信息

问题3:Skill加载失败

Skill加载失败时,你怎么知道是哪一个?

Error: Failed to load skill xxx

解决方案:

# 查看具体错误
openclaw logs | grep -i skill
# 禁用出问题的Skill
openclaw config set skills.entries.xxx.enabled false

问题4:内存不足

OOM了先加内存还是先减Agent?

Agent运行需要足够内存。如果遇到OOM:

  • 关闭其他占用内存的程序
  • 增加虚拟内存
  • 减少模型上下文长度

八、进阶配置

多Agent这层,你现在有必要配吗?

8.1 配置多个Agent

几个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协作

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
}
}
}
}
}

九、工作目录结构

建议的工作目录结构:

~/openclaw-work/
├── 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已正常启动:

openclaw status

确认Gateway运行状态为”running”。

10.3 安装天气Skill

OpenClaw内置了天气查询功能:

openclaw skills add weather

10.4 配置天气渠道

编辑openclaw.json:

{
skills: {
entries: {
weather: {
enabled: true,
config: {
provider: "openweather",
apiKey: "YOUR_API_KEY"
}
}
}
}
}

10.5 测试对话

配置完成后,重启Gateway:

openclaw gateway restart

在控制台发送消息:

北京今天天气怎么样?

Agent应该回复类似:

北京今天晴,温度25℃,湿度40%,东南风2级。未来三天以晴天为主。

10.6 调试技巧

如果Agent没有正确回复,检查:

  1. 日志中是否有错误:openclaw logs
  2. Skill是否正确加载:openclaw skills list
  3. 网络是否能访问天气API

十一、环境变量的最佳实践

APIKey写在文件里,你之前踩过这个坑吗?

11.1 为什么需要环境变量

换机器部署时,你的手工步骤有几步?

在配置文件中直接写入API Key存在安全风险。更安全的做法是使用环境变量:

{
channels: {
qqbot: {
token: { source: "env", id: "QQ_BOT_TOKEN" }
}
}
}

11.2 设置环境变量

Linux/macOS:

export QQ_BOT_TOKEN="your_token_here"

Windows:

set QQ_BOT_TOKEN=your_token_here

11.3 永久保存环境变量

推荐将环境变量写入Shell配置:

# ~/.bashrc 或 ~/.zshrc
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的长期记忆会随时间积累,可能影响检索效率。建议定期清理:

openclaw memory prune

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 本章要点

这些要点里,哪一条你最容易忘?

  1. 环境准备:Node.js 22 + OpenClaw
  2. 初始化配置:通过openclaw onboard引导配置
  3. 核心概念:Agent、Skills、Channels、Memory
  4. 常用命令:start、stop、restart、logs、config
  5. 进阶配置:多Agent、记忆系统、安全设置

14.2 课后作业

这个作业你需要多久能交?

  1. 在你的电脑上完成OpenClaw环境搭建
  2. 配置QQ或Telegram机器人渠道
  3. 实现一个简单的天气查询功能
  4. 尝试配置多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版本:

node –version # 确保是 v22.x.x

如果版本不对,使用nvm切换:

nvm install 22
nvm use 22

错误二:权限不足

Linux/macOS安装时遇到EACCES错误:

sudo npm install -g openclaw

或者配置npm的全局目录:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

错误三:端口被防火墙拦截

如果外部无法访问18789端口:

# 检查防火墙
sudo ufw status
# 开放端口
sudo ufw allow 18789

错误四:消息发送失败

检查机器人是否正确连接到频道:

openclaw logs | grep "qqbot"

如果显示”Connection refused”,检查Token配置是否正确。

14.5 最佳实践总结

这几条实践你现在做到了几条?

经过多次环境搭建,我总结了以下最佳实践:

实践一:目录结构清晰

将工作区、配置、日志分开存放,便于管理:

~/.openclaw/
├── config/ # 配置文件备份
├── workspace/ # 工作区
├── logs/ # 日志
├── skills/ # 技能
└── sessions/ # 会话

实践二:版本控制配置

将openclaw.json纳入版本控制,但排除敏感信息:

# .gitignore
openclaw.json
sessions/
memory/

使用环境变量存储敏感配置:

export OPENCLAW_SECRET_TOKEN="xxx"

实践三:定期备份

重要配置和记忆数据定期备份:

# 备份配置
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高手也不是一天练成的。

记住,实践是最好的老师。看十遍不如动手一遍。

重复跑的活儿攒到一定量,可以看AI 搭个人助手这个页面,按场景分好了工具和步骤。

Avatar photo

龙主编

龙主编,AI智习室官方媒体主编。 专注 AI 行业观察与实操分享,擅长将复杂技术转化为通俗易懂的实战指南。 坚信 AI 不是取代人类,而是赋能每个人。 内容风格: 真实案例 + 详细干货 + 可操作性 使命: 让普通人也能抓住 AI 时代的红利。