本地部署OpenClaw（原Clawdbot）：Windows/macOS/Linux环境变量配置与TaoToken接入指南

1. 为什么 OpenClaw 本地部署总卡在环境变量这一步OpenClaw原 Clawdbot是一个可以在本地跑起来的 AI 网关与 Agent 框架它能对接 OpenAI 兼容接口、本地 Ollama 模型也能通过统一 Key 接入第三方模型服务。适合想在自己电脑上搭一套可控 AI 助手的开发者尤其是需要长期跑 coding agent、又不想把密钥散落在各个项目里的人。但真正动手部署时很多人第一步就卡住了明明在终端里export了密钥重启终端就没了Windows 上照着 Linux 教程敲命令PowerShell 直接报错macOS 换了 zsh 之后.bash_profile根本不加载。这些问题的根源都指向同一件事——环境变量在不同操作系统下的持久化机制完全不同。OpenClaw 启动时会按固定顺序读取配置系统环境变量 → 自定义配置文件 → 命令行参数。密钥、网关端口、模型地址这些敏感信息官方推荐放在环境变量里而不是硬编码进代码。所以配置环境变量不是可选项而是部署流程里绕不开的一环。这篇就按 Windows、macOS、Linux 三个系统把可复制的命令、config.toml 骨架、以及通过 TaoToken 统一 Key 接入的验证步骤一次讲清楚。你跟着敲完应该能直接跑通连通性测试。2. TaoToken 前置准备拿到统一 Key 和接入地址在配置 OpenClaw 之前先把模型侧的接入信息准备好。TaoToken 提供 OpenAI 兼容的 API 接口一个 Key 可以调用多种模型省去在 OpenClaw 里维护多套密钥的麻烦。你需要准备两样东西API Key登录后在控制台创建格式类似sk-开头的一串字符。Base URLhttps://taotoken.net/api注意这个地址不带任何查询参数直接作为 OpenAI 兼容端点使用。创建 Key 的入口在控制台的 API Keys 页面建议给 OpenClaw 单独建一个 Key方便后续按项目排查用量。如果你还没决定用哪个模型可以先在模型对话页面测一下响应确认账号和额度正常再回到本地配置。注意Key 只在创建时完整显示一次复制后先存到密码管理器里别直接贴在聊天记录或代码仓库。拿到 Key 之后OpenClaw 侧需要配置的核心变量其实就三个OPENAI_API_KEY、OPENAI_BASE_URL以及可选的网关端口CLAWDBOT_GATEWAY_PORT。下面分系统来配。3. 三系统环境变量配置可复制命令与 config.toml 骨架3.1 macOS / Linux先确认 shell 类型再写配置文件macOS 从 Catalina 起默认 shell 是 zshLinux 服务器多数还是 bash。写错文件是新手最常见的坑所以第一步先确认echo $SHELL输出/bin/zsh就编辑~/.zshrc输出/bin/bash就编辑~/.bashrc登录式 shell 用~/.bash_profile。以 zsh 为例vim ~/.zshrc在文件末尾追加以下内容把 Key 换成你自己的# OpenClaw 接入 TaoToken export OPENAI_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/api # OpenClaw 网关端口 export CLAWDBOT_GATEWAY_PORT18789 # 可选本地 Ollama 模型 export OLLAMA_BASE_URLhttp://localhost:11434保存后立即生效不用重启终端source ~/.zshrc echo $OPENAI_API_KEY能打印出你的 Key 就说明持久化成功。这里有个细节source只影响当前终端新开的终端会自动读取.zshrc所以两边都要验证一下。3.2 Windows图形界面和 PowerShell 两种方式Windows 新手推荐图形界面路径是「此电脑」右键 →「属性」→「高级系统设置」→「环境变量」。在「用户变量」里新建变量名变量值OPENAI_API_KEYsk-你的TaoToken密钥OPENAI_BASE_URLhttps://taotoken.net/apiCLAWDBOT_GATEWAY_PORT18789点确定保存后必须重启终端或 PowerShell才会生效这是 Windows 和 Unix 系最大的区别。如果你习惯命令行用 PowerShell 设置用户级变量[Environment]::SetEnvironmentVariable( OPENAI_API_KEY, sk-你的TaoToken密钥, User ) [Environment]::SetEnvironmentVariable( OPENAI_BASE_URL, https://taotoken.net/api, User )验证时新开一个 PowerShell 窗口echo $env:OPENAI_API_KEY注意 Windows 里读环境变量是$env:变量名不是$变量名直接照抄 Linux 命令会得到空输出。3.3 临时配置只用于快速测试不想动系统配置时可以只在当前会话里设置。macOS / Linuxexport OPENAI_API_KEYsk-临时密钥 export OPENAI_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:OPENAI_API_KEYsk-临时密钥 $env:OPENAI_BASE_URLhttps://taotoken.net/api关掉终端就失效适合验证 Key 是否可用不适合长期部署。3.4 config.toml 骨架不想改系统变量的替代方案OpenClaw 也支持从配置文件读取路径在 macOS / Linux 是~/.clawdbot/clawdbot.jsonWindows 是C:\Users\你的用户名\.clawdbot\clawdbot.json。如果你更习惯 TOML 风格可以建一个config.toml骨架[env] OPENAI_API_KEY sk-你的TaoToken密钥 OPENAI_BASE_URL https://taotoken.net/api OLLAMA_BASE_URL http://localhost:11434 [gateway] port 18789对应的 JSON 版本{ env: { OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }, gateway: { port: 18789 } }改完配置文件后重启网关clawdbot gateway restart注意配置文件里明文写 Key 有泄露风险务必把~/.clawdbot/加进.gitignore别提交到仓库。4. 验证请求确认 OpenClaw 真的连上了 TaoToken配置写完不代表生效得实际发一次请求。OpenClaw 自带诊断命令clawdbot doctor clawdbot env listdoctor会检查依赖、端口、配置完整性env list会列出当前加载的环境变量。如果输出里能看到OPENAI_API_KEY和OPENAI_BASE_URL且没有红色报错说明配置被正确读取。接着做一次真实的模型调用测试。用 curl 直接打 TaoToken 的兼容端点确认 Key 和网络都通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }Windows PowerShell 里把$OPENAI_API_KEY换成$env:OPENAI_API_KEY。返回 JSON 里带choices字段就说明链路通了。最后通过 OpenClaw 网关发一条消息验证框架层也正常clawdbot chat 你好测试一下连接如果这一步能返回模型回复说明环境变量、Base URL、网关端口三者全部对齐部署完成。想进一步确认模型行为可以到模型对话页面用同一个 Key 对比输出排查是框架问题还是模型侧问题。5. 本篇常见错排查配置不生效的六个原因症状一echo $OPENAI_API_KEY输出为空。最常见的是改了.bash_profile但当前用的是 zsh。回到 3.1 节重新确认$SHELL改对文件再source。症状二Windows 设置完变量新终端还是读不到。图形界面保存后没重启终端或者变量建在了「系统变量」但当前用户无权限读取。先试用户变量重启 PowerShell 再验证。症状三clawdbot doctor报端口占用。18789 被其他进程占了改CLAWDBOT_GATEWAY_PORT为其他值比如 18790然后重启网关。症状四curl 返回 401。Key 复制时带了空格或换行或者用了已删除的 Key。重新在控制台生成一个注意只复制sk-到末尾的完整字符串。症状五curl 返回 404。Base URL 写成了https://taotoken.net/api/v1而 OpenClaw 内部会再拼/v1导致路径重复。环境变量里只填https://taotoken.net/api。症状六配置文件和环境变量冲突。两处都配了 Key 但值不同OpenClaw 按「系统环境变量 配置文件 命令行」的优先级取值容易误判。排查时先clawdbot env list看实际生效的是哪个。如果排查完还是连不上建议直接看接入文档里的错误码对照表比逐条猜快得多。长期跑 coding agent 的话可以考虑 Coding Plan省去每次手动配 Key 的重复劳动。6. 配好之后让 OpenClaw 稳定跑起来环境变量配通只是第一步。实际长期使用时我建议把 Key 按用途拆开一个给 OpenClaw 网关一个给临时脚本这样某天额度异常时能快速定位是哪个环节在消耗。另外两个实用习惯一是把~/.clawdbot/整个目录纳入备份但排除密钥文件迁移机器时只带配置骨架二是每次升级 OpenClaw 后重跑一次clawdbot doctor版本更新偶尔会改环境变量名早发现早改。如果你打算把 OpenClaw 接到 CI 或远程开发机上环境变量就别写死在 shell 配置里改用启动脚本注入避免密钥跟着镜像一起被打包。走到这一步本地部署的连通性基本就稳了剩下的就是按你的场景挑模型、调参数。