快速入门：5分钟创建你的第一个Agent

欢迎来到 OpenClaw 实战教程系列！OpenClaw 是一个开源的 AI Agent 框架，帮助开发者快速构建、部署和管理智能体应用。本教程将带你从零开始，在 5 分钟内创建并运行你的第一个 AI Agent。无论你是 AI 新手还是有经验的开发者，都能在这里找到清晰的入门路径。

第一步：安装 OpenClaw

OpenClaw 的安装非常简单，只需要一条 pip 命令即可完成。我们推荐使用虚拟环境来隔离项目依赖，避免与其他项目产生冲突。

# 创建并激活虚拟环境
python -m venv openclaw-env
source openclaw-env/bin/activate  # Windows 用户使用: openclaw-env\Scripts\activate

# 安装 OpenClaw
pip install openclaw

# 验证安装是否成功
openclaw --version

安装完成后，你会看到终端输出 OpenClaw 的版本号。如果一切正常，说明你已经成功安装了 OpenClaw 核心框架。OpenClaw 会自动安装所有必要的依赖项，包括大语言模型的接口库、工具调用引擎和任务调度器。

第二步：创建项目

OpenClaw 提供了项目脚手架工具，可以一键生成标准的项目目录结构。每个 OpenClaw 项目都遵循统一的目录规范，这使得团队协作和项目维护变得更加方便。

# 创建一个新的 Agent 项目
openclaw init my-first-agent

# 进入项目目录
cd my-first-agent

# 查看项目结构
tree .
# 输出:
# .
# ├── agents/
# │   └── __init__.py
# ├── tools/
# │   └── __init__.py
# ├── config.yaml
# ├── main.py
# └── requirements.txt

项目创建完成后，你会看到几个关键目录和文件。agents/ 目录用于存放你的 Agent 定义文件，tools/ 目录用于存放自定义工具，config.yaml 是项目的核心配置文件，main.py 是程序入口文件。

第三步：定义你的第一个 Agent

在 OpenClaw 中，Agent 的定义非常直观。你只需要创建一个 Python 类，继承自 BaseAgent，并配置好 Agent 的名称、描述和系统提示词即可。下面我们来创建一个简单的"智能助手"Agent。

# agents/assistant.py
from openclaw import BaseAgent
from openclaw.models import Message

class MyFirstAgent(BaseAgent):
    """你的第一个 AI Agent —— 智能助手"""

    name = "智能助手"
    description = "一个能够回答各种问题并提供建议的通用智能助手"
    model = "gpt-4"  # 使用的大语言模型

    system_prompt = """
    你是一个友好、专业的AI助手。你的职责是：
    1. 准确理解用户的问题
    2. 提供清晰、有条理的回答
    3. 在不确定时主动说明，而不是编造信息
    4. 用简洁易懂的语言解释复杂概念

    回答风格：友好、专业、有条理。
    """

    async def on_message(self, message: Message):
        """处理收到的消息"""
        response = await self.chat(message.content)
        return response

    async def on_start(self):
        """Agent 启动时的初始化逻辑"""
        print(f"[{self.name}] 已启动，准备接收消息！")

上面的代码定义了一个名为"智能助手"的 Agent。其中 system_prompt 是 Agent 的核心灵魂——它决定了 Agent 的行为方式和回答风格。on_message 方法定义了 Agent 收到消息后的处理逻辑，on_start 方法则在 Agent 启动时执行初始化操作。

第四步：配置与运行

接下来，我们需要在 config.yaml 中注册这个 Agent，并配置运行参数。OpenClaw 使用 YAML 格式的配置文件，结构清晰，易于维护。

# config.yaml
app:
  name: "my-first-agent"
  version: "0.1.0"
  log_level: "info"

agents:
  - name: "智能助手"
    module: "agents.assistant"
    class: "MyFirstAgent"
    settings:
      model: "gpt-4"
      temperature: 0.7
      max_tokens: 2048

llm:
  provider: "openai"
  api_key: "${OPENAI_API_KEY}"  # 从环境变量读取

配置文件中的 ${OPENAI_API_KEY} 表示从环境变量中读取 API 密钥，这是一种安全的做法，避免将敏感信息硬编码在配置文件中。你需要在终端中设置环境变量：

# 设置 API 密钥（替换为你的实际密钥）
export OPENAI_API_KEY="sk-your-api-key-here"

# 启动 Agent
openclaw run

运行 openclaw run 后，OpenClaw 会自动加载配置文件，初始化 Agent，并启动一个交互式命令行界面。你现在可以直接在终端中与你的 Agent 对话了！

第五步：测试与验证

启动成功后，你可以输入一些测试消息来验证 Agent 是否正常工作。以下是一些推荐的测试场景：

• 基础问答测试：输入"你好，请介绍一下你自己"，验证 Agent 是否能正确识别自己的身份
• 知识问答测试：输入"请解释什么是机器学习"，验证 Agent 的回答质量
• 多轮对话测试：连续提问几个相关问题，验证 Agent 是否能保持上下文连贯
• 边界测试：输入一些模糊或超出范围的问题，观察 Agent 如何处理

底层原理：发生了什么？

当你运行 openclaw run 时，框架内部实际上执行了一系列精心设计的流程。理解这些流程有助于你更好地使用 OpenClaw 构建复杂的 Agent 应用。

1. 配置加载：OpenClaw 首先解析 config.yaml，读取所有 Agent 的定义和配置参数。环境变量会被自动替换为实际值。
2. Agent 实例化：框架根据配置动态加载对应的 Python 模块，创建 Agent 实例。每个 Agent 都会分配一个独立的消息队列和上下文管理器。
3. LLM 连接建立：Agent 初始化时会与配置的大语言模型建立连接。OpenClaw 支持多种 LLM 提供商，包括 OpenAI、Anthropic、本地模型等，并实现了连接池和自动重试机制。
4. 消息循环启动：Agent 进入主事件循环，等待接收用户输入。每条消息都会经过预处理（如 token 计数、上下文窗口管理）后发送给 LLM。
5. 响应处理：LLM 的响应会经过后处理管道，包括格式校验、安全过滤、日志记录等步骤，最终返回给用户。

整个流程是异步非阻塞的，这意味着即使你同时运行多个 Agent，它们也能高效地并行处理消息。OpenClaw 底层使用了 asyncio 事件循环，确保了出色的并发性能。

下一步

恭喜你！你已经成功创建并运行了第一个 OpenClaw Agent。接下来，你可以继续探索更多高级功能：

• 学习如何使用工作流编排来构建多步骤的复杂任务流程
• 了解如何为 Agent 集成外部工具，让它能够调用 API、查询数据库
• 探索多 Agent 协作模式，让多个 Agent 分工合作完成复杂任务
• 掌握 Prompt 工程技巧，打造更可靠的 Agent 行为

OpenClaw 的世界才刚刚向你展开，继续前进吧！