1. 为什么新手部署 OpenClaw 总卡在 API Key 这一步OpenClaw 是一个开源 AI 智能体图标是只红色小龙虾社区里把部署和调教它的过程叫“养龙虾”。它能帮你处理文件、跑脚本、做联网检索、接各种工具链本质上是一个可以自己调度模型和本地能力的助理框架。适合谁适合想拥有一个私有 AI 助理、又不想从零写调度逻辑的人也适合想拿它练手 Agent 编排的开发者。但我在帮朋友远程排障时发现真正让人卡住的从来不是“买服务器”而是 API Key 怎么拿、往哪写、写完为什么不生效。阿里云轻量应用服务器确实把门槛压得很低预装镜像点几下就能起服务。可一旦进入“配置模型”环节新手就会遇到三个典型问题第一不知道 Key 从哪个控制台创建创建完页面一刷新就找不到了第二不知道配置文件在哪凭感觉改了个config.yaml结果服务读的是另一个路径第三Key 写进去了但请求报 401以为是 Key 错了其实是 Base URL 或模型 ID 没对上。这篇教程就按“从零到跑通”的顺序走一遍先在阿里云轻量服务器上把 OpenClaw 跑起来再把 API Key 正确注入配置文件最后用一条验证指令确认服务真的在干活。全程命令可复制配置文件给模板报错给对照。你不需要懂容器编排也不需要会写 Python跟着敲就行。需要提前说明的是模型调用这部分我会用 TaoToken 的 API 来演示因为它兼容 OpenAI 风格的接口Base URL 和 Key 的写法很标准适合拿来当配置范例。你换成别的兼容服务改三个字段即可。下面正式开始。2. 阿里云轻量服务器初始化与 OpenClaw 环境准备买服务器这一步在控制台点选即可镜像选应用镜像里的 OpenClaw规格 2 核 2G 起步2 核 4G 更稳。地域建议选海外节点内地节点在联网检索类功能上限制较多可能影响 OpenClaw 的搜索工具调用。支付完成后系统会自动完成预装你拿到的是公网 IP、root 密码或密钥。登录服务器我用的是 SSHWindows 用 PowerShell 或 XshellMac 直接终端。命令如下ssh root你的服务器公网IP第一次登录会问 yes/no输 yes然后粘贴密码。进去之后先确认 OpenClaw 的安装位置和服务状态。预装镜像通常把服务放在/opt/openclaw或/root/openclaw用下面这条命令找find / -maxdepth 4 -iname *openclaw* -type d 2/dev/null我实测下来多数镜像落在/opt/openclaw。进去看一眼目录结构cd /opt/openclaw ls -la你会看到类似config、data、logs、docker-compose.yml这样的内容。如果服务是用 Docker 跑的先确认容器状态docker ps -a正常应该有一个名为openclaw或openclaw-server的容器在 Up 状态。如果没起用 compose 拉起来cd /opt/openclaw docker compose up -d接着放通端口。阿里云轻量控制台里有“一键放通”会放行 22 和 18789。如果你在命令行操作防火墙用ufw allow 22/tcp ufw allow 18789/tcp ufw reload这里有个坑要提醒18789 是 Web UI 端口但 OpenClaw 的 API 服务可能跑在另一个端口比如 3000 或 8080。具体看docker-compose.yml里的端口映射。用下面这条确认docker port openclaw输出会告诉你容器端口映射到宿主机的哪个端口。记下来后面验证请求要用。环境准备到这一步服务器层面就通了。接下来是核心API Key 的获取和写入。很多人以为 Key 拿到手就完事其实写入位置和格式才是决定成败的地方。3. 可复制配置API Key 注入与 OpenClaw 配置文件模板先说 Key 从哪来。我用 TaoToken 的 API Key 做演示它的控制台在https://taotoken.net/console进去后创建 Key复制保存。注意Key 只在创建时完整显示一次刷新页面就看不到了这点和大多数平台一样。创建入口在 API Keys 页面https://taotoken.net/api-keys。拿到 Key 之后回到服务器找到 OpenClaw 的配置文件。常见路径有三个按优先级找ls /opt/openclaw/config/ ls /opt/openclaw/.env ls /opt/openclaw/config/config.yaml如果镜像用的是.env注入那配置就在.env里如果是 YAML就在config.yaml。我下面给一份通用的 YAML 模板字段名按 OpenClaw 常见约定写你对照自己的文件改# /opt/openclaw/config/config.yaml server: host: 0.0.0.0 port: 3000 web_ui_port: 18789 model: provider: openai-compatible base_url: https://taotoken.net/api api_key: sk-你的TaoToken密钥 model_id: gpt-4o-mini max_tokens: 4096 temperature: 0.7 tools: web_search: enabled: true file_ops: enabled: true workspace: /opt/openclaw/data/workspace logging: level: info path: /opt/openclaw/logs/openclaw.log三个关键字段必须写全base_url、api_key、model_id。Base URL 用https://taotoken.net/api不要多加斜杠也不要写成/v1结尾具体以你所用服务的文档为准。Model ID 填你账号下可用的模型名比如gpt-4o-mini或claude-3-5-sonnet填错会报模型不存在。如果镜像是.env风格就写成这样# /opt/openclaw/.env OPENCLAW_MODEL_PROVIDERopenai-compatible OPENCLAW_BASE_URLhttps://taotoken.net/api OPENCLAW_API_KEYsk-你的TaoToken密钥 OPENCLAW_MODEL_IDgpt-4o-mini OPENCLAW_PORT3000 OPENCLAW_WEB_PORT18789写完保存重启服务让配置生效cd /opt/openclaw docker compose restart然后看日志确认没有报错docker logs -f openclaw --tail 50日志里出现model provider initialized或server listening on 0.0.0.0:3000就说明配置被读进去了。如果出现api key not found或invalid base url回到配置文件检查字段名和引号。YAML 对缩进敏感api_key前面必须是两个空格不能用 Tab。这一步做完Key 就算正确注入了。但“写进去”不等于“能用”下一步必须发一条真实请求验证。4. 验证请求一条命令确认 OpenClaw 服务正常启动验证分两层先确认服务端口活着再确认模型调用能通。第一层用 curl 打健康检查接口curl -s http://127.0.0.1:3000/health正常返回类似{status:ok,model:gpt-4o-mini}。如果返回Connection refused说明服务没起或端口不对回去看docker ps和docker port。第二层直接调模型接口确认 Key 和 Base URL 都对curl -s -X POST http://127.0.0.1:3000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话说明你是什么}], max_tokens: 100 }如果 OpenClaw 的 API 路径不是/v1/chat/completions换成它文档里写的路径。返回里能看到choices数组和模型输出就说明整条链路通了请求进 OpenClawOpenClaw 用配置里的 Key 调模型模型返回结果。你也可以直接测底层 API绕过 OpenClaw确认 Key 本身没问题curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }这条通了说明 Key 和 Base URL 没问题问题就出在 OpenClaw 配置层。两条都通你就可以打开浏览器访问 Web UI 了。地址是http://你的服务器IP:18789首次访问需要 TokenToken 在控制台的“访问 Web UI 面板”里生成或者看日志里的web token字段。我试过在 Web UI 里发一句“帮我列一下当前工作目录的文件”如果它能调工具并返回结果说明 Agent 的工具链也活了。到这一步你的“龙虾”就算养成了。5. 本篇常见错排查401、local proxy failed 与 reading choices 报错排障这部分我按真实报错来对照你遇到哪个查哪个。报错一401 Unauthorized。这是最常见的。原因通常有三个Key 复制时带了空格或换行Key 写进了配置文件但没重启服务Key 本身过期或被禁用。排查顺序先用第 4 节的底层 curl 测 Key通了说明 Key 没问题问题在 OpenClaw 读取配置的环节。检查config.yaml里api_key的值有没有被引号包住有没有多余空格。改完必须docker compose restart热加载不一定生效。报错二local proxy failed 或 connection refused。这个通常出现在 OpenClaw 试图访问外部 API 时。原因可能是服务器 DNS 解析异常或者出站流量被安全组拦了。先测 DNSnslookup taotoken.net再测出站连通性curl -I https://taotoken.net/api如果 curl 卡住或超时检查轻量服务器的防火墙规则确认出站 443 没有被限制。另外如果你在配置文件里把 Base URL 写成了http://而不是https://也会出现代理失败。报错三reading choices 相关报错比如cannot read property choices of undefined。这说明请求发出去了但返回结构不是预期的 OpenAI 格式。常见原因是 Base URL 写错比如多写了/v1或少了/v1导致打到了错误的端点。对照你所用服务的文档确认完整路径。另一个原因是 Model ID 填了一个不存在的模型服务返回了错误对象而不是正常的 choices 数组。把 Model ID 换成账号下确认可用的模型再试。报错四OAuth 或 token 过期类提示。如果你用的是需要 OAuth 刷新的服务Key 可能是短期有效的。OpenClaw 本身不负责刷新 OAuth token这种情况要么换成长期 Key要么在外部做刷新逻辑。用 TaoToken 这类 API Key 方式接入就不会有这个问题Key 是静态的写进配置就能长期用。报错五Web UI 打不开提示 token 无效。Token 是每次生成访问链接时动态出的复制时容易漏字符。重新在控制台点一次“访问 Web UI 面板”复制完整 URL注意 URL 里带的 token 参数要一起复制。如果还是不行看日志里的web token字段手动拼http://IP:18789/?tokenxxx。排障的核心思路就一条分层验证。先测底层 API再测 OpenClaw 健康检查最后测 Web UI。哪一层断了就修哪一层不要一上来就重装。6. 长期使用建议与接入文档入口跑通之后如果你打算长期用 OpenClaw 做编码辅助或 Agent 任务建议把模型调用切到 Coding Plan 这类套餐上成本更可控适合高频调用。配置方式和上面一样只改 Base URL 和 Key 即可。模型对话调试可以在模型对话页面直接试确认模型可用再写进配置。接入文档里有完整的字段说明和示例遇到配置字段不确定的时候查一下https://taotoken.net/doc。API Keys 管理在https://taotoken.net/api-keys创建和吊销都在这里。如果你用的是 Claude Code 类的编码工具Anthropic 兼容接入的说明在https://taotoken.net/claudecode-anthropic配置逻辑和本文一致三件套还是 Base URL、Key、Model ID。最后给一个实用技巧把配置文件备份一份到/opt/openclaw/config/config.yaml.bak每次改之前先备份改坏了直接覆盖回来比重装快得多。服务器快照也建议开阿里云轻量支持自动快照出问题回滚就行。养龙虾这件事配置一次跑通之后剩下的就是慢慢调教它干活了。