1. 为什么要在本地跑 OpenClaw 对接阿里云百炼

OpenClaw 是一个开源的 AI 自动化助理框架，你可以把它理解成一个「能自己动手干活」的机器人底座：它本身不带大模型，而是通过配置把外部模型 API 接进来，再挂到钉钉、Web 面板这类入口上，让 AI 在群聊里自动回消息、跑任务、生成内容。2026 年 4 月这个时间点，OpenClaw 的本地集成链路已经比较成熟，尤其是和阿里云百炼的对接，官方兼容模式接口稳定，配置项也不复杂。

这篇教程面向的是第一次接触 OpenClaw 的开发者，目标很明确：在本地机器上，用大约 8 分钟把 OpenClaw 跑起来，把阿里云百炼的 API Key 写进配置，最后在钉钉侧发一条消息验证整条链路通不通。全程不需要你懂 Node.js 底层，也不需要买服务器，一台能联网的开发机就够。我会把每一步的命令、配置文件片段、验证动作都写清楚，你复制粘贴就能跟做。

先说清楚几个概念，避免后面看配置时懵。OpenClaw 的模型调用走的是「provider」抽象层，每个 provider 有自己的 baseUrl、apiKey 和模型列表。阿里云百炼提供的是 OpenAI 兼容接口，所以 baseUrl 填https://dashscope.aliyuncs.com/compatible-mode/v1，模型 ID 用qwen3-max-2026这类百炼侧的标识。钉钉侧则是通过开放平台的机器人能力接入，OpenClaw 内置了钉钉通道，你只要把 Client ID 和 Client Secret 填进去，再开一个触发前缀，机器人就能在群里响应指令。

很多人卡住不是因为技术难，而是几个细节没对齐：API Key 复制时带了空格、端口没放行、钉钉权限没申请全、配置改完没重启服务。这篇教程会把这些坑提前标出来，你按顺序走基本不会翻车。下面从环境准备开始，一步步来。

2. 环境准备与 TaoToken 前置配置

在正式写 OpenClaw 配置之前，先把两件事准备好：本地运行环境和模型 API 的接入凭证。环境这块，OpenClaw 依赖 Node.js 22 及以上版本，官方推荐用 nvm 管理版本，避免和系统自带的旧 Node 冲突。如果你机器上已经有 Node 22，可以跳过安装，直接验证版本。

# 检查 Node 版本，必须 >= 22 node -v # 如果没有或版本过低，用 nvm 安装 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22

Node 就绪后，全局安装 OpenClaw CLI。这里建议同时把 npm 镜像切到国内源，依赖下载会快很多，尤其是后面装技能包的时候。

npm config set registry https://registry.npmmirror.com/ npm install -g openclaw-cli openclaw --version

接下来是模型 API 凭证。阿里云百炼的 API Key 在百炼控制台的「密钥管理」里创建，格式是sk-开头的一串字符。创建时注意两点：一是复制后检查首尾有没有多余空格或换行，二是这个 Key 只显示一次，创建完立刻保存到安全的地方。如果你还没开通百炼，先去控制台完成实名认证，否则创建 Key 的入口是灰的。

除了百炼直连，如果你希望统一管理多个模型的接入凭证，可以用 TaoToken 做一层聚合。它的 API 地址是https://taotoken.net/api，在控制台里可以创建和管理 Key，然后 OpenClaw 侧只需要填 TaoToken 的 baseUrl 和 Key，就能同时调用多个后端模型。对于需要频繁切换模型做对比的场景，这种方式省事很多。具体操作是：登录 TaoToken 控制台，在 API Keys 页面创建一个新 Key，复制保存；然后在 OpenClaw 的 provider 配置里把 baseUrl 指向 TaoToken 的 API 地址，apiKey 填刚创建的 Key，模型 ID 按 TaoToken 文档里支持的标识填。

这里要提醒一句：不管用百炼直连还是 TaoToken 聚合，Key 都不要硬编码在会提交到 Git 的文件里。OpenClaw 的配置文件默认在~/.openclaw/openclaw.json，这个路径不在项目仓库内，相对安全，但如果你要分享配置，记得把 Key 替换成占位符。

环境准备好之后，先别急着写完整配置，用一条最小命令验证 OpenClaw CLI 能正常跑：

openclaw doctor

这个命令会检查 Node 版本、配置文件是否存在、端口占用等基础项。如果输出里有红色报错，先按提示修掉，再往下走。很多人跳过这步，后面配置写完发现服务起不来，回头排查反而更费时间。

3. 可复制的 OpenClaw 配置文件片段

