OpenClaw 新手入门指南：从零开始快速上手

恭喜你决定开始学习 OpenClaw！本指南将帮助你从零开始，快速掌握 OpenClaw 的基本使用方法。无论你是技术新手还是有一定经验的开发者，都能通过本指南顺利入门。

什么是 OpenClaw？

在开始之前，让我们先了解一下 OpenClaw：

  • 开源 AI Agent 框架：用于构建智能助手
  • 多平台支持：Telegram、Discord、飞书、微信等
  • 可自定义：通过技能系统扩展功能
  • 自动化：支持定时任务和自动化工作流

第一步：准备工作

基础环境要求

你需要准备以下环境：

组件 要求 说明
电脑 能联网的电脑 Windows/Mac/Linux
Node.js 18.0+ JavaScript 运行环境
代码编辑器 VS Code 推荐但非必需
通讯账号 Telegram/Discord 用于测试

安装 Node.js

Windows 和 macOS： 1. 访问 Node.js 官网 2. 下载 LTS 版本（推荐） 3. 运行安装程序 4. 验证安装：node --version

Linux (Ubuntu)：

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

第二步：获取 OpenClaw

方式一：克隆项目

# 克隆代码仓库
git clone https://github.com/openclaw/your-repo.git

# 进入目录
cd openclaw

# 安装依赖
npm install

方式二：使用 Docker（推荐）

# 克隆后进入目录
cd openclaw

# 使用 Docker 启动
docker compose up -d

第三步：基础配置

创建配置文件

复制示例配置：

cp config/app.example.yaml config/app.yaml
cp .env.example .env

编辑 .env 文件

# 必填：LLM API Key
OPENAI_API_KEY=sk-your-api-key-here

# 可选：Telegram Bot Token
TELEGRAM_BOT_TOKEN=your-telegram-token

# 可选：Discord Bot Token  
DISCORD_BOT_TOKEN=your-discord-token

重要：获取 API Key

获取 OpenAI API Key

  1. 访问 OpenAI Platform
  2. 注册账号
  3. 进入 API Keys 页面
  4. 创建新的 API Key
  5. 保存好你的 Key，只会显示一次

第四步：运行 OpenClaw

开发模式（推荐新手）

npm run dev

看到类似输出表示启动成功：

🚀 OpenClaw is starting...
📡 Server running on http://localhost:3000
✅ Ready!

打开管理界面

在浏览器中访问：http://localhost:3000

你应该能看到 OpenClaw 的管理界面。

第五步：连接通讯平台

Telegram 连接

  1. 在 Telegram 搜索 @BotFather
  2. 发送 /newbot 创建机器人
  3. 获取 API Token
  4. 在配置文件中填入 Token

Discord 连接

  1. 访问 Discord Developer Portal
  2. 创建应用并添加 Bot
  3. 获取 Bot Token
  4. 在配置文件中填入 Token
  5. 使用生成的邀请链接将 Bot 添加到服务器

第六步：与 AI 对话

测试基本对话

在 Telegram 或 Discord 中发送消息：

你好！

你应该会收到 AI 的回复。

尝试更多对话

帮我解释一下什么是机器学习
推荐一本编程书籍
今天天气怎么样

第七步：使用技能

什么是技能？

技能是扩展 OpenClaw 功能的方式。每个技能可以执行特定任务。

启用内置技能

在 config/skills.yaml 中：

skills:
  - path: "./skills/weather"
    enabled: true
  - path: "./skills/search"
    enabled: true

使用技能

根据技能配置，可以通过以下方式触发：

  • 关键词触发：直接发送关键词
  • 命令触发：发送特定命令如 /天气 北京

新手常见问题

问题 1：API 调用失败

原因：API Key 错误或余额不足

解决： 1. 检查 API Key 是否正确 2. 访问 OpenAI 官网查看账户余额 3. 确认 API Key 有足够次数

问题 2：Bot 不响应

原因：配置或权限问题

解决： 1. 检查 Bot Token 是否正确 2. 确认 Bot 已在群组中 3. 查看日志中的错误信息

问题 3：端口被占用

原因：3000 端口被其他程序占用

解决：

# 查找占用端口的进程
lsof -i :3000

# 更改端口（在 app.yaml 中）
app:
  port: 3001

新手建议

1. 从简单开始

不要急于自定义，先让基本功能正常运行。

2. 查看日志

日志包含大量有用信息，学会查看日志能帮你解决大部分问题：

npm run dev  # 开发模式会在控制台显示日志

3. 善用文档

遇到问题时： 1. 查看本文档 2. 查看官方文档 3. 搜索社区

4. 小步迭代

每次只做一个改动，这样容易定位问题。

下一步学习

当你已经能正常运行 OpenClaw 后，可以继续学习：

进阶内容

主题 说明
技能开发 创建自定义技能
定时任务 设置自动化任务
工作流 构建复杂自动化
自托管 生产环境部署

快速参考

常用命令

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 生产模式构建
npm run build
npm start

# 查看帮助
npm run help

目录结构

openclaw/
├── config/          # 配置文件
├── skills/          # 技能目录
├── data/            # 数据存储
├── logs/            # 日志文件
└── src/             # 源代码

配置文件位置

配置文件 用途
config/app.yaml 主配置
config/skills.yaml 技能注册
config/cron.yaml 定时任务
.env 环境变量

总结

通过本指南，你已经完成了 OpenClaw 的基础入门：

  • ✅ 了解了 OpenClaw 是什么
  • ✅ 完成环境准备
  • ✅ 安装并运行 OpenClaw
  • ✅ 连接了通讯平台
  • ✅ 与 AI 进行了对话

接下来，你可以： - 探索更多功能 - 学习技能开发 - 构建自己的 AI 助手

祝你使用愉快！

相关阅读： - OpenClaw 安装指南 - OpenClaw 教程 - OpenClaw 配置详解