GitHub深度拆解：OpenClaw三大核心模块实战指南

你试过让AI自动查竞品价格、下载PDF报告、再整理成Excel吗？每次都要写一堆Selenium脚本，反复处理文件权限，手动调度任务顺序？OpenClaw（GitHub @openclaw）不是“黑盒AI应用”，而是一套可拆、可换、可调试的开源AI助手骨架。今天不讲概念，直接本地跑通它的三大核心模块：agent_runtime（智能体调度引擎）、browser_control（浏览器自动化控制）、file_executor（安全文件执行器）。

问题

AI工作流卡在三关：调度混乱、网页操作不稳定、不敢让AI运行代码。本地实验总失败，二次开发更无从下手。

方案

用 OpenClaw 的三个独立 PyPI 包，按需安装、单独测试、自由组合。每个模块都自带 CLI 和最小示例，代码即文档，不用读完 README 就能跑起来。

步骤一：装 agent_runtime —— 让AI“有章法地思考”

这是系统的“大脑调度器”。它不干具体活，但决定：什么时候调浏览器？结果出来后交给谁处理？出错了重试几次？
裸调 LLM API 容易陷入“发完请求就等结果”的僵直状态。真实任务（比如“比价→截图→生成摘要”）必须分阶段、带状态、可中断。

pip install agent-runtime

验证：运行内置 demo，模拟一个两步任务（先查天气，再推荐穿搭）：

agent-runtime demo --steps 2

终端逐行打印：[STEP 1] calling llm... → got response → [STEP 2] calling tool...。这就是调度引擎在工作——它把大目标拆成小动作，并记住当前走到哪一步。

步骤二：装 browser_control —— 让AI真正“点得准、看得清”

别再手写 Selenium！这个模块封装 Playwright，提供统一 API 控制 Chrome/Firefox，默认启用无头模式 + 自动等待 + 元素高亮（调试时加 --debug，AI点击的按钮会被黄色边框圈住）。

它把“找元素”抽象成自然语言指令，比如：

from browser_control import BrowserController

ctrl = BrowserController(headless=False)
ctrl.go_to("https://httpbin.org/forms/post")
ctrl.fill("input[name='email']", "test@yitb.com")  # 不用写 CSS 选择器
ctrl.click("Submit")  # AI 可直接说“点提交按钮”

本地快速集成：一行命令启动服务（供其他模块调用）：

browser-control serve --port 8001

然后用 curl 测试：

curl -X POST http://localhost:8001/action \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","action":"click","target":"h1"}'

返回 {"status":"success","screenshot":"/tmp/screen_abc123.png"} —— 成功！

步骤三：装 file_executor —— 让AI“敢运行，但不乱跑”

AI生成 Python 脚本想自动处理 Excel？传统方案要么全放行（危险），要么全禁止（废掉能力）。file_executor 用沙箱机制：只允许读写指定目录、禁用 os.system、超时强制终止。

exec() 是 Python 最危险的函数之一，而 AI 生成的代码常含 import requests; requests.get(...) 这类隐藏风险。

启动沙箱服务：

pip install file-executor
file-executor serve --allow-read /tmp --allow-write /tmp --timeout 10

传一段安全脚本试试（它会自动检查 imports 和危险函数）：

curl -X POST http://localhost:8002/execute \
  -H "Content-Type: application/json" \
  -d '{
        "code": "with open(\"/tmp/hello.txt\", \"w\") as f: f.write(\"AI wrote this safely\")",
        "language": "python"
      }'

返回 {"output":"", "error":""} —— 文件已写入 /tmp/hello.txt，全程没越权。

常见问题

• Q：模块间怎么通信？
  A：全部走 HTTP REST API（如 browser-control 启在 :8001，agent_runtime 默认调它）。你也可以用 requests 直接调，不依赖任何 SDK。
• Q：能不用 Docker 吗？
  A：完全可以。三个模块都是纯 Python，pip install 后 xxx serve 即启，连 Redis 都不依赖。
• Q：中文网页支持吗？
  A：browser_control 默认启用 --lang=zh-CN，自动处理中文输入框和字体渲染。

下一步

现在你已掌握 OpenClaw 的“三大件”，下一步可以：
✅ 把 browser_control 接入你自己的 Claude 工具调用逻辑（教程：Claude Tool Use 本地实操）
✅ 用 file_executor 搭配 Ollama 本地模型，实现“AI 写脚本 → 沙箱执行 → 返回结果”闭环（教程：Ollama + OpenClaw 构建离线AI工作流）
✅ 直接 fork openclaw/agent-runtime ，修改 step.py 加一个自定义动作（比如“发邮件”），5 分钟就能让 AI 学会新技能。

代码就在 GitHub，打开就懂，改了就用。AI 工作流不该是拼乐高，而是拧螺丝——每个模块严丝合缝，你自己才是总工程师。