OpenClaw 的核心配置都集中在~/.openclaw/openclaw.json。这个文件是 JSON 格式，改的时候注意逗号和大括号配对，少一个符号服务就起不来。下面给出一份完整的、可以直接复制修改的配置片段，包含百炼 provider、默认模型、钉钉通道三部分。

先创建配置目录和文件：

mkdir -p ~/.openclaw touch ~/.openclaw/openclaw.json

然后用编辑器打开，写入以下内容。注意把sk-你的百炼APIKey和钉钉的两个凭证替换成你自己的：

{ "models": { "default": "bailian/qwen3-max-2026", "providers": { "bailian": { "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-你的百炼APIKey", "models": [ { "id": "qwen3-max-2026", "maxTokens": 65536 }, { "id": "qwen3.5-plus", "maxTokens": 8192 } ] } } }, "channels": { "dingtalk": { "enabled": true, "clientId": "你的钉钉ClientID", "clientSecret": "你的钉钉ClientSecret", "prefix": "!" } }, "gateway": { "port": 18789, "host": "0.0.0.0" } }

这份配置里几个关键点解释一下。models.default指定默认走哪个模型，格式是provider名/模型ID，这里指向百炼的 qwen3-max-2026。providers.bailian.baseUrl是百炼的 OpenAI 兼容端点，不要写成 dashscope 的原生端点，否则 OpenClaw 的调用格式会对不上。maxTokens按模型实际支持的上限填，qwen3-max 支持到 65536，qwen3.5-plus 是 8192，填大了请求会被拒。

钉钉部分，prefix是群聊里触发机器人的前缀，默认!，你可以改成/或$，但要注意别和钉钉本身的指令冲突。gateway.port是 Web 面板和 API 的监听端口，默认 18789，如果你本地这个端口被占用，改成 18790 之类也行，但后面访问面板的地址要跟着改。

如果你用 TaoToken 聚合，provider 段改成这样：

"providers": { "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKey": "你的TaoToken Key", "models": [ { "id": "qwen3-max-2026", "maxTokens": 65536 } ] } }

同时把models.default改成taotoken/qwen3-max-2026。这样 OpenClaw 请求先到 TaoToken，再由它转发到对应模型，Key 的管理和轮换都在 TaoToken 控制台完成，本地配置不用频繁改。

配置写完后，先别启动服务，用一条命令校验 JSON 语法：

python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null && echo "JSON OK"

输出JSON OK说明格式没问题。如果报错，按提示的行号去检查，通常是漏了逗号或者多了一个括号。这一步花十秒，能省掉后面看日志排查的几分钟。

4. 启动服务并验证请求链路

配置校验通过后，就可以启动 OpenClaw 网关服务了。启动命令带--daemon参数让它后台运行，这样你关掉终端服务也不会停。

openclaw gateway start --daemon

启动后立刻查状态：

openclaw gateway status

输出里看到active (running)就说明服务起来了。如果显示failed或inactive，先看日志：

openclaw logs -f

日志里最常见的报错是EADDRINUSE，意思是 18789 端口被别的进程占了。用lsof -i:18789找到占用进程，要么杀掉，要么改配置里的端口号再重启。

服务正常后，先验证模型调用通不通，这一步不依赖钉钉，纯粹测 OpenClaw 到百炼的链路：

openclaw model test

这个命令会发一条测试请求给默认模型，返回内容里如果有正常的文本回复，说明 API Key、baseUrl、模型 ID 三者都对上了。如果返回 401，检查 Key 有没有复制错；如果返回 404，检查模型 ID 是不是百炼侧真实存在的；如果超时，检查本地网络能不能访问 dashscope.aliyuncs.com。

模型通了之后，生成一个管理员 Token，用于登录 Web 面板：

openclaw token generate

把输出的 Token 复制下来，浏览器访问http://127.0.0.1:18789?token=你的Token，能看到对话界面就说明网关和面板都正常。在面板里发一句「帮我总结 OpenClaw 的配置步骤」，如果模型正常回复，整条本地链路就算跑通了。

最后验证钉钉侧。在钉钉群里添加你创建的机器人，发送!你好，如果机器人回复了内容，说明钉钉通道也通了。这里有个细节：钉钉机器人的消息回调需要你的本地服务能被钉钉服务器访问到。如果你是在本地机器跑，没有公网 IP，钉钉的回调会失败。解决办法有两个：一是用内网穿透工具把 18789 端口暴露出去（注意合规使用），二是先把 OpenClaw 部署到有公网 IP 的服务器上再配钉钉。本地纯验证模型链路的话，钉钉这步可以暂时跳过，等有公网环境再补。

