OpenClaw接入百炼平台：从本地模型迁移到云端API的完整配置指南

最近我把本地跑的 OpenClaw 接上了百炼平台的免费模型，折腾了一晚上总算把全链路跑通了。如果你也在用 OpenClaw 这类本地智能体框架，又不想为了一个演示项目专门配 GPU 跑大模型，这篇文章大概率能帮你省掉不少弯路。OpenClaw 本身负责本地任务调度、工具执行和上下文管理，模型推理放到百炼的云端接口，配置上其实就几行参数的事，但真正落地时会碰到各种报错和边界情况。我会把从创建 API Key、定位 base_url、改配置文件，到跑通第一句对话以及排查常见问题的完整过程都写出来，尽量做到照着操作就能通。

1. 为什么要把 OpenClaw 从本地搬到云端

1.1 本地模型让我又爱又恨

先说清楚我最初的环境。OpenClaw 跑在一台普通的开发机上，没有独立显卡，只能靠 CPU 推理小尺寸模型。之前我图省事，在本地跑了一个几 B 参数量的模型，速度勉强能接受，但只要是涉及多轮对话、长上下文，或者需要在一次回复里连续调用两个以上工具，模型就开始“犯迷糊”，经常答非所问，甚至把工具参数凭空捏造出来。这种问题在小模型上几乎无解，不是调 prompt 能救回来的。

更麻烦的是资源占用。我这边开着编辑器、数据库、几个定时脚本，OpenClaw 进程再加载一个本地模型，内存和 CPU 直接拉满。有时候模型推理占着 CPU，其他服务响应变得极慢，整个开发环境像被冻住。我也想过单独搞一台带 GPU 的机器，但为了一个个人项目去增加硬件成本，实在不划算。所以当时就萌生了一个想法：OpenClaw 本身只做框架调度，为什么不让它去调用云端更强、更便宜甚至免费的模型接口呢？

还有一个痛点是模型升级。本地模型想升级，得重新下载、重新验证效果，一次折腾至少半天。而云端模型接口基本是平台在维护，当你把模型名从老版本切到新版本，改一个字段就能用上更强的能力。对我这种喜欢折腾但又不想把时间耗在反复部署上的人来说，接入云端明显更符合预期。

1.2 云端模型服务补上了哪些短板

我最后选择把模型出口切到百炼平台，主要是看中它两点：OpenAI 兼容接口和免费额度。OpenAI 兼容意味着 OpenClaw 这类工具不需要写专门的适配层，只要把接口地址和密钥换成云端服务的，就能把请求发出去。很多开源项目本身就支持openai类型的 provider，你只需要填base_url和api_key，剩下的格式转换框架都会处理。

再就是免费额度。对个人开发者来说，跑通一个功能、做点自动化脚本、验证智能体流程，最怕的就是模型调用费用不可控。百炼平台上有可以免费调用的模型额度，日常轻量使用基本够用。我不确定你看到这篇文章的时候免费策略是否调整，但当时我实测下来，个人小流量调用完全 OK，不需要绑卡充值也能跑起来。这个“先免费跑通，再按需付费”的模式，非常适合项目早期验证。

接口稳定性也是我实际体验后觉得值得说的点。本地模型一旦负载高了，请求排队、掉速都算正常的；云端接口则比较稳，至少我连续调试两三个小时后，响应耗时依然保持在可接受范围内，没有出现本地模型那种越跑越卡的衰减感。当然，这只是个人体验，不同时段、不同网络环境下会有差异，但作为日常开发调试，它确实让我省心不少。

1.3 什么时候不建议接云端

虽然接云端好处明显，但有些场景我建议你还是保留本地模型。最典型的就是隐私敏感的数据。OpenClaw 在对话过程中会把系统提示词、用户输入、工具定义，甚至工具执行结果一起发给云端模型接口。如果这些内容涉及个人隐私、公司内部文档、未公开的业务信息，上传到第三方模型服务就有泄露风险。这不是说平台不可信，而是“信任”和“合规”在工程上是两回事，你要能承受这个数据流动的后果。

