2026 年 3 月 28 日我在做 OpenClaw 的一次例行升级时被一个看似简单的需求卡了整整半天让 AI 自己去 GitHub 拿一份 release 清单和 skill 仓库说明。折腾到最后连 OpenClaw 里的 AI Agent 都被逼无奈放弃了内置的联网工具现场手写一版 Python 爬虫一遍遍请求 GitHub API 把数据拉了回来。这个场景听着魔幻但放在真实环境里其实特别典型——工具链越完整碰到访问限制时反而越狼狈。这篇文章就是当时那套“踩坑实录”的完整复盘。我会讲清楚 OpenClaw 在这种场景下是怎么思考的、我给了它什么任务约束、它写出来的爬虫代码长什么样、中间踩了哪些坑、最后怎么收敛的。适合正在折腾 OpenClaw、或者想用 AI Agent 做自动化数据抓取的同学参考。如果你还没接触过 OpenClaw也没关系前面会先花一点篇幅把背景讲明白。1. 事件背景与核心思路拆解1.1 为什么偏偏是 OpenClaw 来干这个活先交代一下 OpenClaw 是什么。它本质上是一个开源的 AI Agent 运行时你可以把它理解成一个长在命令行里的“数字员工”。你给它一个目标它会自己拆解任务、调用工具、写代码、执行命令、读取结果再决定下一步干什么。和单纯的聊天机器人不一样它真的能在你的机器上落地做事比如改文件、跑脚本、查日志甚至像这次一样自己写一个爬虫。我这次的任务环境是一台 Windows 11 机器上的 WSL Ubuntu 22.04Python 3.11装的是 OpenClaw 的 main 分支源码版。任务本身不复杂我需要让 Agent 去某个 GitHub 仓库下抓取最近的 releases 信息、几个 skill 子仓库的 README然后汇总成一份结构化文档供后续做 skill 配置参考。选 OpenClaw 而不是自己写脚本是因为我想顺带测试它在“外部网络受限”场景下的自主应变能力——结果它真的给了我一个足够意外的答案。1.2 任务卡点AI 想要的数据偏偏在 GitHub 上按理说这种任务对 Agent 来说不算难。OpenClaw 自带 web_search、web_fetch 这类联网工具让它直接搜索或者抓取页面就行。但实际问题在于我所在的内网环境对 GitHub 的访问非常不稳定尤其是 api.github.com 和 raw.githubusercontent.com 这两类域名经常出现连接超时、TLS 握手失败、HTTP 403 限流。AI 第一次尝试用的是 openclaw 内置的 fetch 工具结果连续三次超时。它又试着去搜索引擎找缓存页面拿回来的内容七零八落根本没法用。这时候有意思的事情发生了Agent 在思考日志里写了一句类似“内置工具不可用我将生成一个 Python 脚本通过本地网络请求 GitHub API”的话。也就是说它自己完成了“工具失效 → 切换方案”的决策开始写代码了。这就是标题里“逼得 AI 手敲代码”的来龙去脉。表面上是访问受限把它逼到了墙角本质上却是 Agent 在运行时检测到既有工具链的边界后主动降级到“本地代码执行”这条更底层的路径。我觉得这种思维链比爬虫本身更有价值所以先把背景讲清楚。2. OpenClaw 安装与运行环境准备2.1 环境清单与版本匹配如果你是第一次接触 OpenClaw建议先按这套环境来能少踩很多坑。我的实际配置如下操作系统Windows 11 WSL2Ubuntu 22.04Python3.11.4OpenClaw 对 3.10 支持较好太老的版本容易缺依赖Node.js18.17部分官方 skill 依赖 Node 环境Git2.40OpenClawmain 分支源码版2026.3.28 当天拉取这里有个很容易被忽略的点OpenClaw 虽然是 Python 写的运行时但它很多 skill 是跨语言的比如调用外部工具的 skill 可能需要 Node 或者 Go。所以你不能只盯着 Python 版本最好把 Node 也装好并且确认node --version能在 WSL 里直接执行。我第一次部署时因为没装 Node导致几个内置 skill 加载失败报错还特别隐晦只说“plugin load error”排查了半天才发现是环境缺东西。2.2 安装脚本的两种方式与选择逻辑OpenClaw 官方提供了一键安装脚本核心参数是--method可以指定从 release 包安装还是从 GitHub 的 main 分支检出源码。命令大概长这样bash install.sh --method git --branch main我那次选择 git 方式主要因为两个原因。一是 release 包通常落后 main 分支几个版本而我需要用到当天刚合并的一个 skill 热修复二是我想直接读源码方便后面调试。如果你只是日常使用、追求稳定我更推荐 release 方式至少出问题时你能明确知道自己用的是哪个版本。安装脚本跑完并不是结束还需要执行初始化命令把配置目录和模型 API 信息写好python -m openclaw init python -m openclaw configure --set model.provideropenai --set model.api_keyxxxx注意 configure 命令在不同版本里参数名可能略有差异以python -m openclaw --help为准。我 3 月 28 日拉到的版本里模型配置已经统一到了model.*这个命名空间下之前的llm.*已经被标记为 deprecated 了照旧教程写会直接报 “unknown config key”。2.3 安装期的 GitHub 访问问题提前解决安装阶段我就遇到了 git clone 失败的问题。现象是克隆到一半报RPC failed; curl 56 OpenSSL SSL_read: Connection was reset这种错误在拉取大型仓库时特别常见和仓库大小、网络链路质量都有关系。我当时用了三个组合拳来解决全程都是正规手段不依赖任何第三方代理工具第一浅克隆。只拉最新一次提交历史记录不同步git clone --depth 1 https://github.com/openclaw/openclaw.git第二调整 git 的 http 缓冲参数防止大对象传输时连接被重置git config --global http.postBuffer 524288000 git config --global http.lowSpeedLimit 1000 git config --global http.lowSpeedTime 60第三对于个别子模块仓库我在 Gitee 上找了由项目维护者发布的同步副本直接从国内托管平台 clone速度非常稳定。Gitee 本身是正规的代码托管平台很多开源项目都有官方或社区维护的同步仓库用这种方式绕开国际链路的不稳定是合规且常见的做法。另外我也把 SSH 方式配好了生成了新的 ed25519 密钥并加到 GitHub 账号里。SSH 方式在长连接场景下比 HTTPS 稳定很多后续拉 private 仓库或者 push 代码都用得上。这一步建议提前做等 AI 执行到一半发现没法下载依赖再来配就太被动了。3. 逼 AI 手写爬虫核心环节与实现细节3.1 任务定义与 Prompt 设计要让 AI Agent 在遇到访问问题时主动切换方案最忌讳的是把任务描述得太死。我当时的任务指令大概是这样的请从 GitHub 仓库中获取最近的 release 列表、每个 release 的 tag 名称和发布时间以及仓库根目录 README 的内容。将这些信息汇总成一份 Markdown 报告。如果内置的 fetch 或 search 工具无法访问目标站点请评估替代方案必要时直接编写 Python 脚本在本地执行网络请求来获取数据。脚本需要处理连接超时、HTTP 限流和分页不能只抓取第一页就结束。这段 Prompt 的关键在于最后两句话一是给了 Agent “别死磕内置工具”的许可二是明确要求它处理分页和限流。这两点直接决定了它后续写代码的方向。如果没有这些约束AI 很可能会反复重试内置 fetch 工具直到超时报错然后告诉你“任务失败”而不是自己动手写爬虫。3.2 AI 生成的爬虫脚本拆解AI 最终产出的脚本核心逻辑很清晰我把它简化后贴在这里。它用的是 Python 标准库urllib而不是requests原因是它在执行环境里现装requests需要联网 pip install而当前网络环境不稳定标准库更保险。#!/usr/bin/env python3 # fetch_github_releases.py import json import os import random import time import urllib.request import urllib.error REPO os.environ.get(GH_REPO, openclaw/openclaw) TOKEN os.environ.get(GH_TOKEN, ) BASE fhttps://api.github.com/repos/{REPO}/releases HEADERS { User-Agent: OpenClaw-Agent/1.0, Accept: application/vnd.githubjson, } if TOKEN: HEADERS[Authorization] fBearer {TOKEN} def fetch_page(page): url f{BASE}?per_page30page{page} req urllib.request.Request(url, headersHEADERS) try: with urllib.request.urlopen(req, timeout20) as resp: data json.loads(resp.read().decode(utf-8)) return data, resp.status, dict(resp.headers) except urllib.error.HTTPError as e: return None, e.code, dict(e.headers) def main(): page 1 all_releases [] while True: data, status, headers fetch_page(page) if status 403 or status 429: wait int(headers.get(Retry-After, 60)) print(f[WARN] rate limited, wait {wait}s, flushTrue) time.sleep(wait random.uniform(1, 3)) continue if status ! 200 or not data: break all_releases.extend(data) if len(data) 30: break page 1 time.sleep(random.uniform(2, 5)) with open(releases.json, w, encodingutf-8) as f: json.dump(all_releases, f, ensure_asciiFalse, indent2) print(f[INFO] saved {len(all_releases)} releases) if __name__ __main__: main()这段代码的逻辑并不复杂但有几个细节值得夸一下。它把 page 变量放在循环外逐页累加直到返回的 release 数量小于 30 才结束这说明 AI 理解 GitHub API 分页规则。它还读取了响应头里的Retry-After字段而不是盲目固定等待这在应对限流时非常有用。随机 sleep 2 到 5 秒也是为了避免固定间隔被服务端识别为自动化请求。3.3 为什么是 API 而不是直接抓网页有人可能会问直接抓 GitHub 的 releases 页面 HTML 不行吗为什么要用 API这个问题我特意问过 Agent它的回答很到位GitHub 的网页是服务端渲染加部分动态加载HTML 结构可能随前端版本更新而变化抓下来之后还要做一堆解析清洗而 API 接口返回的是纯 JSON字段结构固定自带分页和限流头信息无论是解析难度还是稳定性都强得多。这个选择背后其实反映了一个更通用的原则能用结构化接口就不要去啃半结构化页面。如果你的任务对象是某个没有 API 的网站那才需要考虑 HTML 解析、动态渲染、验证码对抗那一套。但 GitHub 这类平台API 是第一公民永远优先用它。API 的另一大优势是限流规则透明。匿名请求一小时只有 60 次额度加了 Token 能到 5000 次。脚本里通过Authorization: Bearer头携带 Token是标准做法。我这里设置TOKEN从环境变量读取而不是硬编码在代码里避免密钥泄漏。3.4 限流与命中的参数细节整个请求过程中我让 AI 特别关注几个参数它们直接决定脚本能不能稳定跑完。per_page30GitHub API 单页最大是 100我用 30 是为了降低单次请求的数据量减少超时概率。对于 release 这种大对象列表30 是一个比较稳的量级。重试退避遇到 403/429 时先读取Retry-After头没有就默认 60 秒。然后在基础等待时间上再加 1 到 3 秒的随机偏移避免多个请求同时恢复然后再次撞上限流。超时设置urlopen(timeout20)20 秒没有响应就抛出异常不能让脚本无限期卡住。第一次跑的版本没设置这个参数结果连接挂起AI 还傻傻等着我手动 CtrlC 之后它才反应过来要加超时。这些参数看着不起眼但在真实网络环境里就是“能跑完”和“永远跑不完”的区别。尤其是超时设置没有它脚本遇到连接半开状态时就是一个死循环。4. 踩坑实录与问题排查速查表4.1 安装期和运行期的三大典型故障先说安装期的三个坑每一个都困扰了我不少时间。第一个是git clone大仓库时连接中断。除了前面说的浅克隆和缓冲参数还有一个更隐蔽的原因WSL2 的虚拟网卡在不同网络环境切换后DNS 缓存会变得异常。表现为能 ping 通 ip 但 git clone 就是超时。解决方法是重启 WSLwsl --shutdown后在 Windows 侧重新进入或者手动刷新 DNSsudo resolvectl flush-caches。第二个是模型 API 配置后一直报连接错误。这个其实和 GitHub 无关但也容易误导排查方向。我当时以为又是网络问题折腾了半天最后发现是 OpenClaw 的模型配置里base_url末尾少了一个/v1导致请求路径拼错。所以遇到连接错误时先确认配置的 endpoint 格式再去怀疑网络。第三个是 skill 加载失败报No module named xxx。这个坑的根源在于 OpenClaw 的 skill 依赖了外部 Python 包而你没装到同一个虚拟环境里。解决方法是进入 OpenClaw 的虚拟环境后执行pip install -r skill_requirements.txt有些 skill 还需要 Node 依赖检查一下对应目录下有没有package.json。4.2 AI 代码里的“自作聪明”和调试过程AI 写的代码也不是一遍过它中间出现过三次比较典型的问题。第一次是分页处理缺失。第一版脚本只请求了第一页抓到 30 条 release 就停了完全没意识到可能有更多。我反馈“release 总数应该超过 30”它检查之后补上了翻页逻辑。这个问题的根因是 Agent 在生成代码时优先考虑“能跑通”而不是“跑得全”所以任务描述里必须显式强调“不止第一页”。第二次是限流退避写成了固定值。它最初在每次请求后固定time.sleep(2)完全没有读取Retry-After头。结果跑到第 60 个请求左右GitHub 开始持续返回 403脚本进入了无限“请求-失败-等待”的循环。我让它把响应头和状态码打印到日志里它才意识到问题出在限流字段没被使用。第三次是编码问题。脚本在 Windows 上通过 WSL 运行终端默认编码是 UTF-8 没问题但它写文件时用了ensure_asciiTrue导致所有中文 README 内容变成了\uXXXX转义。我指定使用ensure_asciiFalse并且显式声明encodingutf-8才解决。这个小细节在纯英文环境里完全不会暴露但只要碰到中文内容就一定会出问题。调试方法上我坚持让 AI 在脚本里保留充足的日志输出包括状态码、响应头、当前页码和请求 URL。每次跑失败后把最后几十行日志丢回给它让它自己判断问题出在哪里。这种方式比直接替它改代码高效得多因为 Agent 能看到自己行为的实际反馈后续生成新代码时会更注意这些边界条件。4.3 常见问题排查速查表我把这次遇到的和容易遇到的问题整理成了一张表方便以后对照。现象可能原因解决方案备注git clone 中途连接重置网络链路波动、大对象传输超时浅克隆、调大 http.postBuffer、改 SSH深克隆大仓库时尤其明显api.github.com 请求超时DNS 解析异常或国际链路不稳定刷新 DNS、重启 WSL、换时段重试优先使用 API 而非网页GitHub API 返回 403/429匿名请求超过 60 次/小时加 Token、读取 Retry-After 重试限额 5000 次/小时raw.githubusercontent.com 读文件失败该域名访问不稳定通过 git clone 仓库替代、或用 jsDelivr CDN 拉取 release 文件jsDelivr 是公开 CDN访问相对稳定skill 加载报 No module named xxx依赖未装到同一虚拟环境手动 pip install 对应依赖检查 skill 目录下的 requirements.txt模型 API 报连接失败base_url 路径配置错误核对 endpoint 是否带 /v1 后缀与网络问题区分开脚本写文件中文乱码ensure_ascii 或编码未指定用 ensure_asciiFalse encodingutf-8Windows 下建议加 BOM 便于记事本打开这张表其实覆盖面很广不只是 OpenClaw 本身的问题也包括了使用 AI Agent 做网络自动化任务时的通用坑。建议收藏起来哪天你遇到类似现象直接对着排查就行。5. 让 AI Agent 更可靠的一些心得5.1 给 Agent 明确“能力边界”和任务约束经过这次折腾我最大的体会是Agent 的可靠性不完全是模型能力决定的很大程度上取决于你怎么定义任务边界。如果你只说“帮我抓 GitHub 数据”它可能用内置工具试几次失败后就直接放弃了。但如果你明确告诉它“内置工具不行时可以用 Python 脚本替代脚本必须处理分页、限流和超时”它就真的能做到。这不是玄学而是 Agent 的思维链里任务的子目标被显式拆开了。它知道“抓取数据”不是唯一目标“在工具失效时寻找替代路径”也是一个被认可的目标。所以给 Agent 下指令时最好把“兜底方案”写进任务描述里明确告诉它什么情况下可以切换策略什么参数是必须处理的。这套思路在任何 Agent 平台上都适用不止 OpenClaw。5.2 把这次爬虫固化成 OpenClaw Skill既然这次爬虫已经写出来了下次再遇到类似任务不应该让 AI 重新发明轮子。OpenClaw 支持自定义 skill我把这次的脚本和 Prompt 模板固化成了一个名叫github_fetch的 skill。skill 的目录结构大概是这样.openclaw/ skills/ github_fetch/ SKILL.md scripts/ fetch_releases.pySKILL.md里写的是元信息和调用提示OpenClaw 加载 skill 时会读取这个文件把它注入到 Agent 的上下文里。内容可以很简单--- name: github_fetch description: 从 GitHub API 获取 release 列表、README 或文件内容处理分页与限流。 --- 当用户需要获取 GitHub 仓库信息时使用 scripts/fetch_releases.py。 - 支持环境变量 GH_REPO 和 GH_TOKEN。 - 必须处理分页per_page30循环直到返回数量不足 30。 - 必须处理 403/429 限流读取 Retry-After随机退避 2-5 秒。 - 输出文件统一保存为 JSONUTF-8 编码。这样以后我只要在对话里说“用 github_fetch 拉一下 xxx 仓库的 releases”Agent 就会自动读取 SKILL.md按既定逻辑执行不会再从头写一遍或者踩同样的坑。这个思路强烈推荐任何重复性任务都值得沉淀为 skill。5.3 关于 Agent 自主性的一点反思最后说点更宏观的体会。这次“AI 被逼手写代码爬 GitHub”的事件表面看起来是绕开了访问限制的奇技淫巧本质上是 Agent 系统里“功能降级链”在起作用。内置工具不可用 → 降级到本地代码执行 → 用更基础的原语完成任务。这比“死磕内置工具直到失败”要智能得多。作为使用者我们要做的不是祈祷模型突然开窍而是主动为 Agent 配置这种降级链。比如维护好本地 Python 环境、把常用脚本沉淀成 skill、在 Prompt 里留好兜底策略。Agent 的自主性不是模型单方面给的是你和它共同设计出来的。这次以后我布置任务时都会问自己一句如果内置工具全挂了我的环境还允许 Agent 用什么方式完成任务答案越清晰Agent 的表现就越稳定。有朋友问过我既然最终还是靠写代码解决问题为什么不直接自己写脚本非要绕一大圈让 AI 来干。我的回答是这次不只是为了拿数据更是为了验证这套“AI Agent 本地代码执行”的运行模式是否可靠。从结果看它是可靠的而且在写代码的过程中 AI 还主动处理了分页、限流、编码这些细节比我预期中靠谱。以后遇到类似任务我会让 OpenClaw 直接调 skill 来干把它当成一个会自动写代码的外包工程师来用。