1. 先搞清楚 OpenClaw 到底在跑什么OpenClaw 是一个把自然语言指令转成实际动作的智能体框架它自己不带推理能力必须外接一个大模型 API 才能理解你说的话、拆解任务、调用技能。你可以把它理解成一个「遥控器」——遥控器本身不会播节目得配上电视大模型才有画面。2026 年这个版本对 Node.js 版本、端口策略、配置结构都做了调整很多老教程直接照抄会踩坑。它适合谁三类人一是想在自己服务器上挂一个 7×24 小时在线的助手随时通过 Web 面板或接口调用二是对数据隐私敏感、希望所有对话和技能数据都留在本地的开发者三是想拿它对接千问或 Coding Plan 这类模型服务做自动化任务编排的团队。不管哪类核心链路都一样装运行时 → 初始化 → 配模型 API → 验证请求通不通。我实测下来最容易卡住的不是安装本身而是「模型配好了但请求发不出去」——报错五花八门401、local proxy failed、reading choices 轮番上阵。这篇就按「阿里云 本地三系统」两条线把每一步命令、每一段配置、每一个验证动作都摊开写你照着敲就能复现。先说清楚整体结构阿里云适合长期挂机、要公网访问的场景本地适合零成本、重隐私的场景。两条线共用同一套模型配置逻辑区别只在安装和端口放通。下面从环境准备开始一步步来。环境要求先对齐阿里云推荐 2vCPU 2GiB 内存起步带宽 ≥3Mbps系统盘 ≥40GB ESSD本地 CPU ≥2 核内存 ≥2GB推荐 4GBNode.js 必须 22.x 以上。系统层面 Windows 1164 位 22H2、macOS 12、Ubuntu 20.04/Debian 11 都能跑。Node 版本不对是最常见的启动失败原因先node -v确认别跳过。2. TaoToken 前置把模型入口和 Key 准备好在配 OpenClaw 之前得先有一个能用的模型 API 入口。这里我用 TaoToken 作为统一接入层它把千问、Coding Plan 等模型服务收敛成一套兼容 OpenAI 格式的接口OpenClaw 侧只需要填 Base URL Key Model ID 三件套就能通。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 。为什么建议先过一层统一入口因为 OpenClaw 的 provider 配置是按「provider 名 baseurl apikey model」组织的如果你直接对接多个原生平台每个平台的鉴权头、路径、模型命名都不一样切换和排障都麻烦。统一入口之后你换模型只改 Model IDBase URL 和 Key 不动验证逻辑也一致。拿 Key 的路径进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建复制出来形如sk-开头的字符串。这个 Key 就是后面配置里providers.xxx.apikey的值。注意别把它贴到公开仓库本地配置文件权限设成 600。模型侧有两个方向一是走模型对话验证连通性入口 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 二是长期编码 / Agent 场景用 Coding Plan入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Coding Plan 适合高频调用、需要稳定额度的场景普通对话验证用模型对话页就够。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面列了各模型的 Model ID 命名规则配 OpenClaw 时直接对照填。如果你用 Claude Code 类工具Anthropic 兼容入口是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 对应的 Key 管理页ClaudeCodeAnthropic 的 deep link 是 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 。前置准备清单一个可用的 API Key、确认好的 Base URLhttps://taotoken.net/api 、一个 Model ID比如千问系列或 Coding Plan 对应模型。这三样齐了后面 OpenClaw 的 provider 配置就是填空题。3. 可复制配置阿里云与本地三系统落地这一节是全文最核心的部分所有片段都能直接复制。先讲阿里云再讲本地三系统最后给统一的模型配置片段。阿里云侧买实例时选「应用镜像」里的 OpenClaw 镜像预装了 Node.js 22省去手动装运行时。地域优先选免备案区域国内业务选华东 1杭州。实例规格 2vCPU 2GiB 40GiB ESSD 起步。连上服务器后先更新依赖并拿到随机端口# 更新系统依赖 yum update -y --disablerepo* --enablerepoaliyunos,epel # 获取 OpenClaw 随机端口2026 版本默认随机不是固定 18789 openclaw config get gateway.port # 放行随机端口把 PORT 换成上一步拿到的数字 firewall-cmd --add-portPORT/tcp --permanent firewall-cmd --add-port80/tcp --permanent firewall-cmd --add-port443/tcp --permanent firewall-cmd --reload # 验证放行结果 firewall-cmd --list-ports端口这步是阿里云部署最大的坑2026 版本端口是随机的老教程写死 18789 会导致 Web 面板打不开。一定要先config get gateway.port拿到真实端口再放行。接着初始化并启动cd /opt/openclaw npm config set registry https://registry.npmmirror.com/ openclaw onboard --non-interactive --accept-risk --enable-skill-market openclaw gateway start --daemon openclaw token generate --admin --allow-ip 0.0.0.0/0 openclaw dashboard url最后一行会输出 WebUI 访问地址复制到浏览器打开用生成的 admin Token 登录。本地三系统。macOS/Linux 用官方国内镜像脚本curl -fsSL https://open-claw.org.cn/install-cn.sh | bash openclaw --version openclaw onboard --non-interactive --accept-risk --enable-skill-market openclaw gateway start --daemon openclaw token generate --admin openclaw dashboard urlWindows 11 用管理员 PowerShellSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser choco install git -y iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex装完继续执行和 macOS 相同的 onboard / start / token / dashboard 四条命令。模型配置片段这是 §3 必须给的可复制 JSON。OpenClaw 的配置文件在~/.openclaw/openclaw.json你可以直接编辑也可以用openclaw config set逐项写。下面是走 TaoToken 统一入口的完整 JSON 结构{ agents: { defaults: { model: { primary: taotoken/qwen3.5-plus } } }, providers: { taotoken: { baseurl: https://taotoken.net/api, apikey: sk-你的TaoToken-Key, temperature: 0.7, maxTokens: 2048 } } }如果你要分别对接千问原生和 Coding Plan用命令行写# 千问方向 openclaw config set agents.defaults.model.primary dashscope-api/qwen3.5-plus openclaw config set providers.dashscope-api.apikey sk-你的千问Key openclaw config set providers.dashscope-api.baseurl https://dashscope.aliyuncs.com/compatible-mode/v1 openclaw config set providers.dashscope-api.temperature 0.7 openclaw config set providers.dashscope-api.maxTokens 2048 # Coding Plan 方向 openclaw config set agents.defaults.model.primary coding-plan/qwen3.5-plus openclaw config set providers.coding-plan.apikey sk-sp-你的CodingPlanKey openclaw config set providers.coding-plan.baseurl https://coding.dashscope.aliyuncs.com/v1 openclaw config set providers.coding-plan.temperature 0.7 openclaw config set providers.coding-plan.maxTokens 1024 openclaw gateway restart三件套对照表配任何 provider 都按这个填配置项含义示例值baseurl接口根地址https://taotoken.net/apiapikey鉴权密钥sk-xxxxxxxxmodel.primary主模型 IDtaotoken/qwen3.5-plus改完配置必须openclaw gateway restart否则不生效。这一步漏掉的人特别多表现为「配置明明改了但请求还是走旧模型」。4. 验证请求从连通性到真实对话配完不验证等于没配。这一节给逐项验证动作每一步都有预期结果对不上就往下看排障。第一步确认服务在跑openclaw gateway status预期输出里有running和当前端口号。如果是stopped先openclaw gateway start --daemon。第二步验证 provider 配置读到了openclaw config get providers.taotoken.baseurl openclaw config get agents.defaults.model.primary两条命令分别回显你填的 Base URL 和 Model ID。如果回显为空说明配置没写进去检查 JSON 文件路径和语法。第三步发一条真实请求。OpenClaw 提供 CLI 直连测试openclaw chat --message 用一句话说明你现在用的是哪个模型预期返回一段自然语言且内容里能看出模型身份。如果这里报错基本就是 Key 或 Base URL 的问题。第四步走 HTTP 层验证排除 OpenClaw 封装干扰curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: qwen3.5-plus, messages: [{role: user, content: ping}] }预期返回 JSONchoices[0].message.content里有内容。这一步通了说明 Key、Base URL、模型 ID 三件套全对问题只可能在 OpenClaw 侧。第五步WebUI 端到端。打开openclaw dashboard url给的地址登录后在对话框发一条消息看是否正常返回。WebUI 通了整条链路就闭环了。验证顺序建议严格按「服务状态 → 配置回显 → CLI 请求 → HTTP 请求 → WebUI」走哪一步断掉就锁定哪一层别一上来就怀疑模型。我踩过的坑是HTTP 层通了但 WebUI 不通最后发现是浏览器缓存了旧的 Token清一下就好。5. 常见报错逐项排查这一节按真实报错对照每条都给定位方法和修复动作。401 Unauthorized。最常见Key 错了或没带上。先确认providers.xxx.apikey的值和 TaoToken 控制台里的一致注意前后不能有空格。然后确认请求头是Authorization: Bearer sk-xxxBearer 后面有一个空格。如果 Key 是从网页复制的检查有没有把换行符带进去。修复后openclaw gateway restart。local proxy failed。这个报错通常出现在本地部署且配了代理类中间层时。OpenClaw 2026 版本对本地回环地址的请求有校验如果你的 Base URL 指向了本机某个转发端口会被拦。解决方法是把 Base URL 直接指向 https://taotoken.net/api 不要经过本地转发。同时检查环境变量里有没有残留的HTTP_PROXY/HTTPS_PROXY有就 unset 掉再重启服务。reading choices 报错。典型表现是Cannot read properties of undefined (reading choices)。这说明请求发出去了但返回体结构不对——大概率是 Base URL 少了/v1或多了/v1。TaoToken 的根地址是 https://taotoken.net/api OpenClaw 内部会拼/v1/chat/completions所以 baseurl 填到/api为止不要再加/v1。填错就会拿到非预期响应解析 choices 时崩掉。OAuth 相关报错。如果你用的是 Claude Code 类工具对接报 OAuth 失败检查是不是把 Anthropic 兼容入口和普通 API 入口混用了。Claude Code 场景走 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite 对应的配置方式Key 从 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 拿。普通 OpenClaw 对话不需要 OAuth用 Bearer Key 即可。服务启动失败。先node -v确认是 22.x。Linux 上如果版本低curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs再openclaw gateway start --daemon。Windows 上如果 PowerShell 报执行策略错误回到 §3 的Set-ExecutionPolicy那步。Web 控制台打不开。三个检查点地域是否免备案、随机端口是否放行firewall-cmd --list-ports看有没有你拿到的那个端口、服务是否 running。三条都过还打不开openclaw gateway restart再来一次。数据备份。配置和技能数据都在~/.openclaw/下定期备份cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw-backup.json cp -r ~/.openclaw/skills ~/.openclaw/skills-backup排障时如果涉及 Cline MCP 或 Codex auth.json 的配置记住三件套必须齐全Base URL、Key、Model ID缺一个都会报鉴权或模型找不到。CC Switch 切换 provider 后同样要 restart。6. 长期跑起来把配置固化下来部署通了只是开始长期稳定运行还得做几件事。第一把模型配置写进版本管理但 Key 用环境变量注入别硬编码在 JSON 里。OpenClaw 支持读环境变量你可以在启动脚本里export TAOTOKEN_KEYsk-xxx配置文件里写apikey: ${TAOTOKEN_KEY}。第二阿里云实例设个快照策略每周自动备份系统盘。本地的话~/.openclaw/目录加进你的同步盘或 git 私仓。第三监控端口和进程。简单做法是加一条 cron*/5 * * * * openclaw gateway status | grep -q running || openclaw gateway start --daemon第四模型切换不用重装。想从千问换到 Coding Plan只改agents.defaults.model.primary和对应 provider 的 apikeyrestart 即可。长期编码 / Agent 高频场景建议直接上 Coding Plan入口 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 额度更稳。最后给一个我常用的验证脚本每次改完配置跑一遍五秒确认链路健康#!/bin/bash echo 服务状态 openclaw gateway status echo 当前模型 openclaw config get agents.defaults.model.primary echo 连通性 curl -s -o /dev/null -w %{http_code} -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_KEY \ -H Content-Type: application/json \ -d {model:qwen3.5-plus,messages:[{role:user,content:ping}]} echo 返回 200 就说明整条链路是通的。把这套流程跑顺之后OpenClaw 在阿里云和本地三系统上的部署差异其实就只剩安装和端口两步模型配置完全通用。
