1. 为什么要在本地跑 OpenClaw以及它到底解决什么问题OpenClaw 是一个能在本地操控电脑、读写文件、模拟键鼠、调用浏览器完成自动化任务的智能体框架。你可以把它理解成一个“住在你电脑里的执行助手”你说一句“把下载文件夹按类型整理好”它会自己拆解步骤、调用工具、动手完成。它适合三类人一是想让 AI 直接操作本地文件系统的开发者二是需要批量处理重复桌面任务的效率党三是想把大模型能力接进自己工作流、又不想把数据全丢到云端的折腾派。但真正上手时卡人的往往不是 OpenClaw 本身而是两件事第一Windows / macOS / Linux 三套系统的依赖环境各不相同Node.js、Python、Git 版本对不上就起不来第二模型 API 通道要单独配每个模型一个 Key、一个 Base URL配置文件写错一个字段Gateway 就一直显示离线。这篇教程就围绕这两个痛点展开先把 OpenClaw 在三套系统上装起来再用 TaoToken 的统一 Key 把settings.json和config.toml两个骨架配置一次性写对最后逐条验证 API 连通性。我试过把同一份配置在 Windows 11、macOS 14 和 Ubuntu 22.04 上各跑一遍踩过的坑集中在路径含中文、环境变量没刷新、以及配置文件里 Base URL 多写了斜杠这三处。下面按“先装环境、再配 Key、后验证”的顺序来每一步都给可复制的命令和配置片段。2. 前置准备TaoToken 统一 Key 与 API 通道OpenClaw 本身不带模型能力它需要外接一个兼容 OpenAI 协议的 API 通道。TaoToken 的作用就是把这层通道统一起来你只需要一个 Key、一个 Base URL就能在 OpenClaw 里切换不同模型不用为每个模型单独维护一套凭证。对本地部署来说这能省掉大量“换模型就改配置”的重复劳动。先拿到凭证。访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完 Key 后去 API Keys 页面复制完整字符串它通常以固定前缀开头只显示一次务必先存到本地密码管理器。API 通道的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接填这一串即可。如果你后面要接 Claude Code 这类工具对应的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的字段对照表。注意Key 属于敏感凭证不要写进会提交到 Git 的配置文件里。推荐用系统环境变量注入配置文件里只引用变量名。环境变量在三套系统上的设置方式不同先按你的系统执行# macOS / Linux写入 ~/.zshrc 或 ~/.bashrc 后 source 生效 export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api# Windows PowerShell当前会话生效永久生效需用 setx $env:TAOTOKEN_API_KEY你的Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api设置完用echo $TAOTOKEN_API_KEYWindows 用echo $env:TAOTOKEN_API_KEY确认能打印出值打印为空说明没生效先解决这一步再往下走。3. 全系统安装 OpenClawWindows / macOS / Linux 逐条命令OpenClaw 的运行依赖三样东西Node.js 18 以上、Python 3.10 以上、Git。三套系统的安装方式如下装完都要验证版本。3.1 Windows 11 安装步骤Windows 推荐用 winget 装依赖避免手动下载安装包。以管理员身份打开 PowerShellwinget install OpenJS.NodeJS.LTS winget install Python.Python.3.12 winget install Git.Git装完关闭并重开 PowerShell让 PATH 刷新然后验证node -v python --version git --version三个命令都能输出版本号后克隆 OpenClaw 并安装依赖。安装路径必须是纯英文不能有中文、空格或特殊符号推荐D:\OpenClawcd D:\ git clone https://github.com/openclaw/openclaw.git OpenClaw cd OpenClaw npm install -g pnpm pnpm install如果pnpm install卡在某个包上多半是网络问题可以换用 npm 镜像重试。安装完成后先别急着启动配置还没写。3.2 macOS 安装步骤macOS 用 Homebrew 最省事。先确认已装 Homebrew没有的话按官网命令装。然后brew install node20 brew install python3.12 brew install gitApple Silicon 机器注意 node 路径验证node -v python3 --version git --version克隆并安装cd ~/Projects git clone https://github.com/openclaw/openclaw.git OpenClaw cd OpenClaw npm install -g pnpm pnpm installmacOS 上如果遇到权限报错不要用sudo pnpm install而是检查目录归属用chown把项目目录改回当前用户。3.3 LinuxUbuntu 22.04安装步骤Ubuntu 用 apt 装基础依赖Node.js 建议用 NodeSource 源装 20.xsudo apt update sudo apt install -y python3.12 python3-pip git curl curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs验证并安装node -v python3 --version git --version git clone https://github.com/openclaw/openclaw.git ~/OpenClaw cd ~/OpenClaw sudo npm install -g pnpm pnpm installLinux 上如果 OpenClaw 需要模拟键鼠还要装 X11 相关库sudo apt install -y libx11-dev libxtst-dev。无头服务器上跑键鼠模拟意义不大建议在带桌面的环境里用。三套系统装完后项目根目录下应该能看到package.json和config文件夹。接下来写配置。4. 可复制配置settings.json 与 config.toml 骨架OpenClaw 的配置分两层settings.json管运行时行为config.toml管模型通道和 Gateway。两个文件都在项目根目录的config文件夹下没有就手动创建。4.1 settings.json 骨架这个文件控制日志级别、工作目录、是否启用键鼠模拟等。把下面的内容复制进去路径按你的系统改{ gateway: { host: 127.0.0.1, port: 8765, autoStart: true }, workspace: { root: D:/OpenClaw/workspace, allowFileWrite: true, allowShell: true }, automation: { enableKeyboard: true, enableMouse: true, enableBrowser: true }, logging: { level: info, file: D:/OpenClaw/logs/openclaw.log } }macOS / Linux 用户把root和file改成/Users/你的用户名/OpenClaw/workspace和对应日志路径。注意 JSON 里路径用正斜杠/反斜杠要转义容易写错。4.2 config.toml 骨架这个文件是模型通道的核心TaoToken 的统一 Key 就配在这里[provider.taotoken] name TaoToken base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} protocol openai [model.default] provider taotoken model gpt-4o-mini temperature 0.7 max_tokens 4096 [model.fast] provider taotoken model gpt-4o-mini temperature 0.3 [gateway] config_path ./config/settings.json关键点有三个base_url只写到/api不要在后面加/v1或斜杠api_key用${TAOTOKEN_API_KEY}引用环境变量不要硬编码protocol保持openaiTaoToken 的通道兼容这套协议。注意如果你在 Windows 上用的是 PowerShell 设置的环境变量OpenClaw 启动时可能读不到建议改用系统“环境变量”面板设置用户级变量然后重启终端。配置写完后检查两个文件的语法。JSON 可以用node -e require(./config/settings.json)验证TOML 用python3 -c import tomllib; tomllib.load(open(config/config.toml,rb))验证。语法错了启动必失败。5. 启动与验证确认 Gateway 在线、API 连通配置就绪后启动 OpenClaw。在项目根目录执行pnpm start第一次启动会初始化服务等待 1 到 3 分钟界面右上角出现“Gateway 在线”才算成功。如果一直显示离线先看日志文件最后 20 行tail -n 20 logs/openclaw.log日志里如果出现401 Unauthorized说明 Key 没读到或无效出现ECONNREFUSED说明 Base URL 写错或网络不通。Gateway 在线后单独验证 API 通道是否真的通。用 curl 直接打一次对话接口curl -X POST https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复 OK 两个字母}] }返回 JSON 里choices[0].message.content有内容说明 Key 和通道都正常。这一步通了OpenClaw 里再发指令就不会因为通道问题失败。接着在 OpenClaw 界面底部输入框发一条测试指令比如“列出当前工作目录下的文件”。如果它能返回文件列表说明 Gateway、模型通道、工具调用三层全部打通。想更直观地验证模型对话效果可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 单独测一轮确认返回质量符合预期。如果你打算长期用 OpenClaw 做编码或 Agent 任务建议了解一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它在长任务场景下的额度策略更划算。6. 本篇常见报错排查Gateway 一直离线九成是配置路径问题。检查settings.json里workspace.root是否为纯英文路径含中文或空格会导致服务起不来。其次检查config.toml的base_url是否多写了/v1正确写法就是https://taotoken.net/api。401 或 Key 无效先确认环境变量在当前终端能打印出来。Windows 上用setx设置的变量需要重开终端才生效。如果 Key 复制时带了空格也会导致鉴权失败重新复制一次。pnpm install 报错找不到 PythonOpenClaw 的部分依赖需要编译找不到 Python 会失败。确认python3 --version能输出且 Python 在 PATH 里。Windows 上如果装了多个 Python 版本用py -3.12指定。启动后界面无输入框或无法发送通常是 Gateway 还没初始化完。等右上角显示在线后再操作。如果一直不出现删掉logs目录下的缓存日志重启一次。键鼠模拟不生效Linux 上缺 X11 库按第 3.3 节补装。macOS 上需要在“系统设置 → 隐私与安全性 → 辅助功能”里给终端授权否则模拟操作会被系统拦截。换模型后报 model not foundconfig.toml里model字段的值要和 TaoToken 支持的模型名一致写错一个字符就会报这个错。改完配置要重启 OpenClaw热加载不一定生效。排查顺序建议固定为先看日志、再验环境变量、最后验 curl 通道。这三步能覆盖绝大多数启动和连通性问题。配置文件和 Key 的管理入口统一在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 需要新建或轮换 Key 时去那里操作。