讲讲最近我在openclaw踩的坑吧。（偏小白视角，因为是第一次真正意义上接触别人写好的 Agent 框架）
环境：Windows11本地，主要使用cmd。配置的是google ai studio的免费层级的API key。
从下载、安装到使用，我原本想着照着文档跑起来就好了吧。结果是，除非你是有多年工作经验的架构设计师或者程序员，否则很难不踩坑。但其实我踩的这些坑让我逐渐意识到，OpenClaw在Model、Agent、Tool 之间做了一层非常刻意的架构分离。大多数新手第一次接触时，大概率都会被这种分层设计所绕进去。
今天就列举出最近在OpenClaw上踩的坑，最后再聊聊它的底层逻辑。
一、报错显示没有auth-profile.json
现象：
Agent failed before reply: No API key found for provider "custom-10". Auth store: C:\Users\...\.openclaw\agents\main\agent\auth-profiles.json. Configure auth for this agent (openclaw agents add <id>) or copy auth-profiles.json from the main agentDir.
报错原因： 当前会话我使用的是agent：main，报错的意思是我少了auth-profile.json这个文件。
解决方案： 在cmd执行openclaw agents add main。我将其理解为新注册一个agent。就像给刚出生的宝宝做出生证明一样。再去查看对应的文件路径，就有auth-profile了。
心得体会： 我暂时还不懂为什么初始设置的main agent，不自带auth-profile。我一开始还以为是不是我的路径有中文的原因。还想这想那的，又去问ai、又去逛社区找解决方法，人家报错都告诉你怎么解决了，要么使用openclaw agents add 这个命令去为这个agent配置auth，要么从main agentDirl复制一个auth文件过去。去问gpt、gemini的结果就是，没一个有用的。
由此可知，每个Agent是独立持有Auth的，而不是全局共享。 也就是说，在 OpenClaw 里，API Key 不是属于“你这个人”的，而是属于“这个 Agent 实例”的。这是一个非常重要但很容易被忽略的设计思想。
二、新set了model，为什么没有同步更新给agent？
先明确一件事：models是给人管理的，agents是给openclaw管理的。这俩不属于同一层面。Models 更像是一个给开发者管理的模型注册表，而 Agents 才是实际运行时的执行单元。
所以你新set的model，当然不会让agent进行更新。
也就是说，OpenClaw故意把“模型管理”和“模型使用”拆开了。这是一个很典型的工程解耦设计。
那agent，比如说main，是怎么更新了新模型进去的呢？这个后续有待探究。
三、寻觅一个能白嫖的web search API
为了让agent能联网搜索，我开始寻找可以白嫖的 Web Search API。
但如果你像博主一样，没有VISA卡，只有银联的借记卡。那么恭喜你，这个tool就很不好白嫖来了。
以下是我的尝试：
Brave search API：openclaw默认的web search tool。第一次调用联网搜索时，你的龙虾会提示你，没有配置brave api key。好消息是，它每月有5美金的免费额度（约1000次请求）。坏消息是，需要先订阅一个每月5美金的套餐才能开始使用免费额度。订阅就需要绑银行卡，虽然支持银联，但只支持信用卡。并且我没有VISA。
虚拟信用卡 （虚拟 VISA ） ：WildCard比较稳定，但是前段时间由于政策原因已经停止虚拟信用卡的服务了。Depay，需要虚拟货币，比较麻烦。其他的都不怎么稳定，我不想冒风险。
Tavily / Serper.dev：这两个在 AI 圈很火，但目前 OpenClaw 的 web_search 工具没有原生内置这两个驱动（虽然可以自己写插件支持）。比较麻烦。
Perplexity ： 支持VISA，不支持银联。
Gemini：我现在配置的默认模型是 google/gemini-3-flash-preview。Gemini 有一个自带的功能叫 "Google Search Grounding " 。但是google ai studio的免费层级 模型2.5 flash才支持搜索功能。
事实证明，Agent工具生态对国内开发者现实环境的适配并不友好。
四、Tool Fan-out 一分钟打爆Rate Limit
简单来说，小龙虾经常要用tools，一个tool就去请求一次，导致一分钟内请求次数过多，老是被限制，输出中断，整个流程需要等待冷却时间再继续。（针对我用的免费API）
这其实是典型的 Agent 工程难题：Tool Fan-out 导致的 Rate Limit 崩溃。当Agent逻辑拆得越细，Tool使用得越频繁，这个问题就越明显。目前我还在寻找更好的解决方案。
五、总结
回过头来看，我踩的坑（非外部因素所导致的）很大原因都是因为不够了解openclaw的架构。我最初把它当成一个简单的模型调用工具了，但实际上它是一个在Model、Agent、Tool三层之间做了强隔离的Agent框架。
一开始我只关心怎么把它跑起来，但因为踩的坑，我开始反过来思考：它为什么要这样设计。这是我第一次真正从使用者的角色，走向理解设计者的视角。
附上：openclaw官方文档 、 CLI参考