还有一类场景是低延迟要求特别高的本地自动化。比如你希望 OpenClaw 在断网环境下也能执行任务，或者响应时间必须控制在几十毫秒以内，那云端模型可能不一定合适。网络抖动、接口限流、超时重试都会影响整体延迟。所以决策不是“本地好还是云端好”，而是你想在模型效果、资源成本、数据隐私、延迟这四者之间怎么取舍。我个人是把脱敏后的信息交给云端，真正敏感的内容仍然走本地规则处理。

2. 动手前先理清配置链路

2.1 OpenClaw 的模型配置在哪里

OpenClaw 这类开源项目的配置方式通常有两种：命令行启动时用环境变量，或者通过配置文件读取。具体到不同版本，配置文件可能是config.json、config.yaml，也可能是在某个数据目录下的settings文件。我建议你动手前先看一眼 OpenClaw 的文档，或者直接运行openclaw --version并检查项目根目录，确认当前版本支持的配置方式。

打开配置文件后，核心要改的是一个和模型调用相关的区块。不同版本字段名可能不一样，常见的是llm、model或ai。这个区块里一般会有几个基础字段：provider表示供应商类型，base_url表示接口地址，api_key表示密钥，model表示模型 ID，可能还有temperature和max_tokens这类生成参数。你要理解的是，OpenClaw 本身并不绑定任何具体模型厂商，它只负责把消息包装成请求，发到base_url指向的接口，再解析返回结果。所以我们后面要做的，就是把这一整块地址和密钥换成百炼提供的信息。

我见过不少人一上来就照抄网上的配置路径，结果版本不对，文件位置变了，怎么改都不生效。OpenClaw 迭代速度很快，配置文件结构偶尔会调整，所以最稳妥的办法是先备份原有配置，再按当前版本的文档修改。备份这件事我后面还会强调，它真的能在你折腾失败时救命。

2.2 百炼平台要准备哪几样东西

在百炼控制台，你需要准备的核心信息就三样：API Key、模型 ID、接口地址。API Key 是调用凭证，通常以sk-开头，在控制台的“API-KEY 管理”里创建。创建时可以选择主账号或子账号，个人使用选主账号就行。创建成功后要立刻复制保存，因为很多平台只在创建时完整展示一次，关闭页面后就看不到原值了，只能重新生成一个新的 key。

模型 ID 不是模型在页面上显示的中文名，而是接口调用时要填的英文标识。比如某个模型在模型广场可能叫“通义千问-Turbo”，但接口文档里的模型 ID 往往是qwen-turbo。在控制台点进任意模型详情页，一般都能看到“模型 ID”或“endpoint”字段，那才是配置时要填的东西。这一步很多人会搞混，填了中文名后接口一直报 model not found，然后又花不少时间去查，其实只要切换到英文 ID 就通了。

接口地址方面，百炼有多种接入方式。对 OpenClaw 这种兼容 OpenAI 协议的工具，可以直接用 OpenAI 兼容模式的地址，通常是在域名末尾加上/compatible-mode/v1。注意/v1是不可省略的，因为框架会在 base_url 后面继续拼接/chat/completions，如果你只填了裸域名，最终请求地址就会拼错，返回 404。建议把这几个参数单独记下来，后面配置时直接对号入座。

2.3 必记参数速查表

在动手改配置前，我习惯把要用的参数写到一张表里，这样既不会漏，改错了也能快速对照。

提示：如果控制台上已经没有标记为“免费”的模型，或者免费额度信息发生了变化，不要硬填旧的模型 ID。以控制台当前展示为准，模型的价格和免费额度会动态调整。

2.4 先跑通本地基线

接入云端之前，务必先确认 OpenClaw 本身是正常的。最简单的方式是用原来的本地配置启动一次，发一条测试消息，确认它能正常返回。这一步的目的不是让你继续用本地模型，而是为了隔离问题：如果本地都跑不通，那是框架安装或配置本身的问题；如果本地能跑通，换成百炼后报错，那问题大概率出在接口参数、网络或密钥这些环节。

