未感染者模拟器
62.73M · 2026-04-13
上周 OpenClaw 冲到 GitHub 20 万 Star 的时候，我正好在给自己的一个小产品做 Agent 自动化流程。之前用的是自己糊的 LangChain pipeline，维护成本已经让我想掀桌了。看到 OpenClaw 的 Skills 生态概念，我决定花两天时间把整个 Agent 层迁过去。踩了不少坑，但最终效果比我预期好很多——这篇把完整的接入流程和踩坑记录都写出来。
OpenClaw 是 2026 年最火的开源 AI Agent 框架，核心卖点是 Skills 技能包生态：像装插件一样给 Agent 添加能力（搜索、代码执行、数据库查询等），底层对接任意大模型 API。下面手把手演示从安装到跑通第一个 Skills Agent，包含两种模型接入方案的完整代码。
| 维度 | 说明 |
|---|---|
| 框架版本 | OpenClaw v2.4.x（2026 年 6 月最新） |
| 支持模型 | GPT-5、Claude 4.6、Gemini 3、GLM-5、Qwen 3、DeepSeek V3 等 |
| 核心概念 | Agent → Skills → Tools 三层架构 |
| 上手难度 | 比 LangChain 简单，比 AutoGen 灵活 |
| 本文耗时 | 跟着走大概 30 分钟能跑通 |
Python 3.11+，建议用 3.12。OpenClaw 从 v2.3 开始强依赖 asyncio 的一些新特性，3.10 以下直接报错。
# 创建虚拟环境
python -m venv openclaw-demo
source openclaw-demo/bin/activate # Windows: openclaw-demoScriptsactivate
# 安装 OpenClaw 核心包 + Skills 扩展
pip install openclaw>=2.4.0
pip install openclaw-skills[all] # 包含搜索、代码执行、文件处理等内置 Skills
# 验证安装
python -c "import openclaw; print(openclaw.__version__)"
# 输出: 2.4.x
装完之后目录结构不用手动创建，OpenClaw 有个脚手架命令：
openclaw init my-agent
cd my-agent
会生成这样的结构：
my-agent/
├── agent.yaml # Agent 配置（模型、Skills 列表）
├── skills/ # 自定义 Skills 目录
├── prompts/ # 系统提示词
│ └── default.md
└── main.py # 入口文件
OpenClaw 的模型层设计得很干净，原生支持 OpenAI 协议。先改 agent.yaml：
# agent.yaml
agent:
name: "my-first-agent"
model:
provider: "openai_compatible"
base_url: "https://api.ofox.ai/v1"
api_key: "${OFOX_API_KEY}"
model_name: "claude-sonnet-4-20250514"
temperature: 0.7
max_tokens: 4096
skills:
- name: "web_search"
enabled: true
- name: "code_executor"
enabled: true
sandbox: "docker" # 代码执行用 Docker 沙箱
- name: "file_reader"
enabled: true
这里我用的是 ofox.ai 的聚合接口。ofox.ai 是一个 AI 模型聚合平台，一个 API Key 可以调用 GPT-5、Claude 4.6、Gemini 3 等 50+ 模型，兼容 OpenAI 协议，改个 base_url 就行，不用折腾各家不同的鉴权方式。
然后写 main.py：
import asyncio
import os
from openclaw import Agent, Conversation
async def main():
# 从 yaml 加载配置
agent = Agent.from_config("agent.yaml")
# 初始化 Skills（会自动检测 Docker 环境等）
await agent.init_skills()
# 创建对话
conv = Conversation()
# 第一轮：让 Agent 搜索并总结
response = await agent.chat(
conv,
"帮我搜索一下 OpenClaw 2.4 版本的主要更新内容，用中文总结"
)
print(f"Agent: {response.content}")
# 查看 Agent 调用了哪些 Skills
for action in response.actions:
print(f" [Skill] {action.skill_name}: {action.status}")
if action.result:
print(f" [Result] {action.result[:200]}...")
# 第二轮：让它写代码并执行
response = await agent.chat(
conv,
"用 Python 写一个快速排序，然后执行测试一下"
)
print(f"Agent: {response.content}")
if __name__ == "__main__":
os.environ["OFOX_API_KEY"] = "your-key-here"
asyncio.run(main())
跑一下：
python main.py
正常的话你会看到 Agent 先调用 web_search Skill 去搜索，拿到结果后用大模型总结，然后第二轮调用 code_executor Skill 写代码并在 Docker 沙箱里执行。整个流程 OpenClaw 自动编排，不需要手写 chain。
不想用 yaml 配置、想在代码里动态切换模型和 Skills 的话，可以纯 SDK 方式：
import asyncio
from openclaw import Agent, Skill, ModelConfig
from openclaw.skills import WebSearchSkill, CodeExecutorSkill
async def main():
# 手动配置模型
model_config = ModelConfig(
provider="openai_compatible",
base_url="https://api.ofox.ai/v1",
api_key="your-key-here",
model_name="gpt-5", # 随时切换模型
temperature=0.5,
)
# 手动注册 Skills
skills = [
WebSearchSkill(max_results=5),
CodeExecutorSkill(
sandbox="docker",
timeout=30,
allowed_packages=["numpy", "pandas", "requests"]
),
]
agent = Agent(
name="flexible-agent",
model=model_config,
skills=skills,
system_prompt="你是一个技术助手，擅长代码和技术调研。回答用中文。"
)
await agent.init_skills()
# 单次调用，不需要维护对话
result = await agent.run(
"对比一下 Python 3.12 和 3.13 的性能差异，给出具体的 benchmark 数据"
)
print(result.content)
# 查看 token 消耗
print(f"nToken 用量: {result.usage.total_tokens}")
print(f"Skills 调用次数: {len(result.actions)}")
asyncio.run(main())
这种方式可以在运行时动态切换模型。简单任务用 DeepSeek V3 省钱，复杂推理切 Claude 4.6：
# 动态切换模型的示例
async def smart_route(agent, query):
"""根据任务复杂度选模型"""
if len(query) < 50 and "简单" in query:
agent.switch_model("deepseek-v3")
else:
agent.switch_model("claude-sonnet-4-20250514")
return await agent.run(query)
这是 OpenClaw 最有意思的部分。内置 Skills 够用，但真正的价值在于你可以写自己的 Skill：
from openclaw import Skill, SkillResult
class DatabaseQuerySkill(Skill):
"""自定义数据库查询 Skill"""
name = "database_query"
description = "查询 PostgreSQL 数据库，支持自然语言转 SQL"
# 定义 Skill 的参数 schema（Agent 会根据这个决定何时调用）
parameters = {
"query": {
"type": "string",
"description": "用户的自然语言查询需求"
},
"database": {
"type": "string",
"enum": ["users", "orders", "products"],
"description": "要查询的数据库"
}
}
async def execute(self, query: str, database: str) -> SkillResult:
# 这里写你的实际逻辑
import asyncpg
conn = await asyncpg.connect(self.config["db_url"])
try:
# 实际项目里你可能会先用 LLM 把自然语言转成 SQL
# 这里简化处理
rows = await conn.fetch(f"SELECT * FROM {database} LIMIT 10")
return SkillResult(
success=True,
data=str(rows),
message=f"查询 {database} 成功，返回 {len(rows)} 条记录"
)
finally:
await conn.close()
# 注册使用
agent.add_skill(DatabaseQuerySkill(config={"db_url": "postgresql://..."}))
graph TB
User[用户输入] --> Agent[OpenClaw Agent]
Agent --> Router{Skills Router}
Router --> S1[WebSearch Skill]
Router --> S2[CodeExecutor Skill]
Router --> S3[DatabaseQuery Skill]
Router --> S4[自定义 Skill...]
Agent --> LLM{大模型 API}
LLM --> M1[Claude 4.6]
LLM --> M2[GPT-5]
LLM --> M3[DeepSeek V3]
LLM --> M4[GLM-5]
S1 --> Agent
S2 --> Agent
S3 --> Agent
style Agent fill:#e1f5fe
style Router fill:#fff3e0
style LLM fill:#f3e5f5
Agent 收到用户输入后，先让大模型决定要调用哪些 Skills（本质上就是 Function Calling），Skills 执行完把结果返回给大模型做最终总结。这个循环可以多轮进行，直到 Agent 认为任务完成。
坑 1：Skills 初始化顺序问题
await agent.init_skills() 必须在 agent.chat() 之前调用，否则会报 SkillNotInitializedError。我一开始以为框架会自动 lazy init，结果并不会。看了源码才发现 init 阶段会做 Docker 连接检测、搜索 API 密钥验证等，必须显式调用。
坑 2：Docker 沙箱权限
CodeExecutorSkill 默认用 Docker 沙箱，机器没装 Docker 或当前用户没有 docker 权限，会直接报错。临时解决方案：
CodeExecutorSkill(sandbox="subprocess") # 不用 Docker，直接 subprocess
# ️ 生产环境别这么干，有安全风险
坑 3：并发调用 Skills 时的 token 爆炸
OpenClaw 默认并行调用多个 Skills，每个 Skill 的结果都会塞进上下文。注册了 5 个 Skills 且 Agent 决定全部调用，一轮对话的 token 消耗可能直接翻 5 倍。解决办法：
# agent.yaml
agent:
max_concurrent_skills: 2 # 最多同时调用 2 个 Skills
skill_result_max_tokens: 1000 # 每个 Skill 结果最多保留 1000 token
这两个配置项文档里藏得很深，翻了半天 issue 才找到。
坑 4：agent.yaml 里的环境变量不支持 .env 文件
${OFOX_API_KEY} 这种写法只读系统环境变量，不会自动读 .env。要么 source .env，要么在 Python 里用 python-dotenv：
from dotenv import load_dotenv
load_dotenv() # 在 Agent.from_config 之前调用
OpenClaw 的 Skills 生态是目前 Agent 框架里设计最干净的——比 LangChain 的 Tool 清爽，比 AutoGen 的多 Agent 通信简单。我现在的工作流是：简单任务用 DeepSeek V3 跑 Skills，复杂推理切 Claude 4.6，通过 ofox.ai 聚合 API 一个 Key 搞定所有模型切换，不用维护一堆密钥。
Skills 市场里社区贡献的技能包也越来越多了，很多场景直接拿来用就行。如果你也在做 Agent 相关的项目，花一个周末上手试试。
有问题评论区聊，踩到新坑我会更新在这里。
