上周 OpenClaw 冲到 GitHub 20 万 Star 的时候我正好在给自己的一个小产品做 Agent 自动化流程。之前用的是自己糊的 LangChain pipeline维护成本已经让我想掀桌了。看到 OpenClaw 的 Skills 生态概念我决定花两天时间把整个 Agent 层迁过去。踩了不少坑但最终效果比我预期好很多——这篇把完整的接入流程和踩坑记录都写出来。OpenClaw 是 2026 年最火的开源 AI Agent 框架核心卖点是 Skills 技能包生态像装插件一样给 Agent 添加能力搜索、代码执行、数据库查询等底层对接任意大模型 API。下面手把手演示从安装到跑通第一个 Skills Agent包含两种模型接入方案的完整代码。先说结论维度说明框架版本OpenClaw v2.4.x2026 年 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-mvenv openclaw-demosourceopenclaw-demo/bin/activate# Windows: openclaw-demo\Scripts\activate# 安装 OpenClaw 核心包 Skills 扩展pipinstallopenclaw2.4.0 pipinstallopenclaw-skills[all]# 包含搜索、代码执行、文件处理等内置 Skills# 验证安装python-cimport openclaw; print(openclaw.__version__)# 输出: 2.4.x装完之后目录结构不用手动创建OpenClaw 有个脚手架命令openclaw init my-agentcdmy-agent会生成这样的结构my-agent/ ├── agent.yaml # Agent 配置模型、Skills 列表 ├── skills/ # 自定义 Skills 目录 ├── prompts/ # 系统提示词 │ └── default.md └── main.py # 入口文件方案一直接对接 OpenAI 兼容 APIOpenClaw 的模型层设计得很干净原生支持 OpenAI 协议。先改agent.yaml# agent.yamlagent:name:my-first-agentmodel:provider:openai_compatiblebase_url:https://api.ofox.ai/v1api_key:${OFOX_API_KEY}model_name:claude-sonnet-4-20250514temperature:0.7max_tokens:4096skills:-name:web_searchenabled:true-name:code_executorenabled:truesandbox:docker# 代码执行用 Docker 沙箱-name:file_readerenabled:true这里我用的是 ofox.ai 的聚合接口。ofox.ai 是一个 AI 模型聚合平台一个 API Key 可以调用 GPT-5、Claude 4.6、Gemini 3 等 50 模型兼容 OpenAI 协议改个base_url就行不用折腾各家不同的鉴权方式。然后写main.pyimportasyncioimportosfromopenclawimportAgent,Conversationasyncdefmain():# 从 yaml 加载配置agentAgent.from_config(agent.yaml)# 初始化 Skills会自动检测 Docker 环境等awaitagent.init_skills()# 创建对话convConversation()# 第一轮让 Agent 搜索并总结responseawaitagent.chat(conv,帮我搜索一下 OpenClaw 2.4 版本的主要更新内容用中文总结)print(fAgent:{response.content})# 查看 Agent 调用了哪些 Skillsforactioninresponse.actions:print(f [Skill]{action.skill_name}:{action.status})ifaction.result:print(f [Result]{action.result[:200]}...)# 第二轮让它写代码并执行responseawaitagent.chat(conv,用 Python 写一个快速排序然后执行测试一下)print(fAgent:{response.content})if__name____main__:os.environ[OFOX_API_KEY]your-key-hereasyncio.run(main())跑一下python main.py正常的话你会看到 Agent 先调用web_searchSkill 去搜索拿到结果后用大模型总结然后第二轮调用code_executorSkill 写代码并在 Docker 沙箱里执行。整个流程 OpenClaw 自动编排不需要手写 chain。方案二用 Python SDK 更精细地控制不想用 yaml 配置、想在代码里动态切换模型和 Skills 的话可以纯 SDK 方式importasynciofromopenclawimportAgent,Skill,ModelConfigfromopenclaw.skillsimportWebSearchSkill,CodeExecutorSkillasyncdefmain():# 手动配置模型model_configModelConfig(provideropenai_compatible,base_urlhttps://api.ofox.ai/v1,api_keyyour-key-here,model_namegpt-5,# 随时切换模型temperature0.5,)# 手动注册 Skillsskills[WebSearchSkill(max_results5),CodeExecutorSkill(sandboxdocker,timeout30,allowed_packages[numpy,pandas,requests]),]agentAgent(nameflexible-agent,modelmodel_config,skillsskills,system_prompt你是一个技术助手擅长代码和技术调研。回答用中文。)awaitagent.init_skills()# 单次调用不需要维护对话resultawaitagent.run(对比一下 Python 3.12 和 3.13 的性能差异给出具体的 benchmark 数据)print(result.content)# 查看 token 消耗print(f\nToken 用量:{result.usage.total_tokens})print(fSkills 调用次数:{len(result.actions)})asyncio.run(main())这种方式可以在运行时动态切换模型。简单任务用 DeepSeek V3 省钱复杂推理切 Claude 4.6# 动态切换模型的示例asyncdefsmart_route(agent,query):根据任务复杂度选模型iflen(query)50and简单inquery:agent.switch_model(deepseek-v3)else:agent.switch_model(claude-sonnet-4-20250514)returnawaitagent.run(query)自定义 Skills 开发这是 OpenClaw 最有意思的部分。内置 Skills 够用但真正的价值在于你可以写自己的 SkillfromopenclawimportSkill,SkillResultclassDatabaseQuerySkill(Skill):自定义数据库查询 Skillnamedatabase_querydescription查询 PostgreSQL 数据库支持自然语言转 SQL# 定义 Skill 的参数 schemaAgent 会根据这个决定何时调用parameters{query:{type:string,description:用户的自然语言查询需求},database:{type:string,enum:[users,orders,products],description:要查询的数据库}}asyncdefexecute(self,query:str,database:str)-SkillResult:# 这里写你的实际逻辑importasyncpg connawaitasyncpg.connect(self.config[db_url])try:# 实际项目里你可能会先用 LLM 把自然语言转成 SQL# 这里简化处理rowsawaitconn.fetch(fSELECT * FROM{database}LIMIT 10)returnSkillResult(successTrue,datastr(rows),messagef查询{database}成功返回{len(rows)}条记录)finally:awaitconn.close()# 注册使用agent.add_skill(DatabaseQuerySkill(config{db_url:postgresql://...}))整体架构用户输入OpenClaw AgentSkills RouterWebSearch SkillCodeExecutor SkillDatabaseQuery Skill自定义 Skill...大模型 APIClaude 4.6GPT-5DeepSeek V3GLM-5Agent 收到用户输入后先让大模型决定要调用哪些 Skills本质上就是 Function CallingSkills 执行完把结果返回给大模型做最终总结。这个循环可以多轮进行直到 Agent 认为任务完成。踩坑记录坑 1Skills 初始化顺序问题await agent.init_skills()必须在agent.chat()之前调用否则会报SkillNotInitializedError。我一开始以为框架会自动 lazy init结果并不会。看了源码才发现 init 阶段会做 Docker 连接检测、搜索 API 密钥验证等必须显式调用。坑 2Docker 沙箱权限CodeExecutorSkill默认用 Docker 沙箱机器没装 Docker 或当前用户没有 docker 权限会直接报错。临时解决方案CodeExecutorSkill(sandboxsubprocess)# 不用 Docker直接 subprocess# ⚠️ 生产环境别这么干有安全风险坑 3并发调用 Skills 时的 token 爆炸OpenClaw 默认并行调用多个 Skills每个 Skill 的结果都会塞进上下文。注册了 5 个 Skills 且 Agent 决定全部调用一轮对话的 token 消耗可能直接翻 5 倍。解决办法# agent.yamlagent:max_concurrent_skills:2# 最多同时调用 2 个 Skillsskill_result_max_tokens:1000# 每个 Skill 结果最多保留 1000 token这两个配置项文档里藏得很深翻了半天 issue 才找到。坑 4agent.yaml里的环境变量不支持.env文件${OFOX_API_KEY}这种写法只读系统环境变量不会自动读.env。要么source .env要么在 Python 里用python-dotenvfromdotenvimportload_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 相关的项目花一个周末上手试试。有问题评论区聊踩到新坑我会更新在这里。