我习惯把这步叫“基线测试”。看起来多花了两分钟，但它能帮你把排查范围缩小一大半。曾经有人直接改了远程配置，发现连不上，于是把 OpenClaw 的配置反复改来改去，折腾了大半天，最后发现是本地服务压根没起来。先确保地基是好的，再去盖上面的楼，这个顺序不会错。

3. 实战：一步步把 OpenClaw 切到百炼

3.1 创建 API Key 的完整步骤

以百炼现在的控制台流程来举例，入口可能随版本调整，但整体逻辑差不多。第一步，登录百炼控制台，确认已开通百炼服务，没开通的话会提示你先开通，个人实名认证后一般马上生效。第二步，在左侧菜单找到“API-KEY 管理”或类似入口，进入后点击“创建 API-KEY”。第三步，给这个 key 起个一眼能认出来的名字，比如openclaw-local，方便之后在多个 key 里找到它。第四步，创建成功后复制sk-开头的完整字符串，保存到你的密码管理工具或本地环境变量里。

我建议你为不同项目分别创建 API Key，不要一个 key 到处复用。这样某个项目的 key 泄露了，你只需要单独删除这一把，其他服务不受影响。我在本地会把 key 存到 shell 环境变量里，比如export DASHSCOPE_API_KEY="sk-xxxx"，而不是直接贴在 OpenClaw 配置文件中。这么做的目的是避免配置文件因为分享、备份、上传仓库而导致密钥泄露。

3.2 修改 OpenClaw 配置文件

把 API Key 准备好后，就可以改 OpenClaw 的配置了。假设你的配置文件是 JSON 格式，大概会找到一个类似下面的结构：

{ "llm": { "provider": "openai", "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key": "sk-xxxxxxxx", "model": "qwen-turbo", "temperature": 0.7, "max_tokens": 2048 } }

如果配置文件是 YAML，写法类似：

llm: provider: openai base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" api_key: "sk-xxxxxxxx" model: "qwen-turbo" temperature: 0.7 max_tokens: 2048

有几个细节容易踩坑，我单独列一下。第一，base_url不要带/chat/completions这个尾巴，OpenClaw 会自己拼接，多带了反而会拼出重复路径。第二，api_key尽量保持纯字符串，不要夹杂空格或换行，特别是在终端里复制时容易带上隐藏字符。第三，model一定用英文模型 ID，不要用中文展示名。第四，如果你的 OpenClaw 版本里没有provider字段，而只有type或engine，先看文档确认它内部是否支持 OpenAI 兼容协议，一般设置为openai或openai-compatible即可。

改完之后先保存，但先不用急着重启，下一步我建议先用 curl 直接测试百炼接口，把问题留在外面解决。

3.3 用环境变量避免密钥泄漏

配置文件里直接写明文 key 虽然也能跑，但不太推荐。OpenClaw 很多版本支持从环境变量读取默认值，你可以先定义好这些变量，再启动服务：

export DASHSCOPE_API_KEY="sk-xxxxxxxx" export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" export OPENAI_MODEL="qwen-turbo"

如果你用的 OpenClaw 版本会默认读取OPENAI_API_KEY，那你甚至可以把DASHSCOPE_API_KEY映射过去再启动。这种方式的好处是，配置文件里不需要出现真实密钥，即使你之后把配置示例发给别人，或者提交到代码仓库，也不会造成密钥泄露。缺点是你需要记得在启动前把环境变量准备好，否则 OpenClaw 会拿到空值，鉴权自然失败。

我自己的习惯是在配置文件里放一个占位符，比如api_key: "env:DASHSCOPE_API_KEY"。不过这个写法不是所有版本都支持，有的框架只是简单地从固定名字的环境变量读取，所以还是要以你当前使用的 OpenClaw 版本文档为准。最稳的做法是：先在命令行里export好变量，再启动 OpenClaw，启动后看日志确认它有没有读到 key。

