1. 为什么新手部署 OpenClaw 总在 Key 上翻车OpenClaw前身 Clawdbot/Moltbot是一个开源、本地优先的 AI 助理框架能 7×24 小时在线响应、执行多任务自动化、跨平台协同。它和普通聊天机器人的区别在于不只是对话还能通过指令完成文件处理、日程管理、邮件整理、多平台自动化操作兼容 Qwen、GPT、Claude 等多款大模型。适合个人办公和轻量团队协作是能真正落地的“数字员工”。但新手在阿里云 ECS 上从零部署 OpenClaw 并接入 ClawHub 时最容易卡住的地方不是 Docker 装不上而是多模型 Key 分散、环境变量写错位置。典型场景你在.env里写了OPENAI_API_KEY又在openclaw.json里配了models.providers.bailian.apiKey结果容器启动后日志报401 Unauthorized你以为是 Key 失效其实是变量名对不上或者你换了模型供应商要同时改三四个文件改漏一个就local proxy failed。这篇教程聚焦一条完整路径在阿里云 ECS 上用 docker-compose 部署 OpenClaw把 endpoint 与 API Key 统一改到 TaoToken再用 curl 验证请求、用日志排查错误。全程可复制不需要你懂运维。先说清楚 TaoToken 在这里的角色它是一个统一 Key 接入层把原本分散在 OpenAI、Anthropic、Qwen 等不同供应商的 endpoint 和 Key 收敛成一套 Base URL 一个 Key 多个 Model ID。对 OpenClaw 这种要同时调多个模型的后端来说配置量直接减半环境变量出错概率也大幅下降。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 地址是 https://taotoken.net/api 这个不加 UTM直接用于代码里。你需要准备的东西一台阿里云 ECS2vCPU2GiB 内存起步推荐 2vCPU4GiB、一个 TaoToken API Key、能 SSH 登录服务器的终端。下面从零开始。2. 阿里云 ECS 前置准备与 TaoToken Key 获取2.1 服务器规格与系统选择OpenClaw 对内存有硬性要求低于 2GB 会直接导致服务启动失败。个人日常使用选 2vCPU2GiB 能跑起来但如果你要同时挂 ClawHub 技能、跑文件处理任务建议直接上 2vCPU4GiB避免运行中 OOM。存储选 40GiB ESSD 起步系统盘用 ESSD 比普通云盘读写快服务卡顿明显减少。系统镜像推荐 Alibaba Cloud Linux 3.2104 LTS 64位 或 Ubuntu 22.04 LTS 64位。这两个版本对 Docker 和 Node.js 22.x 的兼容性最好社区踩坑记录也最多遇到问题好搜。地域选择上如果你需要联网搜索功能完整优先选中国香港或海外地域国内地域除香港的轻量服务器联网搜索会受限这点在选购时就要确认。安全组方面OpenClaw 默认 Web 服务端口是 18789你需要在阿里云控制台的防火墙/安全组里放行这个端口。如果只是本机调试也可以先不放行用 SSH 隧道访问但新手建议直接放行省去隧道配置的麻烦。2.2 获取 TaoToken API Key登录 TaoToken 控制台进入 API Keys 页面创建一个新 Key。创建后立即复制保存页面通常只显示一次。这个 Key 的格式类似sk-xxxxxxxx后面所有配置都用它。同时记下两个地址Base URLhttps://taotoken.net/api模型对话入口用于验证模型是否通https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite如果你打算长期跑编码类 Agent 任务可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。新手先不用管把基础部署跑通再说。2.3 SSH 连接与环境预检用 FinalShell 或 Xshell 连接服务器或者直接用终端ssh root你的服务器公网IP输入密码后进入服务器。先做一轮环境预检确认系统版本、内存、端口、外网连通性# 查看系统版本 cat /etc/os-release # 查看内存确认 2GiB free -h # 查看 18789 端口是否被占用 ss -tlnp | grep 18789 # 测试外网连通性 curl -I https://taotoken.net/api如果free -h显示内存低于 2GiB或者curl超时先解决这两个问题再往下走。端口被占用的话找出占用进程并终止或者改 OpenClaw 的监听端口。预检通过后安装 Docker 和 docker-compose。Alibaba Cloud Linux 3 和 Ubuntu 22.04 都可以用官方脚本# 安装 Docker curl -fsSL https://get.docker.com | bash # 启动并设置开机自启 systemctl enable docker systemctl start docker # 验证 docker --version docker compose versiondocker compose version能输出版本号就说明 compose 插件已就位。如果提示docker: compose is not a docker command说明你装的是旧版 docker-compose用docker-compose --version验证后面命令里把docker compose换成docker-compose即可。3. 可复制的 docker-compose 与 .env 配置这一节是核心。我把 OpenClaw 的部署拆成三个文件docker-compose.yml、.env、openclaw.json。你只需要改.env里的 Key其他基本不用动。3.1 目录结构在服务器上建一个工作目录mkdir -p /opt/openclaw cd /opt/openclaw mkdir -p data logs最终结构/opt/openclaw ├── docker-compose.yml ├── .env ├── openclaw.json ├── data/ └── logs/3.2 docker-compose.ymlversion: 3.8 services: openclaw: image: openclaw/openclaw:2026.1.25 container_name: openclaw restart: unless-stopped ports: - 18789:18789 env_file: - .env volumes: - ./data:/root/.openclaw - ./logs:/root/.openclaw/logs - ./openclaw.json:/root/.openclaw/openclaw.json environment: - TZAsia/Shanghai healthcheck: test: [CMD, curl, -f, http://localhost:18789/health] interval: 30s timeout: 10s retries: 3这里的关键点env_file加载.envvolumes把配置文件和日志挂到宿主机方便你直接改配置、看日志不用进容器。restart: unless-stopped保证服务器重启后服务自动拉起。3.3 .env 文件# TaoToken 统一接入配置 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYsk-你的TaoToken密钥 # OpenClaw 默认模型用 TaoToken 上的 Model ID OPENCLAW_DEFAULT_MODELclaude-sonnet-4-20250514 # Web 控制台访问 Token自己设一个复杂字符串 OPENCLAW_GATEWAY_TOKENyour-strong-token-here # 日志级别 OPENCLAW_LOG_LEVELinfo注意TAOTOKEN_API_KEY后面不要有空格不要加引号除非 Key 里本身有特殊字符。很多新手在这里多打一个空格导致请求头里 Key 带空格服务端返回 401。3.4 openclaw.json{ models: { providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: [ { id: claude-sonnet-4-20250514, name: Claude Sonnet 4 }, { id: gpt-4o, name: GPT-4o }, { id: qwen-max, name: Qwen Max } ] } }, default: taotoken/claude-sonnet-4-20250514 }, gateway: { port: 18789, token: ${OPENCLAW_GATEWAY_TOKEN} }, logging: { level: info, file: /root/.openclaw/logs/openclaw.log } }这里apiKey用${TAOTOKEN_API_KEY}引用环境变量OpenClaw 启动时会从.env读取。这样你换 Key 只改.env一处不用动 JSON。default字段指定默认模型格式是provider/model-id。3.5 启动服务cd /opt/openclaw docker compose up -d查看启动状态docker compose ps docker compose logs -f openclaw日志里看到Gateway listening on 0.0.0.0:18789和Model provider taotoken initialized就说明启动成功。如果看到401或invalid api key先别急下一节教你怎么验证和排查。4. 验证请求与成功结果部署完不验证等于没部署。这一节用 curl 直接打 TaoToken 的接口确认 Key 和 endpoint 都通再验证 OpenClaw 容器内部能正常调用模型。4.1 先用 curl 验证 TaoToken 连通性在服务器上执行curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: claude-sonnet-4-20250514, messages: [ {role: user, content: 回复两个字通了} ], max_tokens: 20 }成功的话返回类似{ id: chatcmpl-xxx, object: chat.completion, choices: [ { index: 0, message: { role: assistant, content: 通了 }, finish_reason: stop } ] }如果返回401说明 Key 错了或没带Bearer前缀返回404说明 endpoint 路径不对确认是https://taotoken.net/api/v1/chat/completions返回model not found说明 Model ID 写错了去模型对话页面确认可用模型列表。4.2 验证 OpenClaw 容器内部调用进入容器docker exec -it openclaw bash在容器内执行同样的 curlcurl -X POST $TAOTOKEN_BASE_URL/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:ping}],max_tokens:10}这一步验证的是容器内环境变量是否正确加载。如果容器内报401但宿主机 curl 正常说明.env没被正确读取检查docker-compose.yml里env_file路径和.env文件权限。4.3 通过 Web 控制台验证浏览器访问http://你的服务器公网IP:18789输入.env里设置的OPENCLAW_GATEWAY_TOKEN登录。在对话框输入你好请告诉我你当前使用的模型名称如果回复里包含claude-sonnet-4或你配置的默认模型说明整条链路通了。再试一个文件处理指令创建一个名为 test.txt 的文件内容为 OpenClaw 部署成功返回文件创建成功的提示说明自动化功能也正常。4.4 查看日志确认无报错docker compose logs --tail100 openclaw | grep -i error没有输出说明没有错误日志。如果有local proxy failed通常是容器内 DNS 解析问题在docker-compose.yml的environment里加- DNS223.5.5.5后重启。5. 本篇常见错误排查这一节对照真实报错给出定位和修复方法。你遇到问题时先在这里找。5.1 401 Unauthorized现象日志里出现401 Unauthorized或invalid api key。原因Key 错误、Key 带空格、Key 未加载、Authorization 头格式不对。排查步骤宿主机执行echo $TAOTOKEN_API_KEY确认输出和你在 TaoToken 控制台复制的一致。检查.env文件里 Key 后面有没有多余空格用cat -A .env | grep TAOTOKEN_API_KEY看行尾是否有$之外的字符。容器内执行env | grep TAOTOKEN确认变量已注入。curl 时确认Authorization: Bearer sk-xxx中间有一个空格Bearer不能少。5.2 local proxy failed现象日志报local proxy failed或dial tcp: lookup taotoken.net: no such host。原因容器内 DNS 解析失败或者服务器本身无法访问外网。修复# 在 docker-compose.yml 的 environment 下加 - DNS223.5.5.5 - DNS8.8.8.8然后docker compose down docker compose up -d。如果还不行在宿主机执行curl -I https://taotoken.net/api确认宿主机网络正常。5.3 reading choices 报错现象日志出现error reading choices或unexpected end of JSON input。原因模型返回的响应格式和 OpenClaw 预期的不一致通常是 Model ID 写错或者请求被中间层拦截返回了 HTML 错误页。修复确认openclaw.json里的 Model ID 和 TaoToken 模型列表里的一致。用 4.1 的 curl 命令直接打看返回的是 JSON 还是 HTML。如果是 HTML说明 endpoint 路径错了。检查baseUrl是否写成了https://taotoken.net/api/末尾多斜杠去掉末尾斜杠。5.4 OAuth 相关报错现象日志出现OAuth token expired或refresh token failed。原因如果你之前用 OAuth 方式接入过其他供应商OpenClaw 可能还在尝试刷新旧 token。修复在openclaw.json里删除旧的 provider 配置只保留taotoken一个 provider。然后清空data/目录下的缓存docker compose down rm -rf data/cache docker compose up -d5.5 端口无法访问现象浏览器打不开http://公网IP:18789。排查阿里云控制台安全组是否放行 18789 端口入方向。服务器本机防火墙firewall-cmd --list-ports或ufw status确认 18789 已放行。容器是否在运行docker compose ps状态是Up才正常。容器内监听地址docker exec openclaw ss -tlnp | grep 18789确认监听的是0.0.0.0而不是127.0.0.1。5.6 ClawHub 技能安装失败现象clawhub install xxx报command not found或network timeout。修复# 确认 clawhub 已安装 which clawhub # 如果没有用 npm 安装 npm install -g clawhub # 刷新环境变量 source ~/.bashrc # 测试网络 curl -I https://clawhub.openclaw.ai如果网络超时检查服务器是否能访问外网或者换一个 ClawHub 镜像源如果有的话。6. 统一 Key 接入后的日常维护与 CTA部署跑通只是开始日常维护才是让 OpenClaw 稳定干活的关键。这一节说几个实用操作。6.1 常用命令速查# 查看服务状态 docker compose ps # 重启服务改配置后生效 docker compose restart openclaw # 查看实时日志 docker compose logs -f openclaw # 停止服务 docker compose down # 更新镜像 docker compose pull docker compose up -d # 进入容器 docker exec -it openclaw bash6.2 换模型只改一处因为所有模型都走 TaoToken 统一接入你想换默认模型时只需要改openclaw.json里的default字段default: taotoken/gpt-4o然后docker compose restart openclaw。不用改.env不用改docker-compose.yml不用重新配 Key。这就是统一 Key 接入的价值。6.3 备份配置# 备份整个配置目录 tar -czf openclaw-backup-$(date %Y%m%d).tar.gz /opt/openclaw # 恢复时解压到原路径即可建议每周备份一次尤其是你装了很多 ClawHub 技能之后。6.4 查看 API Key 用量登录 TaoToken 控制台在 API Keys 页面可以看到每个 Key 的调用量和余额。如果发现用量异常增长检查是不是某个技能在循环调用模型。6.5 下一步做什么基础部署跑通后你可以安装 ClawHub 技能扩展功能clawhub search basic-utils clawhub install basic-utils接入钉钉/飞书等 IM 工具通过聊天窗口下达指令配置多个模型做 fallback主模型超时自动切备用模型如果你在验证模型时想快速测试不同 Model ID 的响应效果可以直接用模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。长期跑编码类 Agent 任务的话Coding Plan 的额度更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。需要管理多个 Key 或查看调用明细去控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建新 Key 在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入文档里有各语言 SDK 的示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后说一个我踩过的坑.env文件不要用 Windows 记事本编辑后直接上传记事本会加 BOM 头导致第一行变量名前面多一个不可见字符OpenClaw 读不到TAOTOKEN_BASE_URL。用vim或nano在服务器上直接编辑或者用 VS Code 的 Remote SSH 保存为 UTF-8 无 BOM。这个坑排查起来很费时间因为cat看不出来得用xxd .env | head才能看到 BOM 字节。