quick_start.py

openclaw openclaw解答 2026-04-09 1

核心概念与特点

在开始之前，先了解 OpenClaw 的几个核心特点：

quick_start.py-第1张图片-OpenClaw下载官网 - OpenClaw电脑版 | ai小龙虾

一体化：集成了知识库管理（RAG）、智能体工作流（Agent）、对话管理等核心模块。
松耦合：各个模块之间解耦,你可以自由组合或替换其中任一组件。
标准化：提供统一的配置、数据格式和API接口,方便管理和扩展。
生产就绪：注重稳定性、可观测性和易于部署。

基础使用步骤

第零步：环境准备

Python: 确保你的环境是 Python 3.9+。
Git: 用于克隆代码库。

第一步：安装

克隆仓库：

git clone https://github.com/open-claw/openclaw.git
cd openclaw

使用Poetry安装（推荐）： OpenClaw 使用 Poetry 管理依赖。

# 如果没有安装 poetry，请先安装
pip install poetry
# 在项目根目录下，安装依赖（这会创建一个虚拟环境）
poetry install
# 激活虚拟环境
poetry shell

或者，你也可以直接用 pip 安装核心包（可能缺少一些可选依赖）：

pip install open-claw-core

第二步：配置

OpenClaw 的配置非常灵活，主要通过 YAML 配置文件 和 环境变量 来管理。

关键配置文件：
- configs/settings.yaml：核心设置，如LLM API密钥、向量数据库连接、日志级别等。
- configs/model_config.yaml：模型相关配置，如选择哪个模型提供商（OpenAI、通义千问、DeepSeek等）及对应参数。
- configs/prompt_config.yaml：各类任务的提示词模板。
- configs/knowledge_base.yaml：知识库配置，如分词器、Embedding模型、向量库类型等。
必须进行的配置：
- 打开 configs/settings.yaml，找到 llm 部分，设置你的大模型 API 密钥和 Base URL。
```
llm:
  default: openai  # 默认使用 openai 配置
  openai:
    api_key: "sk-your-openai-api-key-here"
    base_url: "https://api.openai.com/v1" # 如果是 Azure 或第三方代理，需要修改
    model: "gpt-4o-mini" # 默认使用的模型
```
- 如果你要使用知识库（RAG），还需要配置向量数据库，默认可能使用 ChromaDB（本地文件存储），无需额外服务，如需使用 Milvus、Qdrant 等，需修改 configs/knowledge_base.yaml 并确保服务已启动。

第三步：核心功能体验

A. 使用知识库（RAG）进行问答

创建/加载知识库：

from openclaw.knowledge_base import KnowledgeBaseFactory
# 1. 从配置文件加载知识库配置
kb = KnowledgeBaseFactory.get_knowledge_base("default") # "default" 对应 knowledge_base.yaml 中的配置名
# 2. 向知识库添加文档（支持 txt, pdf, md, html, docx 等）
# 方式一：添加单个文件
kb.add_document("/path/to/your/document.pdf")
# 方式二：添加整个文件夹
kb.add_documents_from_directory("/path/to/your/docs_folder")
# 文档会被自动切分、向量化并存储到向量数据库

进行问答：

from openclaw.agents import RAGAgent
# 创建 RAG 智能体
rag_agent = RAGAgent(knowledge_base=kb)
# 提问，智能体会自动检索相关知识并生成答案
question = "OpenClaw 框架的主要特点是什么？"
answer, relevant_docs = rag_agent.run(query=question)
print(f"问题: {question}")
print(f"答案: {answer}")
print(f"\n参考来源:")
for doc in relevant_docs:
    print(f"- {doc.metadata.get('source', 'N/A')}: {doc.page_content[:100]}...")

B. 使用工作流智能体（Agent）

OpenClaw 的 Agent 可以编排多个工具（Tools）来完成复杂任务。

定义和运行一个简单Agent：

from openclaw.agents import BaseAgent
from openclaw.tools import ToolRegistry
from openclaw.utils.callbacks import ConsoleCallbackHandler
# 注册一些内置工具（网页搜索、计算器、Python执行等）
# 通常工具会在配置中预定义，这里演示手动创建
tool_registry = ToolRegistry()
# ... (注册工具的代码，具体参考文档和 examples)
# 创建一个基础 Agent，并传入工具
agent = BaseAgent(
    tools=tool_registry.get_tools(),
    callbacks=[ConsoleCallbackHandler()] # 添加回调，在控制台观察执行过程
)
# 运行 Agent
task = "请搜索一下今天北京天气如何，然后用摄氏度告诉我。"
result = agent.run(task)
print(result)

C. 启动API服务（Web界面）

OpenClaw 提供了基于 FastAPI 的完整 API 和可选的 Web 前端。

启动后端API：

# 在项目根目录下
python -m openclaw.serve.api
# 或者使用 uvicorn 直接运行
uvicorn openclaw.serve.api:app --host 0.0.0.0 --port 8000 --reload

访问 http://localhost:8000/docs 查看完整的 Swagger API 文档。

启动前端Web界面（如果项目提供）：
```
# 通常前端是一个单独的工程，需要进入 frontend 目录
cd frontend
npm install
npm run dev
```
然后访问 http://localhost:3000 即可在浏览器中使用图形化界面管理知识库、进行对话等。

配置文件关键项速查

LLM 切换：在 model_config.yaml 中，将 llm_model_name 改为 qwen-max、glm-4 等，并在 settings.yaml 中配置对应 API 密钥即可切换模型供应商。
Embedding 模型切换：在 knowledge_base.yaml 中修改 embeddings 部分，支持 OpenAI、BGE、M3E 等多种模型。
向量数据库切换：在 knowledge_base.yaml 中修改 vector_store 部分，支持 Chroma, FAISS, Milvus, Qdrant, PGVector 等。

快速开始（最简示例）

假设你已经配置好 OpenAI API Key,想快速测试一个不依赖知识库的对话：

from openclaw.llm import LLMFactory
async def main():
    # 1. 从全局配置获取 LLM 实例
    llm = LLMFactory.get_llm() # 默认会读取 settings.yaml 和 model_config.yaml 的配置
    # 2. 直接调用
    response = await llm.agenerate(messages=[{"role": "user", "content": "你好，请介绍一下你自己。"}])
    print(response.content)
if __name__ == "__main__":
    asyncio.run(main())

运行：

python quick_start.py

总结与建议

从配置文件入手：理解 configs/ 目录下的几个 YAML 文件是掌握 OpenClaw 的关键。
运行官方示例：项目 examples/ 目录提供了从简单到复杂的示例代码，是最佳的学习路径。
善用调试和日志：设置 settings.yaml 中的 log_level: DEBUG 可以查看详细的执行过程,对理解框架流程和排查问题非常有帮助。
查阅官方文档：关注项目 GitHub 仓库的 README 和 docs/ 目录,获取最新的功能和最佳实践。