1. 先搞清楚OpenClaw和“人人养虾”到底在做什么1.1 OpenClaw是什么一句话说清Agent运行时OpenClaw 是一个开源的 Agent 运行时。通俗点讲它就是一个“智能体工作台”负责把大模型、工具函数、多轮记忆这些模块拼接起来让你不必从零实现模型调用和上下文管理。你只需要告诉它三件事用哪个大模型、挂哪些工具、这个 Agent 要扮演什么角色。剩下的事包括请求怎么发、返回怎么解析、多轮对话的上下文怎么存都由 OpenClaw 帮你处理。我习惯拿饭店打比方OpenClaw 是大堂经理负责接单、安排人手、记住熟客偏好百度千帆是后厨真正的菜品——语义理解、文本生成——由后厨完成。经理不炒菜后厨不管接待两者通过一套标准接口配合。这也是为什么 OpenClaw 本身不内置“大模型”概念它只是把不同的模型服务统一接到自己的流程里来。理解这一点就不容易在配置时搞混“模型服务商”和“Agent框架”的边界。1.2 “人人养虾”项目想解决什么问题“人人养虾”是一个偏应用向的模拟养殖管理项目。模拟场景里有一个对虾养殖池每天产生一批水质数据包括水温、pH、溶氧、氨氮等指标。人工盯这些数据容易漏批量养殖时还要手动整理成日报非常繁琐。这个项目的目标就是让 Agent 每天早上自动读取前一天的记录分析异常给出当天的喂食建议并生成一份可读的养殖日报。如果用传统规则脚本做也不是不行但逻辑会越写越脆氨氮超标是调饲料还是调换水温度低到多少要减料不同方案之间怎么解释这些用 if-else 写出来又长又难维护。换成大模型之后你可以把规则写进提示词再加一两个计算工具Agent 就能按自然语言理解场景把数值背后的原因讲清楚。这才是这个项目选 OpenClaw 而不是普通脚本的原因要的是规则解释能力和灵活交互不是简单的条件分支。1.3 为什么选百度千帆作为推理后端选择百度千帆最直接的一点是它提供 OpenAI 兼容接口OpenClaw 里配成 OpenAI 兼容的 provider 就能直接用不需要写额外的插件。其次千帆是国内可直连访问的模型服务平台对开发者来说省去很多网络环境上的麻烦。文心系列模型在中文场景下的表现比较可靠特别是偏报告型的文本任务日志摘要和改写语感比很多通用开源模型更自然。另外千帆有免费额度和多个档位的模型轻量型号可以跑高频日志摘要复杂型号可以跑决策分析。预算敏感的项目可以先从免费额度开始跑通之后再按需调整。这些因素叠加起来我用它做“人人养虾”的推理后端基本没有遇到迁移成本。如果你之前已经用过 OpenAI 接口那切到千帆的配置思路几乎是一样的。2. 配置前的准备工作账号、密钥和模型选择2.1 千帆控制台要做的事配置前先到千帆的 ModelBuilder 控制台完成实名认证并开通服务。这一步不做后面所有调用都会返回 403。开通后在“应用接入”或“API Key管理”页面创建一组 Key。这里有个要注意的细节百度智能云体系里会区分 API Key 和 Secret Key而在 OpenAI 兼容调用场景下通常用的是 API Key 的 Bearer 认证。先把 API Key 单独复制出来注意不要带上多余的空格或换行。以前我在这个细节上吃过亏复制出来的 Key 只要尾部多一个看不见的换行鉴权就过不了。如果控制台里没看到“API Key管理”入口多半是服务还没有开通。先找到“在线推理 预置服务”点开任意一个模型页面会引导你完成开通和领取免费额度。这个过程和注册普通云服务差不多只是权限刷新需要等一小会儿不用着急。另一点建议是把 Key 存到你本机的密码管理工具或者项目 .env 文件里不要随手贴在聊天窗口。2.2 千帆模型怎么选一张表和两个典型场景千帆上常见的几档模型我实际对比过之后给出一份简化参考模型ID以控制台为准定位适用场景ernie-speed-8k轻量快速日志摘要、简单问答、喂食建议生成ernie-lite-8k更轻量高频低延迟的文本分类ernie-3.5-8k综合均衡日常对话、基础工具调用ernie-4.0-8k复杂推理水质异常综合诊断、多条件决策我在“人人养虾”里的分配是日报生成用 ernie-speed-8k异常诊断用 ernie-4.0-8k。原因很直接——摘要任务对模型能力要求不高轻量模型响应快、费用低而异常归因分析涉及多个指标联动需要更强的推理能力贵一点也值得。如果你不确定先用默认的 3.5 档把流程跑通再根据实际效果调整比一开始就上旗舰模型更省事。不要把模型选型当成“越贵越好”这个场景里速度、成本和中文语感往往更要紧。2.3 确认OpenClaw的版本和配置文件位置接下来回到 OpenClaw 这边。新版本普遍推荐用配置文件管理模型服务旧版本可能还要改环境变量。安装完成后先执行 openclaw --version 确认版本再找到配置文件目录默认一般在 ~/.openclaw/config.yaml。也可以执行 openclaw config --path 直接打印路径比在系统里乱翻高效得多。在动手改配置前建议先跑一条最简单的命令验证 OpenClaw 本体没问题比如 openclaw doctor它会检查配置完整性。如果 doctor 报数据库或日志目录错误先解决它再接入模型否则后面所有测试都会连带失败。我自己通常还会看一眼日志级别调试阶段保持 info 级别可以清楚看到请求和响应的完整路径避免出现问题后两眼一抹黑。3. 核心一步把百度千帆配置进OpenClaw3.1 先拿到千帆的API Key常见认证方式避坑严格来说API Key 应该在前一章准备好但问“为什么一上来就卡住”的人实在太多所以这里单独再讲一遍。千帆控制台里有“安全认证”页面创建 API Key 后把值存好。开发环境可以直接用环境变量生产环境建议走密钥管理服务。注意不要在代码里硬编码 Key尤其是如果你会把项目推到公开仓库这等于把后厨钥匙挂在大门上。关于认证方式我多说一句千帆 v2 接口支持 Bearer 认证OpenClaw 这种 OpenAI 兼容接入方式通常只需要填 api_key 字段它会在请求头里自动拼上 Authorization: Bearer 。所以配置里千万不要加“Bearer ”这个前缀否则最终会变成 Bearer Bearer返回 401。这个错误看起来像“Key不对”其实是格式重复。遇到鉴权失败时先检查这一条能省很多排查时间。3.2 写一份可用的OpenClaw配置下面这份片段是我在本地跑通过的可参考配置llm: default_provider: qianfan providers: qianfan: type: openai_compatible api_key_env: QIANFAN_API_KEY base_url: https://qianfan.baidubce.com/v2 models: - name: ernie-speed-8k max_tokens: 2048 temperature: 0.3 - name: ernie-4.0-8k max_tokens: 4096 temperature: 0.7解释几个关键字段。type 指定兼容格式OpenClaw 会按 /chat/completions 路径拼接请求。api_key_env 指向环境变量名而不是把 Key 直接写死在文件里这样以后换机器或者团队协作都不容易泄露密钥。base_url 填到 v2 这一级就行模型名则填控制台里的具体 ID。temperature 根据任务类型调整日志摘要想要客观统一就调低一点比如 0.3写解释说明可以调到 0.7表达更丰富。如果你用的 OpenClaw 版本字段略有差异比如 models 里要求加 model_type 或 provider_model_map不用担心整体思路是一致的。改完配置先执行 openclaw config test 或重启服务确认配置能被正确解析。没有报错再继续有报错就优先看本地改动的语法比如缩进、冒号后面是否留了空格。3.3 设置环境变量并做连通性测试在项目根目录创建 .env 文件内容大概长这样export QIANFAN_API_KEY你的千帆APIKey如果你的 Shell 重启后会丢变量建议把它写进项目启动脚本而不是全局配置。然后跑一条最简单的 OpenClaw 命令openclaw run 你好请用一句话说明你是什么模型如果配置成功你会看到 Agent 带着模型名和一句自然语言回复。看到回复后先别急着接养虾工具继续测两样东西多轮对话和工具调用雏形。多轮对话可以这样测openclaw run 刚才我说了三句话你还记得第二句吗这个测试的意义在于确认上下文字段能正常传给千帆避免将来日报生成时“前言不搭后语”。如果这里报错大概率不是 Key 的问题而是上下文参数格式不对回到第五节排查。我习惯把这一步叫做“落地测试”模型服务接得对不对一句话就能验出来不需要写复杂的业务逻辑。4. 把“养虾”场景真正跑起来4.1 定义Agent的角色与Prompt模型接入后OpenClaw 并不知道自己要管虾塘所以需要给它一个清晰的系统提示词。我建议把角色定义放在配置的 system_prompt 里而不是埋进每次用户消息中这样上下文更干净。下面是一个我实际用过的角色模板agents: shrimp_manager: system_prompt: | 你是一名养虾场技术员擅长对虾养殖数据分析。 每次收到水质数据后按以下步骤输出 1. 判断水温、pH、溶氧、氨氮是否在合理范围 2. 对异常指标给出原因推测 3. 结合喂食工具计算今天的喂食量 4. 输出一段不超过200字的日报摘要。有一个容易被忽略的点提示词里的步骤顺序就是模型思考的顺序。中文大模型对“先判断、后计算、再总结”这种指令执行得很好。如果你把计算规则放到后面才提工具模型可能会跳过工具直接编一个数字出来这个现象在接入初期特别明显。所以提示词要写得像操作手册一样分步骤模型才会按顺序走。4.2 注册喂食量计算工具让数字有据可查OpenClaw 支持把本地 Python 函数作为工具暴露给模型。我写了一个简化喂食量计算函数# tools/feeding.py def calc_feeding(water_temp: float, ph: float, ammonia: float) - float: base 2.5 if water_temp 20: base * 0.7 elif water_temp 32: base * 0.6 if ph 7.0 or ph 8.5: base * 0.8 if ammonia 0.3: base * 0.7 return round(base, 2)注册工具时OpenClaw 会读取函数名、参数名和类型注释自动生成 tools 描述给模型。这里的关键是参数类型一定写清楚float 就写 floatint 就写 int不要用字符串传数值否则模型在做参数匹配时会报 JSON Schema 校验失败。写完函数后在配置里加上工具路径再运行openclaw run 水温28pH8.6氨氮0.2帮我算一下喂食量打开调试日志你会看到模型先调用 calc_feeding拿到返回值之后再组织语言回复。如果日志里没有工具调用过程先检查模型名是否支持 function calling。记住一个原则模型负责解释工具负责计算不要让模型心算喂食量。4.3 完整日报生成流程示例把角色、工具、模型串起来后一次完整的日报生成流程是这样的项目脚本读取昨日水质 JSON 文件把数据拼接成一段用户消息交给 OpenClawOpenClaw 判断是否需要调用 calc_feeding 工具千帆返回分析文本和日报摘要脚本把结果写入 Markdown 文件。实际生成的输出效果大概是这样昨日水温 26.2℃pH 8.6氨氮 0.18mg/L。pH 偏高建议检查换水频率和藻相氨氮处于正常范围。今日喂食量按工具计算结果为 1.4kg较昨日低 0.2kg建议少量多餐。其余指标正常无需特殊处理。注意看模型没有自己编喂食量而是先调用工具拿到 1.4kg 再写进报告。这就是 OpenClaw 接入千帆后的价值既保留了大模型的表达和归因能力又让关键数字有据可查。第一次跑通时建议把原始数据、工具返回值、最终输出三个文件都存下来方便后面对照排查。日报输出格式如果在多轮后跑偏可以在提示词里附上一个输出模板让模型照着填。5. 实际使用中踩过的坑排查速查表5.1 鉴权报错 401 / 403遇到 401先确认环境变量有没有被正确加载。运行 echo $QIANFAN_API_KEY 看看值是否为空再检查 Key 里有没有复制进去的换行或空格。403 则是服务开通问题回到控制台查看账号是否完成实名、是否开通了 ModelBuilder 服务。还有一个容易忽略的情况在“预置服务”页面看到的模型展示名和“推理示例”里复制的模型 ID 可能不是同一个字符串填错了会报模型不存在而不是鉴权错误。遇到 401/403按“环境变量—Key格式—服务开通—模型ID”的顺序逐项排查基本十分钟内能定位。5.2 429限流和额度不足千帆对并发和每分钟请求数有限制。我第一次做工具调用测试时连续请求太快就撞上 429。解决办法在 OpenClaw 的请求配置里加大重试间隔或者把高频任务切到轻量模型来分摊频率。另一个可能是免费额度用完了到控制台看一下额度明细。如果既没有限流也没有额度问题那就要看看是不是触发了内容安全策略导致请求被拦截。总之429 不一定代表 Key 有问题先看配额再调重试参数。5.3 工具调用不生效这个问题最容易让人困惑模型回复很流畅但就是不调用 calc_feeding。原因主要有三类模型不支持 function calling、tools 参数格式不兼容、提示词没有明确要求使用工具。我的排查顺序是先把模型切到 ernie-4.0-8k它的工具调用能力更强然后看 OpenClaw 日志里有没有 JSON Schema 报错最后检查提示词里是否明确写了“必须调用喂食量工具后再输出结果”。实际经验里第三类原因占多数模型不缺能力缺的是指令约束。5.4 响应超时和输出乱码超时通常集中在首次请求因为模型冷启动需要时间尤其是 4.0 这种大模型。建议把 OpenClaw 的请求 timeout 调到 60 秒以上不要用默认的 15 秒。输出乱码则很大程度上来自温度过高或模型对 JSON 格式理解偏差把 temperature 降到 0.3 基本能缓解。如果输出内容跟当前问题完全不相关更像是模型名配置错误导致的回退行为回到 2.2 节重新选型。5.5 多轮上下文丢失日报生成看起来是单次请求实际联调时经常要追问“为什么 pH 偏高”这时候上下文就很重要。如果 OpenClaw 传过去的历史消息没有被千帆正确接收模型会显得“失忆”。解决方法是确认配置里的 max_history 或 message_window 参数合理例如设置为 20 条同时检查是否因为单条消息太长被截断。千帆的 8k 上下文窗口不算小但如果把完整日报都塞进上下文依旧可能超限。遇到这类问题把对话轮次调小或者用摘要替换旧消息效果立刻会改善。现象常见原因处理方式401 Unauthorized环境变量未加载或 Key 带空格检查 .env 和 echo 输出403 Forbidden未实名或未开通服务完成实名并开通 ModelBuilder429 Too Many Requests并发限流或额度不足加大重试换轻量模型工具不调用提示词未强调或模型不支持换 4.0 档模型明确要求先调用工具响应超时冷启动首 Token 延迟timeout 调到 60s 以上上下文丢失历史消息被截断或轮次过小调整消息轮次用摘要替代旧日志接入大模型服务这件事九成的问题出在“Key 没对、路径不对、模型名不对”这三样上。别急着调业务逻辑先把第 3.3 节那条测试命令跑通再往上叠功能排查成本会低很多。我在接千帆时还发现把环境变量放进项目启动脚本比放在全局配置里更不容易在重启后被清掉这已经是我的固定习惯。最后再分享一个小技巧如果千帆控制台里找不到某个模型 ID不用慌先在“在线推理 预置服务”里把模型部署好拿到接口实际显示的标准模型 ID再填回 OpenClaw。所谓“模型不存在”的报错很多时候只是产品页面名称和接口 ID 对不上。这个细节足够帮你省下至少半个小时的搜索时间。这次把“人人养虾”配上千帆之后我最大的感受是模型接入只是开始真正花时间的反而是提示词和工具注册。把这两件事理顺了后面想换任何大模型服务商都很从容。希望这份记录能让你少走一点弯路。
1. 先搞清楚OpenClaw和“人人养虾”到底在做什么1.1 OpenClaw是什么一句话说清Agent运行时OpenClaw 是一个开源的 Agent 运行时。通俗点讲它就是一个“智能体工作台”负责把大模型、工具函数、多轮记忆这些模块拼接起来让你不必从零实现模型调用和上下文管理。你只需要告诉它三件事用哪个大模型、挂哪些工具、这个 Agent 要扮演什么角色。剩下的事包括请求怎么发、返回怎么解析、多轮对话的上下文怎么存都由 OpenClaw 帮你处理。我习惯拿饭店打比方OpenClaw 是大堂经理负责接单、安排人手、记住熟客偏好百度千帆是后厨真正的菜品——语义理解、文本生成——由后厨完成。经理不炒菜后厨不管接待两者通过一套标准接口配合。这也是为什么 OpenClaw 本身不内置“大模型”概念它只是把不同的模型服务统一接到自己的流程里来。理解这一点就不容易在配置时搞混“模型服务商”和“Agent框架”的边界。1.2 “人人养虾”项目想解决什么问题“人人养虾”是一个偏应用向的模拟养殖管理项目。模拟场景里有一个对虾养殖池每天产生一批水质数据包括水温、pH、溶氧、氨氮等指标。人工盯这些数据容易漏批量养殖时还要手动整理成日报非常繁琐。这个项目的目标就是让 Agent 每天早上自动读取前一天的记录分析异常给出当天的喂食建议并生成一份可读的养殖日报。如果用传统规则脚本做也不是不行但逻辑会越写越脆氨氮超标是调饲料还是调换水温度低到多少要减料不同方案之间怎么解释这些用 if-else 写出来又长又难维护。换成大模型之后你可以把规则写进提示词再加一两个计算工具Agent 就能按自然语言理解场景把数值背后的原因讲清楚。这才是这个项目选 OpenClaw 而不是普通脚本的原因要的是规则解释能力和灵活交互不是简单的条件分支。1.3 为什么选百度千帆作为推理后端选择百度千帆最直接的一点是它提供 OpenAI 兼容接口OpenClaw 里配成 OpenAI 兼容的 provider 就能直接用不需要写额外的插件。其次千帆是国内可直连访问的模型服务平台对开发者来说省去很多网络环境上的麻烦。文心系列模型在中文场景下的表现比较可靠特别是偏报告型的文本任务日志摘要和改写语感比很多通用开源模型更自然。另外千帆有免费额度和多个档位的模型轻量型号可以跑高频日志摘要复杂型号可以跑决策分析。预算敏感的项目可以先从免费额度开始跑通之后再按需调整。这些因素叠加起来我用它做“人人养虾”的推理后端基本没有遇到迁移成本。如果你之前已经用过 OpenAI 接口那切到千帆的配置思路几乎是一样的。2. 配置前的准备工作账号、密钥和模型选择2.1 千帆控制台要做的事配置前先到千帆的 ModelBuilder 控制台完成实名认证并开通服务。这一步不做后面所有调用都会返回 403。开通后在“应用接入”或“API Key管理”页面创建一组 Key。这里有个要注意的细节百度智能云体系里会区分 API Key 和 Secret Key而在 OpenAI 兼容调用场景下通常用的是 API Key 的 Bearer 认证。先把 API Key 单独复制出来注意不要带上多余的空格或换行。以前我在这个细节上吃过亏复制出来的 Key 只要尾部多一个看不见的换行鉴权就过不了。如果控制台里没看到“API Key管理”入口多半是服务还没有开通。先找到“在线推理 预置服务”点开任意一个模型页面会引导你完成开通和领取免费额度。这个过程和注册普通云服务差不多只是权限刷新需要等一小会儿不用着急。另一点建议是把 Key 存到你本机的密码管理工具或者项目 .env 文件里不要随手贴在聊天窗口。2.2 千帆模型怎么选一张表和两个典型场景千帆上常见的几档模型我实际对比过之后给出一份简化参考模型ID以控制台为准定位适用场景ernie-speed-8k轻量快速日志摘要、简单问答、喂食建议生成ernie-lite-8k更轻量高频低延迟的文本分类ernie-3.5-8k综合均衡日常对话、基础工具调用ernie-4.0-8k复杂推理水质异常综合诊断、多条件决策我在“人人养虾”里的分配是日报生成用 ernie-speed-8k异常诊断用 ernie-4.0-8k。原因很直接——摘要任务对模型能力要求不高轻量模型响应快、费用低而异常归因分析涉及多个指标联动需要更强的推理能力贵一点也值得。如果你不确定先用默认的 3.5 档把流程跑通再根据实际效果调整比一开始就上旗舰模型更省事。不要把模型选型当成“越贵越好”这个场景里速度、成本和中文语感往往更要紧。2.3 确认OpenClaw的版本和配置文件位置接下来回到 OpenClaw 这边。新版本普遍推荐用配置文件管理模型服务旧版本可能还要改环境变量。安装完成后先执行 openclaw --version 确认版本再找到配置文件目录默认一般在 ~/.openclaw/config.yaml。也可以执行 openclaw config --path 直接打印路径比在系统里乱翻高效得多。在动手改配置前建议先跑一条最简单的命令验证 OpenClaw 本体没问题比如 openclaw doctor它会检查配置完整性。如果 doctor 报数据库或日志目录错误先解决它再接入模型否则后面所有测试都会连带失败。我自己通常还会看一眼日志级别调试阶段保持 info 级别可以清楚看到请求和响应的完整路径避免出现问题后两眼一抹黑。3. 核心一步把百度千帆配置进OpenClaw3.1 先拿到千帆的API Key常见认证方式避坑严格来说API Key 应该在前一章准备好但问“为什么一上来就卡住”的人实在太多所以这里单独再讲一遍。千帆控制台里有“安全认证”页面创建 API Key 后把值存好。开发环境可以直接用环境变量生产环境建议走密钥管理服务。注意不要在代码里硬编码 Key尤其是如果你会把项目推到公开仓库这等于把后厨钥匙挂在大门上。关于认证方式我多说一句千帆 v2 接口支持 Bearer 认证OpenClaw 这种 OpenAI 兼容接入方式通常只需要填 api_key 字段它会在请求头里自动拼上 Authorization: Bearer 。所以配置里千万不要加“Bearer ”这个前缀否则最终会变成 Bearer Bearer返回 401。这个错误看起来像“Key不对”其实是格式重复。遇到鉴权失败时先检查这一条能省很多排查时间。3.2 写一份可用的OpenClaw配置下面这份片段是我在本地跑通过的可参考配置llm: default_provider: qianfan providers: qianfan: type: openai_compatible api_key_env: QIANFAN_API_KEY base_url: https://qianfan.baidubce.com/v2 models: - name: ernie-speed-8k max_tokens: 2048 temperature: 0.3 - name: ernie-4.0-8k max_tokens: 4096 temperature: 0.7解释几个关键字段。type 指定兼容格式OpenClaw 会按 /chat/completions 路径拼接请求。api_key_env 指向环境变量名而不是把 Key 直接写死在文件里这样以后换机器或者团队协作都不容易泄露密钥。base_url 填到 v2 这一级就行模型名则填控制台里的具体 ID。temperature 根据任务类型调整日志摘要想要客观统一就调低一点比如 0.3写解释说明可以调到 0.7表达更丰富。如果你用的 OpenClaw 版本字段略有差异比如 models 里要求加 model_type 或 provider_model_map不用担心整体思路是一致的。改完配置先执行 openclaw config test 或重启服务确认配置能被正确解析。没有报错再继续有报错就优先看本地改动的语法比如缩进、冒号后面是否留了空格。3.3 设置环境变量并做连通性测试在项目根目录创建 .env 文件内容大概长这样export QIANFAN_API_KEY你的千帆APIKey如果你的 Shell 重启后会丢变量建议把它写进项目启动脚本而不是全局配置。然后跑一条最简单的 OpenClaw 命令openclaw run 你好请用一句话说明你是什么模型如果配置成功你会看到 Agent 带着模型名和一句自然语言回复。看到回复后先别急着接养虾工具继续测两样东西多轮对话和工具调用雏形。多轮对话可以这样测openclaw run 刚才我说了三句话你还记得第二句吗这个测试的意义在于确认上下文字段能正常传给千帆避免将来日报生成时“前言不搭后语”。如果这里报错大概率不是 Key 的问题而是上下文参数格式不对回到第五节排查。我习惯把这一步叫做“落地测试”模型服务接得对不对一句话就能验出来不需要写复杂的业务逻辑。4. 把“养虾”场景真正跑起来4.1 定义Agent的角色与Prompt模型接入后OpenClaw 并不知道自己要管虾塘所以需要给它一个清晰的系统提示词。我建议把角色定义放在配置的 system_prompt 里而不是埋进每次用户消息中这样上下文更干净。下面是一个我实际用过的角色模板agents: shrimp_manager: system_prompt: | 你是一名养虾场技术员擅长对虾养殖数据分析。 每次收到水质数据后按以下步骤输出 1. 判断水温、pH、溶氧、氨氮是否在合理范围 2. 对异常指标给出原因推测 3. 结合喂食工具计算今天的喂食量 4. 输出一段不超过200字的日报摘要。有一个容易被忽略的点提示词里的步骤顺序就是模型思考的顺序。中文大模型对“先判断、后计算、再总结”这种指令执行得很好。如果你把计算规则放到后面才提工具模型可能会跳过工具直接编一个数字出来这个现象在接入初期特别明显。所以提示词要写得像操作手册一样分步骤模型才会按顺序走。4.2 注册喂食量计算工具让数字有据可查OpenClaw 支持把本地 Python 函数作为工具暴露给模型。我写了一个简化喂食量计算函数# tools/feeding.py def calc_feeding(water_temp: float, ph: float, ammonia: float) - float: base 2.5 if water_temp 20: base * 0.7 elif water_temp 32: base * 0.6 if ph 7.0 or ph 8.5: base * 0.8 if ammonia 0.3: base * 0.7 return round(base, 2)注册工具时OpenClaw 会读取函数名、参数名和类型注释自动生成 tools 描述给模型。这里的关键是参数类型一定写清楚float 就写 floatint 就写 int不要用字符串传数值否则模型在做参数匹配时会报 JSON Schema 校验失败。写完函数后在配置里加上工具路径再运行openclaw run 水温28pH8.6氨氮0.2帮我算一下喂食量打开调试日志你会看到模型先调用 calc_feeding拿到返回值之后再组织语言回复。如果日志里没有工具调用过程先检查模型名是否支持 function calling。记住一个原则模型负责解释工具负责计算不要让模型心算喂食量。4.3 完整日报生成流程示例把角色、工具、模型串起来后一次完整的日报生成流程是这样的项目脚本读取昨日水质 JSON 文件把数据拼接成一段用户消息交给 OpenClawOpenClaw 判断是否需要调用 calc_feeding 工具千帆返回分析文本和日报摘要脚本把结果写入 Markdown 文件。实际生成的输出效果大概是这样昨日水温 26.2℃pH 8.6氨氮 0.18mg/L。pH 偏高建议检查换水频率和藻相氨氮处于正常范围。今日喂食量按工具计算结果为 1.4kg较昨日低 0.2kg建议少量多餐。其余指标正常无需特殊处理。注意看模型没有自己编喂食量而是先调用工具拿到 1.4kg 再写进报告。这就是 OpenClaw 接入千帆后的价值既保留了大模型的表达和归因能力又让关键数字有据可查。第一次跑通时建议把原始数据、工具返回值、最终输出三个文件都存下来方便后面对照排查。日报输出格式如果在多轮后跑偏可以在提示词里附上一个输出模板让模型照着填。5. 实际使用中踩过的坑排查速查表5.1 鉴权报错 401 / 403遇到 401先确认环境变量有没有被正确加载。运行 echo $QIANFAN_API_KEY 看看值是否为空再检查 Key 里有没有复制进去的换行或空格。403 则是服务开通问题回到控制台查看账号是否完成实名、是否开通了 ModelBuilder 服务。还有一个容易忽略的情况在“预置服务”页面看到的模型展示名和“推理示例”里复制的模型 ID 可能不是同一个字符串填错了会报模型不存在而不是鉴权错误。遇到 401/403按“环境变量—Key格式—服务开通—模型ID”的顺序逐项排查基本十分钟内能定位。5.2 429限流和额度不足千帆对并发和每分钟请求数有限制。我第一次做工具调用测试时连续请求太快就撞上 429。解决办法在 OpenClaw 的请求配置里加大重试间隔或者把高频任务切到轻量模型来分摊频率。另一个可能是免费额度用完了到控制台看一下额度明细。如果既没有限流也没有额度问题那就要看看是不是触发了内容安全策略导致请求被拦截。总之429 不一定代表 Key 有问题先看配额再调重试参数。5.3 工具调用不生效这个问题最容易让人困惑模型回复很流畅但就是不调用 calc_feeding。原因主要有三类模型不支持 function calling、tools 参数格式不兼容、提示词没有明确要求使用工具。我的排查顺序是先把模型切到 ernie-4.0-8k它的工具调用能力更强然后看 OpenClaw 日志里有没有 JSON Schema 报错最后检查提示词里是否明确写了“必须调用喂食量工具后再输出结果”。实际经验里第三类原因占多数模型不缺能力缺的是指令约束。5.4 响应超时和输出乱码超时通常集中在首次请求因为模型冷启动需要时间尤其是 4.0 这种大模型。建议把 OpenClaw 的请求 timeout 调到 60 秒以上不要用默认的 15 秒。输出乱码则很大程度上来自温度过高或模型对 JSON 格式理解偏差把 temperature 降到 0.3 基本能缓解。如果输出内容跟当前问题完全不相关更像是模型名配置错误导致的回退行为回到 2.2 节重新选型。5.5 多轮上下文丢失日报生成看起来是单次请求实际联调时经常要追问“为什么 pH 偏高”这时候上下文就很重要。如果 OpenClaw 传过去的历史消息没有被千帆正确接收模型会显得“失忆”。解决方法是确认配置里的 max_history 或 message_window 参数合理例如设置为 20 条同时检查是否因为单条消息太长被截断。千帆的 8k 上下文窗口不算小但如果把完整日报都塞进上下文依旧可能超限。遇到这类问题把对话轮次调小或者用摘要替换旧消息效果立刻会改善。现象常见原因处理方式401 Unauthorized环境变量未加载或 Key 带空格检查 .env 和 echo 输出403 Forbidden未实名或未开通服务完成实名并开通 ModelBuilder429 Too Many Requests并发限流或额度不足加大重试换轻量模型工具不调用提示词未强调或模型不支持换 4.0 档模型明确要求先调用工具响应超时冷启动首 Token 延迟timeout 调到 60s 以上上下文丢失历史消息被截断或轮次过小调整消息轮次用摘要替代旧日志接入大模型服务这件事九成的问题出在“Key 没对、路径不对、模型名不对”这三样上。别急着调业务逻辑先把第 3.3 节那条测试命令跑通再往上叠功能排查成本会低很多。我在接千帆时还发现把环境变量放进项目启动脚本比放在全局配置里更不容易在重启后被清掉这已经是我的固定习惯。最后再分享一个小技巧如果千帆控制台里找不到某个模型 ID不用慌先在“在线推理 预置服务”里把模型部署好拿到接口实际显示的标准模型 ID再填回 OpenClaw。所谓“模型不存在”的报错很多时候只是产品页面名称和接口 ID 对不上。这个细节足够帮你省下至少半个小时的搜索时间。这次把“人人养虾”配上千帆之后我最大的感受是模型接入只是开始真正花时间的反而是提示词和工具注册。把这两件事理顺了后面想换任何大模型服务商都很从容。希望这份记录能让你少走一点弯路。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
