1. 为什么本地跑 OpenClaw 最容易翻车的地方不是安装OpenClaw 是一个能读写文件、执行命令、调用外部模型的本地 Agent 框架适合个人开发者在自己的机器上做自动化任务。它本身不挑环境Docker 能跑WSL2 里也能跑但真正让人头疼的从来不是装不上而是装完之后 Key 到处散落、环境变量互相覆盖、容器和宿主机网络对不上。我见过太多人第一天兴致勃勃 clone 仓库第三天就在群里问为什么容器里读不到我的 API Key。这个问题的根源在于OpenClaw 的模型调用链路通常涉及三个位置——宿主机 shell 的环境变量、Docker Compose 的 env_file、以及 WSL2 内部的 export。你如果每个工具都单独配一份 KeyCline 一份、Claude Code 一份、OpenClaw 又一份改一次 Key 要改五个地方漏一个就报 401。更麻烦的是很多教程让你把 Key 直接写进 docker-compose.yml一旦这个文件被推到 Git 仓库Key 就泄露了。所以这篇要解决的场景很具体你在 Windows 上用 WSL2 Docker 跑 OpenClaw希望所有模型请求走同一个入口Key 只维护一份容器和宿主机都能用而且不把敏感信息写进版本控制。做法是把 OpenClaw 的 endpoint 统一指向 TaoToken 的兼容通道Base URL 填https://taotoken.net/apiKey 通过.env文件注入Docker Compose 和 WSL2 共享同一份配置。这样你换模型、换 Key、加工具都只动一个文件。适合谁看已经装好 Docker Desktop 和 WSL2、能跑起 Ubuntu 22.04、但被多工具 Key 管理搞烦的个人开发者。如果你还没装 WSL2文中有安装命令如果你已经在裸机跑 OpenClaw 想迁到容器第 3 节的 compose 片段可以直接抄。先说清楚低风险的核心逻辑隔离、单一入口、可回滚。隔离靠 Docker 的沙箱和 WSL2 的独立文件系统单一入口靠 TaoToken 统一 Base URL可回滚靠把配置和 Key 分离改坏了删掉.env重来就行。下面按这个思路一步步落地。2. TaoToken 前置准备一份 Key 打通 Docker 与 WSL2在动 Docker 之前先把 Key 和通道准备好否则后面容器起来了还要回头改配置。TaoToken 在这里的角色是一个统一的模型调用入口你拿一个 Key就能在 OpenClaw、Cline、Claude Code 这些工具里共用同一个 Base URL不用每个工具去不同平台申请。对本地部署来说最大的好处是环境变量只需要维护一个TAOTOKEN_API_KEY容器内外引用同一个值。第一步注册并拿到 Key。打开官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content完成账号注册后进入控制台。控制台地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite在里面找到 API Keys 页面新建一个 Key。建议命名带上用途比如openclaw-local方便以后区分和吊销。Key 只在创建时完整显示一次复制后先存到密码管理器别直接贴在聊天窗口里。第二步确认你要用的模型 ID。在模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite可以先试跑一下看看哪个模型响应符合预期。OpenClaw 的配置里需要填 Model ID常见的有claude-sonnet-4-20250514、gpt-4o这类具体以你账号下可用的为准。把选定的 Model ID 记下来后面写进.env。第三步理解 Base URL 的写法。TaoToken 的 API 入口是https://taotoken.net/api注意这里不加任何 UTM 参数因为它是给程序调用的加了反而可能被某些 HTTP 客户端当成路径的一部分。OpenClaw 里配置 endpoint 时通常填到/api这一层具体的/v1/chat/completions由框架自己拼接。如果你用的是 OpenAI 兼容模式Base URL 就是https://taotoken.net/apiKey 放在Authorization: Bearer头里。第四步规划文件结构。在 WSL2 的 Ubuntu 里建一个工作目录比如~/openclaw-stack里面放三个东西docker-compose.yml、.env、以及 OpenClaw 的配置目录./data。.env负责存 Key 和 Model IDdocker-compose.yml负责引用这些变量./data挂载给容器做持久化。这样 Key 永远不进 compose 文件也不会被 Git 追踪记得把.env写进.gitignore。这里有个容易踩的坑WSL2 里的 Docker 有两种模式一种是 Docker Desktop 的 WSL2 集成一种是直接在 Ubuntu 里装 Docker Engine。前者用docker compose命令后者可能需要docker-compose带横线。本文以 Docker Desktop 集成为例命令统一用docker compose。如果你用的是独立 Engine把命令里的空格换成横线即可配置文件内容完全一样。还有一点WSL2 的文件系统性能在跨 Windows 和 Linux 边界时会下降。建议把~/openclaw-stack放在 WSL2 的 Linux 文件系统里也就是/home/你的用户名/下不要放在/mnt/c/下。后者每次读写都要跨文件系统容器启动会明显变慢日志写入也容易出权限问题。这一点在长期运行的项目里影响很大。3. 可复制配置docker-compose 与 WSL2 端口映射这一节给可以直接抄的配置。先建目录和文件mkdir -p ~/openclaw-stack/data cd ~/openclaw-stack touch docker-compose.yml .env然后编辑.env内容如下。注意 Key 换成你自己的Model ID 换成你在模型对话里验证过的# .env —— 只维护这一份容器和宿主机共用 TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api OPENCLAW_MODELclaude-sonnet-4-20250514 OPENCLAW_GATEWAY_PORT18789接着写docker-compose.yml。这个片段的关键点有三个用env_file注入变量而不是写死、端口只绑定127.0.0.1不暴露公网、数据目录挂载到本地./dataservices: openclaw-gateway: image: openclaw/openclaw:latest container_name: openclaw-gateway restart: unless-stopped env_file: - .env environment: - OPENAI_API_KEY${TAOTOKEN_API_KEY} - OPENAI_BASE_URL${TAOTOKEN_BASE_URL} - OPENCLAW_MODEL${OPENCLAW_MODEL} - SANDBOX_ENABLEDtrue ports: - 127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789 volumes: - ./data:/root/.openclaw deploy: resources: limits: cpus: 2.0 memory: 4G这里解释几个参数。OPENAI_API_KEY和OPENAI_BASE_URL是 OpenClaw 识别 OpenAI 兼容通道的标准变量名TaoToken 的通道兼容这个格式所以直接映射过去就行。SANDBOX_ENABLEDtrue让 Agent 在容器内以受限权限运行避免它直接操作宿主机文件。ports写成127.0.0.1:18789:18789意味着只有本机能访问这个端口局域网其他机器和公网都连不上这是低风险部署的底线。deploy.resources.limits限制容器最多用 2 核 4G防止某个失控任务把整机资源吃满。WSL2 的端口映射需要额外注意。Docker Desktop 在 WSL2 模式下容器端口绑定到127.0.0.1后Windows 宿主机默认可以通过localhost:18789访问因为 Docker Desktop 做了端口转发。但如果你用的是独立 Docker EngineWSL2 的localhost和 Windows 的localhost不是一回事需要在 Windows 侧做端口转发。用管理员 PowerShell 执行# 仅在独立 Docker Engine 模式下需要 netsh interface portproxy add v4tov4 listenport18789 listenaddress127.0.0.1 connectport18789 connectaddress$(wsl hostname -I).Trim()执行后用netsh interface portproxy show all确认规则存在。如果之后 WSL2 的 IP 变了重启后可能变这条规则要重新加。Docker Desktop 用户跳过这一步直接用localhost即可。启动服务docker compose up -d openclaw-gateway docker compose logs -f openclaw-gateway日志里如果看到 gateway 监听 18789 且没有报 Key 相关错误说明配置注入成功。如果报OPENAI_API_KEY not set检查.env文件是否在docker-compose.yml同目录以及env_file路径是否正确。注意.env文件不要有多余空格KEYvalue等号两边不能有空格这是最常见的低级错误。关于 Claude Code 或 Cline 这类工具如果你也想让它们走同一个通道配置三件套是Base URL 填https://taotoken.net/apiKey 填.env里那个Model ID 填你验证过的。Cline 的 MCP 配置里如果涉及 OpenClaw 作为工具同样引用这个 Base URL。这样你所有本地工具的模型请求都从 TaoToken 出去账单和用量在一个地方看不用来回切换。4. 验证请求一次连通性检查清单配置写完不算完得实际发一次请求确认链路通。最直接的方式是用 curl 打 TaoToken 的接口确认 Key 和 Base URL 没问题再确认 OpenClaw 容器能读到这些变量。先在 WSL2 里直接测通道source .env curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: ${OPENCLAW_MODEL}, messages: [{role: user, content: reply with ok}], max_tokens: 10 }如果返回 JSON 里choices[0].message.content有内容说明 Key 和通道都正常。如果返回 401说明 Key 错了或没生效如果返回 404检查 Base URL 是不是多写了或少写了/v1。TaoToken 的 Base URL 是https://taotoken.net/api具体路径由客户端拼接curl 测试时手动补/v1/chat/completions。接着测容器内部能不能读到变量docker compose exec openclaw-gateway env | grep -E OPENAI|OPENCLAW应该能看到OPENAI_API_KEY、OPENAI_BASE_URL、OPENCLAW_MODEL三个变量值和你.env里一致。如果OPENAI_API_KEY是空的说明env_file没生效检查文件路径和权限。然后测 OpenClaw 网关本身是否响应curl -s http://127.0.0.1:18789/health不同版本的 OpenClaw 健康检查路径可能不同有的用/health有的用/。如果返回连接拒绝说明容器没起来或端口没映射用docker compose ps看容器状态docker compose logs看报错。最后做一次端到端验证在 OpenClaw 里触发一个简单任务比如让它读一个本地文件并总结。观察日志里模型请求的 endpoint 是不是指向 TaoToken。如果日志里出现local proxy failed或connection refused通常是容器内 DNS 解析问题可以在 compose 里加dns: 8.8.8.8试试但更可能是 Base URL 写成了localhost而不是完整域名。容器里的localhost指向容器自己不是宿主机所以 Base URL 必须是https://taotoken.net/api这种绝对地址。验证清单汇总成一张表方便你逐项打勾检查项命令预期结果通道连通curl 打/v1/chat/completions返回 choices 内容变量注入docker compose exec ... env三个变量齐全网关存活curl127.0.0.1:18789/health200 或 ok端到端OpenClaw 触发任务日志 endpoint 指向 TaoToken端口隔离从另一台机器访问连接超时预期全部通过后你的 OpenClaw 就跑在一个隔离、单一 Key、可回滚的环境里了。之后换模型只改.env里的OPENCLAW_MODEL然后docker compose up -d重建容器即可不用动 compose 文件。5. 本篇常见报错排查401、local proxy failed 与 OAuth本地部署最容易卡在几个固定报错上这一节按真实错误信息对照排查。401 Unauthorized。这是最高频的。原因通常有三个Key 复制时带了空格或换行、.env文件里等号两边有空格、或者容器读到的还是旧变量。排查顺序先docker compose exec openclaw-gateway env | grep OPENAI_API_KEY看容器里的值和.env对比。如果值不对检查.env格式确保是TAOTOKEN_API_KEYsk-xxx没有引号没有空格。如果值对但还报 401用第 4 节的 curl 直接测 Key确认 Key 本身有效。有时候 Key 在控制台被吊销了但本地没更新也会 401。local proxy failed / connection refused。这个报错说明 OpenClaw 尝试连一个本地代理但连不上。常见原因是 Base URL 被配成了http://localhost:xxxx或http://127.0.0.1:xxxx而容器里的 localhost 是容器自己。解决方法是把 Base URL 改成https://taotoken.net/api这个绝对地址。如果你确实需要走本地代理那代理必须和 OpenClaw 在同一个容器网络里用服务名而不是 localhost 访问。对大多数个人开发者来说直接用 TaoToken 的远程通道更简单不需要本地代理。reading choices: unexpected end of JSON input。这个报错通常不是 Key 问题而是响应体为空或不是 JSON。可能原因Base URL 路径拼错了比如写成了https://taotoken.net/api/v1而客户端又拼了一次/v1导致请求打到不存在的路径返回 HTML 错误页。检查方法是看容器日志里实际请求的完整 URL。正确做法是 Base URL 只填到https://taotoken.net/api让客户端自己拼/v1/chat/completions。另外如果 Model ID 填错有些通道会返回非 JSON 的错误体也会触发这个报错确认 Model ID 和你在模型对话里验证的一致。OAuth 相关报错。如果你在 OpenClaw 里配置了需要 OAuth 的工具或 MCP 服务可能会看到OAuth token expired或invalid_grant。这类报错和模型通道无关是工具侧的授权过期。处理方法是重新走一遍该工具的授权流程。注意不要把 OAuth 和 API Key 混在一起OpenClaw 的模型调用走OPENAI_API_KEY工具授权走各自的 OAuth 配置两者独立。如果你用 Cline 的 MCP 接 OpenClawMCP 的配置里引用的 Base URL 和 Key 要和.env保持一致否则会出现模型能调但工具调不了的情况。Codex auth.json 相关。如果你同时用 Codex 类工具它的auth.json里存的是另一套凭证。确保auth.json里的 Base URL 也指向https://taotoken.net/apiKey 用同一个。三件套Base URL Key Model ID在 Codex、Cline、OpenClaw 里保持一致能避免大部分这个工具能用那个不能用的问题。端口占用。docker compose up时报port is already allocated说明 18789 被别的进程占了。用ss -tlnp | grep 18789找到占用进程或者改.env里的OPENCLAW_GATEWAY_PORT换一个端口。改完记得同步更新 WSL2 端口转发规则如果用了的话。权限问题。容器写./data时报permission denied通常是宿主机目录属主和容器内用户不匹配。OpenClaw 镜像默认以非 root 用户运行而./data是你用当前用户建的。解决方法是chmod 777 ./data测试用或把目录属主改成容器内用户 ID。生产环境建议用chown精确设置不要长期用 777。排查时养成看日志的习惯docker compose logs -f --tail100 openclaw-gateway。大部分报错在日志里有更详细的堆栈比只看客户端返回的错误信息有用得多。6. 把 Key 收拢到一处之后走到这里你的 OpenClaw 应该已经跑在 Docker WSL2 里模型请求统一从 TaoToken 的通道出去Key 只在.env里维护一份。之后不管你是加一个新工具、换一个模型、还是把服务迁到另一台机器都只需要复制.env和docker-compose.yml两个文件不用再去每个工具里翻配置。如果你打算长期跑编码类或 Agent 类任务可以了解一下 Coding Plan地址是https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite适合需要稳定调用和用量管理的场景。日常调试模型效果用模型对话页面就够了。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有各工具的 Base URL 填法和参数说明。API Keys 管理在控制台需要新建或吊销 Key 时去那里操作。最后留一个实用习惯每次改完.env先docker compose config检查变量是否正确解析再docker compose up -d重建。这一步能挡掉大部分因为变量没生效导致的 401。另外.env一定要进.gitignore如果你把~/openclaw-stack初始化成了 Git 仓库先确认git status里看不到.env再提交。