3.4 用 curl 单独验证百炼接口

改配置之前，先用一条 curl 命令直接打百炼的接口，这是最省时间的验证方式。我通常这样写：

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen-turbo", "messages": [ {"role": "system", "content": "你是一个测试助手。"}, {"role": "user", "content": "请只回复两个字：正常"} ] }'

如果返回的 JSON 里有choices[0].message.content，那就说明 key、模型 ID、接口地址三层都通了。如果返回 401、404 或 429，可以直接根据错误码去查，不用再跑到 OpenClaw 那边盲猜。这一步能分流掉至少一半的配置问题。我有一次就是因为 base_url 写成了不带/v1的地址，curl 一打立刻看到 404，改完马上就好。

在 curl 测试通过之前，我不建议重启 OpenClaw，因为框架日志里的报错信息往往比 curl 的返回值更抽象，肉眼定位更费劲。先在外面把接口打通，再把 OpenClaw 接上去，问题范围就清晰了。

3.5 重启 OpenClaw 并跑通对话

curl 通了之后，重启 OpenClaw，让它重新加载配置。启动日志里如果能看到模型初始化成功、连接正常之类的内容，说明出站请求已经指向百炼。然后直接发一条消息，比如“你好，简单介绍下你自己”。如果一切正常，OpenClaw 会先把本地的系统提示词、工具描述等上下文组装成消息，发给百炼接口，百炼返回内容后，OpenClaw 再把结果展示给你。

这时候要留意两件事。第一是响应耗时。云端大模型通常需要一点时间生成，几百毫秒到几秒都算正常；如果你觉得明显卡顿，可能是模型选择过大，也可能是本地网络带宽不稳定。第二是日志里有没有工具调用记录。OpenClaw 这类智能体框架，很多时候会先规划调哪个工具，再生成最终回答，所以日志里出现“调用工具 xxx”是正常的，不代表出错。只要最终能回答你的问题，链路就算通了。

如果发现回复内容有截断，先检查max_tokens是不是设得太小。长回答很容易超出生成上限，OpenClaw 拿到截断内容后可能还会继续处理，但结果质量会明显下降。遇到这种情况，把max_tokens调大，或者在端到端链路跑通后再做上下文裁剪优化。

3.6 工具调用模式怎么配

OpenClaw 相比普通问答机器人的优势在于它能调用工具，比如搜索、读写文件、执行脚本。这需要模型支持 function calling / tool calling。百炼的 qwen 系列模型通常支持 OpenAI 格式的工具调用协议，所以在 OpenClaw 里开启插件或工具后，框架会把工具定义传给模型，模型在合适的时候返回一个工具调用请求，OpenClaw 执行完再把结果回传给模型，生成最终回答。

这个链路在本地小模型上通常不稳定，因为小模型很容易在工具选择和参数填充上出错，多轮调用后甚至会忘记上下文。切到百炼之后，我实测下来稳定性明显提升。要注意的是，免费模型不一定开放工具调用能力，或者有频率限制。如果你发现日志里出现了模型返回的 tool call 请求，但 OpenClaw 没有继续处理，可以先关掉部分插件，只保留纯对话功能，确认模型本身没问题，再逐个开启工具项来排查。

4. 常见问题与排错实录

4.1 高频报错速查表

我把这次配置过程中遇到的，以及朋友们经常问到的错误码整理成了一张速查表。遇到问题先对照这张表，大部分情况都能快速定位。

4.2 重点说说 401 和 429 这两个高频问题

401 是我遇到最多的错误。第一次是因为复制 key 时漏掉了前面的sk-，第二次是环境变量没生效，OpenClaw 读到的其实是空字符串。排查方法很简单：在终端里执行echo $DASHSCOPE_API_KEY，看输出是不是完整 key。如果为空，说明你export的配置没被当前 shell 加载，需要source一下配置文件，或者重新打开终端。