验证顺序建议按「模型测试 → Web 面板 → 钉钉」来，每步确认通过再走下一步，出问题容易定位。

5. 常见报错排查对照

这一节把新手最常撞到的几个报错列出来，对照着改基本能解决。

401 Unauthorized：模型测试返回 401，九成是 API Key 问题。先检查 Key 有没有复制完整，首尾有没有空格。百炼的 Key 是sk-开头，如果你复制时漏了后面几位，或者把创建时的显示内容截断了，都会 401。另一个可能是 Key 被禁用或欠费，去百炼控制台确认状态。

local proxy failed / connection refused：这个报错说明 OpenClaw 连不上 baseUrl。先确认baseUrl写的是https://dashscope.aliyuncs.com/compatible-mode/v1，不要多写或少写路径。然后用curl直接测一下：

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{"model":"qwen3-max-2026","messages":[{"role":"user","content":"hi"}]}'

如果 curl 也失败，说明是网络或 Key 的问题，和 OpenClaw 无关；如果 curl 成功但 OpenClaw 失败，检查配置文件里的 baseUrl 有没有拼写错误。

reading choices 报错：这个通常出现在模型返回格式和 OpenClaw 预期不一致时。百炼的兼容模式返回结构是标准的 OpenAI 格式，choices数组里带message.content。如果你用的是非兼容端点，返回结构不同，OpenClaw 解析就会报这个错。确认 baseUrl 带/compatible-mode/v1后缀。

OAuth 相关报错：钉钉通道如果报 OAuth 或 token 获取失败，检查 Client ID 和 Client Secret 是否配对，以及钉钉应用是否发布了版本。钉钉的凭证在「凭证与基础信息」页面，Client Secret 只显示一次，如果忘了只能重置。另外确认应用权限里申请了qyapi_robot_sendmsg，没有这个权限机器人发不出消息。

服务启动后立即退出：看日志如果没有任何报错就退出，检查配置文件路径对不对。OpenClaw 默认读~/.openclaw/openclaw.json，如果你把文件放在了别处，启动时要加--config参数指定路径。另外确认 Node 版本是 22 以上，低版本会有兼容问题。

钉钉机器人不回复：先确认服务在跑、钉钉通道 enabled 为 true、prefix 和发送的前缀一致。然后在日志里看有没有收到钉钉的回调请求。如果日志里没有回调记录，说明钉钉服务器没访问到你的服务，检查公网可达性和端口放行。

排查的核心思路是分层：先确认模型链路（curl 直测），再确认 OpenClaw 服务（status + logs），最后确认钉钉回调（日志有无请求）。每层单独验证，不要混在一起猜。

6. 后续接入与长期使用建议

本地跑通之后，如果你打算长期用 OpenClaw 做自动化，有几个方向可以继续。一是把服务从本地迁到有公网 IP 的环境，这样钉钉回调稳定，也能 7×24 运行。迁移时只需要把~/.openclaw/openclaw.json复制过去，改一下 gateway 的 host 和端口，重新启动即可。二是把常用技能装上，OpenClaw 的技能生态通过 clawhub 管理，装几个基础技能能明显扩展能力边界：

npm install -g clawhub-cli clawhub install search clawhub install document-parser clawhub install summarize openclaw gateway restart

装完重启服务，技能就生效了。search让模型能联网查资料，document-parser能读 PDF/Word，summarize做长文提炼。这几个都是低风险、高频用的，建议先装。

模型侧，如果你用量大，可以关注百炼的 Coding Plan 这类按次计费的套餐，比纯按 token 计费在固定任务量下更划算。配置方式和普通 API Key 一样，只是 baseUrl 和模型 ID 换成 Coding Plan 对应的值。如果你需要同时接多个模型做对比，用 TaoToken 聚合会更方便，Key 和模型列表都在一个控制台管理，OpenClaw 侧只配一个 provider 就行。

最后说一个实际使用中的小技巧：OpenClaw 的日志默认会滚动，长时间运行后日志文件可能占不少空间。可以在配置里加日志级别和轮转策略，或者定期用openclaw logs --clear清理。另外，配置文件改完一定要openclaw gateway restart，很多人改完不重启，以为没生效，其实是服务还在用旧配置。

整条链路跑通后，你手里就有了一个能接钉钉、能调百炼模型的本地 AI 助理底座。后面要加新通道、换模型、装技能，都是在这份配置上做增量修改，不用推倒重来。先把最小可用链路跑稳，再逐步扩展，比一上来就堆一堆功能要靠谱得多。