1. OpenClaw 接入阿里云百炼 API-Key 的真实场景与坑点OpenClaw 是一个可自托管的 AI Agent 运行框架支持多模型提供商、技能插件和工具调用。阿里云百炼是阿里云推出的大模型服务平台提供通义千问系列模型的 API 调用能力。把这两者接起来本质上就是让 OpenClaw 在需要推理时把请求发到百炼的 OpenAI 兼容端点上拿回结果继续跑 Agent 流程。适合谁看如果你已经在本地或服务器上部署了 OpenClaw想用百炼的 qwen-max、qwen-plus 这类模型替代默认模型或者你手上正好有百炼的 API-Key 但不知道怎么填进 OpenClaw 的配置文件这篇就是为你写的。我试过在两种部署形态下接百炼一种是 Docker 部署、配置文件走/opt/openclaw/config/config.yaml另一种是源码部署、走项目根目录的openclaw.json。两条路径的字段名和嵌套结构不一样混用会直接导致启动后模型不生效日志里只报一句provider not found非常难查。核心难点集中在三处第一百炼有两种鉴权方式——AccessKey ID/Secret 签名模式和 OpenAI 兼容的sk-开头 API-Key 模式OpenClaw 不同版本默认走哪套不一样第二config.yaml和openclaw.json的字段层级不同YAML 用llm_providersJSON 用models.provider第三改完配置后服务不重启或重启不彻底旧进程还在用内存里的老配置。下面按「拿 Key → 改文件 → 验证 → 排错」的顺序走一遍每个片段都可以直接复制。2. TaoToken 前置准备统一 Base URL 与 Key 管理在动 OpenClaw 配置文件之前先把模型侧的接入信息准备好。这里有两种思路一种是直连百炼官方端点另一种是通过 TaoToken 这类聚合网关统一管理 Key 和 Base URL。后者在你有多个模型提供商、或者想让 OpenClaw 的配置在不同环境间复用时更省事。TaoToken 的 API 地址是https://taotoken.net/api它兼容 OpenAI 的接口规范所以 OpenClaw 里凡是填baseURL的地方都可以指向它。你需要先在控制台创建一个 API Key然后把它当作apiKey填进配置。具体操作路径打开https://taotoken.net/console登录后进入 API Keys 页面点创建复制生成的 Key。这个 Key 就是后面配置文件里apiKey字段的值。如果你要用百炼官方的 OpenAI 兼容模式那baseURL填https://dashscope.aliyuncs.com/compatible-mode/v1apiKey填百炼控制台生成的sk-开头的 Key。模型 ID 这块要注意百炼的模型标识符是qwen-max、qwen-plus、qwen-turbo这种小写带连字符的格式不是Qwen-Max。OpenClaw 配置里写错大小写请求会返回Model not available。如果你打算长期跑编码类 Agent 任务可以了解下 Coding Plan 的额度方案入口在https://taotoken.net/coding-plan。不过这篇的重点是配置链路额度的事先放一边。准备好这三样东西Base URL、API Key、Model ID。后面两个配置文件里反复用到。3. 可复制配置config.yaml 与 openclaw.json 双文件实战这一节是全文的核心。OpenClaw 的配置文件位置取决于你的部署方式先用一条命令确认它到底加载的是哪个文件# 查看 OpenClaw 进程启动时指定的配置文件 ps aux | grep openclaw | grep -oP (?--config\s)\S # 或者直接看启动日志 tail -n 50 /var/log/openclaw/app.log | grep -i config如果输出是/opt/openclaw/config/config.yaml那就改 YAML如果是项目根目录的openclaw.json那就改 JSON。两个都改也行但要以实际加载的为准。3.1 config.yaml 版本Docker / 服务化部署YAML 版本的结构是顶层llm_providers下挂各个提供商然后在models里指定默认模型在skills里指定技能用哪个提供商。llm_providers: aliyun_bailian: enabled: true access_key_id: ${ALIYUN_ACCESS_KEY_ID} access_key_secret: ${ALIYUN_ACCESS_KEY_SECRET} region_id: cn-hangzhou endpoint: dashscope.aliyuncs.com api_version: 2023-06-01-preview models: default: qwen-max chat: qwen-max embedding: text-embedding-v2 skills: web_search: enabled: true llm_provider: aliyun_bailian model: qwen-max注意access_key_id和access_key_secret这里用了环境变量引用。你需要在~/.bashrc或 systemd 的EnvironmentFile里设置export ALIYUN_ACCESS_KEY_IDLTAI5txxxxxxxxxxxxxxx export ALIYUN_ACCESS_KEY_SECRETK4Jhxxxxxxxxxxxxxxxxxxxxxxxx改完执行source ~/.bashrc然后重启 OpenClaw 服务。如果你用的是 systemdsudo systemctl restart openclaw sudo systemctl status openclaw3.2 openclaw.json 版本源码 / npm 部署JSON 版本走的是 OpenAI 兼容接口模式结构更扁平。关键字段是models.provider、models.openai.apiKey、models.openai.baseURL以及agents.defaults.model.primary。{ models: { provider: openai, openai: { apiKey: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1 } }, agents: { defaults: { model: { primary: qwen-max } } } }如果你走 TaoToken 网关把baseURL换成https://taotoken.net/apiapiKey换成 TaoToken 控制台生成的 Key模型 ID 保持qwen-max不变。这样 OpenClaw 的请求会先到网关再由网关转发到百炼。这里有个容易踩的坑provider字段必须和openai这个键名对应。有些版本的 OpenClaw 要求provider写openai-compatible写错会报unknown provider。保险起见先看你的 OpenClaw 版本号openclaw --version如果版本在 0.8.x 以上openai是标准写法0.7.x 及以下可能需要openai-compatible。3.3 环境变量注入推荐做法不管用哪个文件密钥都不应该硬编码。JSON 版本虽然不支持${}语法但可以在启动脚本里用envsubst做替换envsubst openclaw.json.template openclaw.json模板文件里写apiKey: ${BAILIAN_API_KEY}启动前替换。这样openclaw.json本身可以加进.gitignore不会泄露。4. 验证请求启动后确认模型连通性配置改完、服务重启后别急着在 Web 界面发消息。先用命令行确认底层连通性这样出问题能快速定位是网络层、鉴权层还是模型层。第一步检查服务健康状态curl -s http://localhost:18789/api/health | jq .llm_status预期返回类似{ provider: aliyun_bailian, status: connected, model: qwen-max, latency_ms: 320 }如果status是disconnected或error说明配置没生效或鉴权失败跳到第 5 节排错。第二步直接发一条测试消息。OpenClaw 通常提供一个/api/chat端点curl -s -X POST http://localhost:18789/api/chat \ -H Content-Type: application/json \ -d {message: 用一句话说明什么是API, model: qwen-max} | jq .reply预期返回一段中文回复类似API是应用程序之间进行数据交互的接口规范。如果返回{error: Authentication failed}说明 Key 有问题如果返回{error: Model not available}说明模型 ID 写错了。第三步如果你走的是 OpenAI 兼容模式可以直接用curl打百炼端点绕过 OpenClaw 验证 Key 本身是否有效curl -s https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H Authorization: Bearer sk-xxxxxxxxxxxxxxxx \ -H Content-Type: application/json \ -d {model: qwen-max, messages: [{role: user, content: hi}]} | jq .choices[0].message.content这条命令能通说明 Key 和端点没问题问题在 OpenClaw 配置层这条命令不通说明 Key 本身或网络有问题。5. 本篇常见错排查401、local proxy failed、reading choices这一节对照真实报错逐个拆解。报错一401 Authentication failed / Invalid API Key最常见的原因是 Key 复制时带了空格或换行。百炼控制台复制出来的 Key 有时末尾会多一个换行符粘进 YAML 后变成apiKey: sk-xxx\n解析时把\n当成 Key 的一部分。解决办法是用cat -A检查配置文件cat -A /opt/openclaw/config/config.yaml | grep apiKey如果行尾出现$之外的字符说明有隐藏字符。重新粘贴或者用sed清理sed -i s/[[:space:]]*$// /opt/openclaw/config/config.yaml另一个原因是 Key 对应的模型服务没开通。登录百炼控制台进入「模型服务」页面确认qwen-max的状态是「已开通」。没开通的话点一下开通通常即时生效。报错二local proxy failed / Connection timeout这个报错说明 OpenClaw 所在服务器无法访问dashscope.aliyuncs.com的 443 端口。先测网络curl -v https://dashscope.aliyuncs.com/compatible-mode/v1/models如果卡在Trying xxx.xxx.xxx.xxx...不动说明出站被拦。检查安全组出站规则是否允许 443以及服务器是否有 iptables 限制sudo iptables -L -n | grep 443如果服务器在内网环境需要配置 HTTP 代理。但注意这里说的代理是企业内网的正向代理不是那种违规工具。在 OpenClaw 的启动脚本里设置export HTTPS_PROXYhttp://your-corporate-proxy:8080报错三reading choices: unexpected end of JSON input这个报错通常出现在 OpenAI 兼容模式下原因是baseURL写错了。比如写成了https://dashscope.aliyuncs.com/compatible-mode少了/v1请求打到了错误的路由返回了 HTML 而不是 JSON解析时就报unexpected end of JSON。正确写法是https://dashscope.aliyuncs.com/compatible-mode/v1如果你走 TaoToken就是https://taotoken.net/api注意末尾不要多加/有些版本的 OpenClaw 拼接路径时会产生//chat/completions导致 404。报错四OAuth token expired / refresh failed这个报错和 API-Key 模式无关通常出现在你用 OAuth 方式登录了某个提供商但 token 过期了。如果你在openclaw.json里同时配了 OAuth 和 API-KeyOpenClaw 可能优先走 OAuth。解决办法是删掉 OAuth 相关的配置块只保留apiKey字段。检查openclaw.json里有没有oauth或auth开头的键有就删掉。报错五配置文件修改未生效改完文件、重启服务但行为没变。先确认服务真的重启了sudo systemctl status openclaw | grep Active如果显示Active: active (running) since ...的时间还是旧的说明重启失败。用sudo systemctl restart openclaw强制重启然后看日志tail -f /var/log/openclaw/app.log日志里会打印实际加载的配置文件路径。如果路径和你改的不一样说明你改错了文件。用第 3 节开头的ps aux命令确认实际加载路径。6. 语义一致 CTA把配置落到可复用的接入流程配置跑通之后建议把 Base URL、API Key、Model ID 这三件套固化到一个环境变量文件里比如~/.openclaw/envexport OPENCLAW_BASE_URLhttps://taotoken.net/api export OPENCLAW_API_KEYsk-xxxxxxxxxxxxxxxx export OPENCLAW_MODEL_IDqwen-max然后在启动脚本里source ~/.openclaw/env配置文件里用${OPENCLAW_BASE_URL}引用。这样换环境时只改一个文件不用动config.yaml或openclaw.json。如果你需要经常切换不同模型做对比测试可以在 TaoToken 控制台的模型对话页面直接验证模型返回是否符合预期入口是https://taotoken.net/model-chat。确认模型行为正常后再把对应的 Model ID 写进 OpenClaw 配置。API Key 的管理和轮换在https://taotoken.net/api-keys建议为 OpenClaw 单独创建一个 Key权限只给需要的模型不要用主账号的 Key。接入文档在https://taotoken.net/doc里面有各语言 SDK 的调用示例对照着调 OpenClaw 的请求格式会更快。最后一步把改好的配置文件权限收紧chmod 600 /opt/openclaw/config/config.yaml chmod 600 openclaw.json确保只有运行 OpenClaw 的用户能读。如果配置文件在 Git 仓库里把文件名加进.gitignore用.template后缀的版本做版本控制。