429 则是免费额度最容易触发的问题。免费额度通常不是无限量，而是按每分钟请求数或每分钟 token 数来限制。你如果写了一个循环频繁调用模型，一小会儿就会撞上限流。遇到 429 不要急着反复重试，先等十几秒，再把 OpenClaw 的请求频率降下来。另一个容易被忽略的点是：如果你一个 key 在好几个项目里共用，限流概率会更高，这也是我前面强调单独建 key 的原因。

4.3 免费额度的一些坑

“免费”不等于“随便用”。有些平台的免费额度是给你一笔总 token 数，用完就要换付费模型；有些是按月刷新；有些只对特定模型有效。我建议配置完成后定期去控制台的“额度/用量”页面看一眼，对自己还剩多少量心里有数。如果你调用的模型不在免费名单里，即使 key 是有效的，接口也可能返回欠费或权限相关错误。这时不要执着于原来那个模型，换一个真正有免费额度的模型 ID 重新配置就行。

还有一个容易忽略的点是上下文长度。OpenClaw 会累积对话历史，如果长时间运行，请求体里的 message 越来越多，很容易超过模型上下文窗口限制。云端接口可能直接报错，或者截断早期内容。解决办法是在 OpenClaw 侧开启上下文裁剪或摘要，控制每次发送的消息长度。特别是跑定时任务时，一定要设置会话清理策略，否则跑着跑着突然就报错了。

4.4 配置过程中的几条实操心得

第一，改配置前一定要备份原文件。OpenClaw 的配置看起来简单，但里面可能藏着你调好的工具白名单、审核规则、模型参数。我因为图省事直接原地替换，后来想切回本地模型，发现原配置已经被覆盖了，只能凭印象重写。现在任何修改之前我都会先cp一份带日期后缀的备份。

第二，把日志级别调到 debug。OpenClaw 启动时通常支持 debug 参数，开启后能看到每次出站请求的完整 URL、响应码和耗时。这比看界面上的“连接失败”有用得多。看到请求实际打到了哪个 URL，你就能立刻判断是不是 base_url 写错了；看到响应码，你就能知道是 key 的问题还是模型 ID 的问题。

第三，不要迷信“免费就是最好的”。如果你之后要跑比较重的任务，或者对响应速度有要求，可以看看付费模型的按量价格。有时候付费模型单次调用成本很低，但省下来的调试时间和稳定性是实打实的。免费额度适合跑通流程和日常轻量使用，不是所有场景都必须用它。

第四，多实例部署时记得同步环境变量。我在一台测试机上配好后，想复制到另一台机器，结果只复制了配置文件，忘了带环境变量，那边一直报鉴权失败。配置文件、环境变量、启动脚本这三样要一起迁移，缺一不可。

5. 接完之后，我还在琢磨的事

把 OpenClaw 接到百炼之后，我的本地开发机终于不用再被模型占着不放了。现在我可以同时开着编辑器、跑几个定时脚本，OpenClaw 依然响应得很快，因为推理负载都在云端。对我个人来说，这种“本地调度 + 云端推理”的组合，既保留了智能体框架的灵活性，又用更低成本获得了更强的模型能力，确实适合个人开发者和中小项目。

不过我也要提醒自己和你，上面这套配置只是“接通用起来”的第一步。接下来你可以继续折腾的还有很多：比如给 OpenClaw 接上自己的知识库，用百炼的 embedding 模型做向量化；比如调整系统提示词，让它在工具调用和多轮对话中更贴合你的业务；再比如做一个简单的 web 控制台，把 OpenClaw 的日志和会话展示出来。配置本身不难，难的是搞清楚框架、模型、工具这三层是怎么协作的。我在实际调试中的体会是：先让链路跑通，再逐步加复杂度，遇到问题就拆成“框架层”和“模型层”分别验证，基本不会卡死。希望这篇实战指南能帮你少踩几个坑，把更多时间花在真正有意思的事情上。