假设项目已发布到PyPI

openclaw OpenClaw帮助 2026-04-09 2

下面我将为您提供一个系统的OpenClaw技术教程,涵盖从概念到实践的各个环节。

假设项目已发布到PyPI-第1张图片-OpenClaw官网 - 龙虾本地部署|安装下载

第一部分：OpenClaw 核心概念解析

1 项目定位

OpenClaw是一个轻量级、可扩展的AI智能体框架，旨在帮助开发者快速构建能够理解用户意图、规划任务、调用工具（函数）并完成闭环的AI应用,其核心思想是：

工具即函数：将外部能力（搜索、计算、API）封装成Python函数。
智能路由：利用大语言模型（LLM）分析用户请求,自动选择并执行正确的工具序列。
状态管理：维护对话和任务执行上下文,支持多轮复杂交互。

2 核心组件

一个典型的OpenClaw智能体系统包含以下模块：

Agent Core (大脑)：负责决策，通常是LLM（如GPT-4、文心一言、通义千问等）。
Tool Registry (工具箱)：所有可用工具的注册中心，每个工具都有清晰的名称、描述和参数模式。
Planner (规划器)：解析用户目标,将其分解为子任务或工具调用序列。
Executor (执行器)：安全、可靠地调用工具,处理返回值。
Memory (记忆)：存储对话历史、工具执行结果和智能体状态。
User Proxy (用户代理)：与用户交互的接口（CLI、Web、API）。

第二部分：环境搭建与快速开始

1 安装

假设OpenClaw是一个Python项目,可以通过pip安装。

# 或从GitHub安装开发版
pip install git+https://github.com/someorg/openclaw.git

2 基础配置

你需要一个LLM的API密钥,这里以OpenAI为例：

import os
from openclaw import OpenClawAgent
os.environ["OPENAI_API_KEY"] = "your-api-key-here"
# 初始化一个基础智能体
agent = OpenClawAgent(
    llm_model="gpt-4-turbo",
    temperature=0.1,
    system_prompt="你是一个专业的AI助手，可以调用工具解决问题。"
)

第三部分：核心功能实战教程

1 定义你的第一个工具

工具是智能体的“手和脚”,定义一个计算阶乘的函数：

from openclaw.tools import tool
@tool(name="calculate_factorial", description="计算一个正整数的阶乘。")
def factorial(n: int) -> str:
    """计算n!。"""
    if n < 0:
        return "错误：输入必须为正整数。"
    result = 1
    for i in range(1, n + 1):
        result *= i
    return f"{n}! = {result}"
# 将工具注册到智能体
agent.register_tool(factorial)

2 同步对话与工具调用

# 用户请求
response = agent.run("请计算5的阶乘。")
print(response)
# 预期输出：模型会识别意图，调用calculate_factorial工具，并返回“5! = 120”。

3 处理复杂查询与自动规划

OpenClaw的强大之处在于处理多步任务。

# 假设我们已经注册了：get_weather(城市)，calculate_travel_time(起点，终点)，book_restaurant(城市，日期，人数)
query = "我下周要去北京出差，帮我查一下天气，然后推荐一家王府井附近的餐厅，预算人均300元。"
response = agent.run(query)
# 智能体可能执行的规划：
# 1. 调用 get_weather(城市="北京") -> 获得天气信息。
# 2. 解析出“王府井附近”、“人均300元”等关键信息。
# 3. 调用 search_restaurant(位置="王府井", 预算=300) -> 获得餐厅列表。
# 4. 综合信息，生成给用户的回复。

4 记忆与上下文

# 开启会话，记忆会自动保存
agent.start_session(session_id="user_123")
response1 = agent.run("我叫张三。")
response2 = agent.run("我的名字是什么？") # 智能体会回答“您是张三。”

第四部分：高级特性与架构

1 自定义规划器

你可以覆盖默认的规划逻辑,实现更复杂的任务分解。

from openclaw.planner import BasePlanner
class MyCustomPlanner(BasePlanner):
    def plan(self, user_input: str, available_tools: List) -> List[Dict]:
        # 你的自定义规划逻辑，例如使用思维树(ToT)或ReAct模式
        plan = [
            {"step": 1, "tool": "web_search", "args": {"query": user_input}},
            {"step": 2, "tool": "summarize", "args": {"text": "<上一步结果>"}}
        ]
        return plan
agent.planner = MyCustomPlanner()

2 工具依赖与流式执行

某些工具的输出是另一个工具的输入,OpenClaw支持定义工具间的依赖关系。

@tool
def get_user_id(name: str) -> str:
    return "user_001"
@tool(depends_on=["get_user_id"]) # 声明依赖
def get_order_history(user_id: str):
    return [{"order_id": "123", "item": "book"}]
# 当用户问“张三的订单历史是什么？”时，智能体会先调用get_user_id，再用其结果调用get_order_history。

3 安全与验证

参数验证：利用Pydantic在工具层进行严格的输入校验。
权限控制：可以为工具打标签（@tool(scope="admin")）,并在执行前检查用户权限。
沙箱执行：对于执行代码等危险工具,可在隔离环境中运行。

4 可观察性与调试

# 启用详细日志，查看智能体的“思考过程”
agent.verbose = True
response = agent.run("...")
# 控制台会输出：分析意图 -> 选择工具A -> 执行结果 -> 选择工具B ...

第五部分：项目实战：构建一个智能数据助手

目标：一个能查询数据库、绘制图表、发送邮件的智能体。

# 1. 定义工具
@tool
def query_sql(sql: str) -> pd.DataFrame:
    # 连接数据库并执行查询
    ...
@tool
def plot_line_chart(data: pd.DataFrame, x: str, y: str):
    # 使用Matplotlib绘图并保存
    ...
@tool
def send_email(to: str, subject: str, body: str, attachment_path: str = None):
    # 发送邮件
    ...
# 2. 组装智能体
agent = OpenClawAgent(
    llm_model="gpt-4",
    system_prompt="你是一个数据助手，可以查询数据、生成图表并通过邮件发送报告。"
)
agent.register_tools([query_sql, plot_line_chart, send_email])
# 3. 执行复杂任务
task = """
请查询上个月销售额前10的产品，生成一个销售额趋势折线图，然后将图表通过邮件发送给zhangsan@company.com。
"""
result = agent.run(task)
print("任务完成！")

第六部分：部署与优化

1 部署为API服务

使用FastAPI快速包装你的智能体。

from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
agent = OpenClawAgent(...) # 初始化生产环境智能体
class QueryRequest(BaseModel):
    session_id: str
    question: str
@app.post("/chat")
async def chat(request: QueryRequest):
    response = agent.run(request.question, session_id=request.session_id)
    return {"response": response}