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. 核心一步：把百度千帆配置进OpenClaw
3.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 就写 float，int 就写 int，不要用字符串传数值，否则模型在做参数匹配时会报 JSON Schema 校验失败。写完函数后，在配置里加上工具路径，再运行：
openclaw run "水温28，pH8.6，氨氮0.2，帮我算一下喂食量"打开调试日志，你会看到模型先调用 calc_feeding，拿到返回值之后再组织语言回复。如果日志里没有工具调用过程，先检查模型名是否支持 function calling。记住一个原则：模型负责解释，工具负责计算，不要让模型心算喂食量。
4.3 完整日报生成流程示例
把角色、工具、模型串起来后，一次完整的日报生成流程是这样的：
- 项目脚本读取昨日水质 JSON 文件；
- 把数据拼接成一段用户消息，交给 OpenClaw；
- OpenClaw 判断是否需要调用 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 | 未实名或未开通服务 | 完成实名并开通 ModelBuilder |
| 429 Too Many Requests | 并发限流或额度不足 | 加大重试，换轻量模型 |
| 工具不调用 | 提示词未强调或模型不支持 | 换 4.0 档模型，明确要求先调用工具 |
| 响应超时 | 冷启动首 Token 延迟 | timeout 调到 60s 以上 |
| 上下文丢失 | 历史消息被截断或轮次过小 | 调整消息轮次，用摘要替代旧日志 |
接入大模型服务这件事，九成的问题出在“Key 没对、路径不对、模型名不对”这三样上。别急着调业务逻辑，先把第 3.3 节那条测试命令跑通，再往上叠功能，排查成本会低很多。我在接千帆时还发现，把环境变量放进项目启动脚本，比放在全局配置里更不容易在重启后被清掉，这已经是我的固定习惯。
最后再分享一个小技巧：如果千帆控制台里找不到某个模型 ID，不用慌，先在“在线推理 > 预置服务”里把模型部署好，拿到接口实际显示的标准模型 ID，再填回 OpenClaw。所谓“模型不存在”的报错，很多时候只是产品页面名称和接口 ID 对不上。这个细节，足够帮你省下至少半个小时的搜索时间。
这次把“人人养虾”配上千帆之后，我最大的感受是：模型接入只是开始，真正花时间的反而是提示词和工具注册。把这两件事理顺了，后面想换任何大模型服务商都很从容。希望这份记录能让你少走一点弯路。
