1. OpenClaw 安装前先把这几个坑想明白OpenClaw曾用名 Clawdbot、Moltbot是一个跑在个人电脑上的开源 AI 代理工具核心开发语言是 TypeScript运行依赖 Node.js。它本身不是大模型而是一个“调度层”接收你的指令调用外部大模型和本地工具把文件检索、资料整理、脚本执行这类活儿串起来自动完成。适合谁想在 Windows10/11 或 Ubuntu 上本地部署 AI 代理、又不想被复杂环境折腾的开发者和效率工具爱好者。但我在 Windows 和 Ubuntu 双系统上各装了一遍之后发现真正卡住新手的不是“OpenClaw 怎么用”而是安装阶段的三类问题Node.js 版本不对导致 TypeScript 编译失败、npm 依赖缺失或完整性校验报错、启动时端口占用或配置写错导致服务起不来。这篇教程就围绕这三个高频问题展开给出 Windows10/11 和 Ubuntu 两套可复制的安装流程以及一份能直接用的 config.toml 和 settings.json 骨架最后用 TaoToken 统一 Key 完成接入和连通性验证。先明确环境底线Node.js 建议 v18最低 v16Git 用于拉源码64 位系统预留 300MB 以上空间。大模型 API 这块如果你不想在多个平台之间来回注册、管理一堆 Key可以走 TaoToken 的统一通道后面配置章节会具体写。2. TaoToken 前置统一 Key 与 API 通道准备OpenClaw 启动后必须接入一个大模型才能干活默认配置里会让你填 OpenAI、智谱 GLM 之类的 API Key。问题在于不同模型的 Key 格式、Base URL、计费方式都不一样切换模型时改配置很容易出错。TaoToken 的思路是提供一个统一的 API 通道和 Key你只需要在 OpenClaw 里填一个地址和一个 Key模型切换在服务端完成。你需要提前做两件事。第一注册并拿到 Key。访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进入控制台后创建 API Key。第二记下 API 基础地址https://taotoken.net/api 这个地址在 OpenClaw 的 config.toml 里会用到注意不要多加路径后缀。如果你只是想先验证模型能不能通可以打开模型对话页面直接测试如果你打算长期用 OpenClaw 做编码或 Agent 任务建议了解一下 Coding Plan额度模型更适合高频调用。Key 管理入口在 API Keys 页面接入文档在 doc 页面遇到配置问题优先查文档。注意API Key 属于敏感信息不要写进公开仓库也不要在截图里暴露完整 Key。config.toml 和 settings.json 建议加入 .gitignore。3. 可复制配置Windows10/11 与 Ubuntu 双系统安装3.1 Windows10/11 安装步骤第一步装 Node.js。去官网下载 v18 的 Windows 64 位安装包安装时务必勾选“Add to PATH”这一步决定后面 cmd 里能不能直接识别 node 命令。装完打开 cmd输入node -v npm -v能分别输出版本号如 v18.17.0 和 9.6.7就算成功。如果提示“不是内部或外部命令”重启电脑再试还不行就手动把C:\Program Files\nodejs加进系统变量 Path。第二步装 Git 并拉源码。Git 安装一路默认即可。然后选一个目录存放源码cd D:\ mkdir OpenClaw cd OpenClaw git clone https://github.com/OpenClaw/openclaw.git cd openclaw如果 git clone 卡住直接去 GitHub 页面下载 ZIP 解压到D:\OpenClaw\openclaw也行效果一样。第三步装依赖并编译。这一步是报错重灾区建议先切镜像再装npm config set registry https://registry.npmmirror.com npm install npm run buildnpm install大概 3 到 10 分钟出现 warning 可以忽略只要没有ERR!就行。npm run build成功后目录下会多出一个dist文件夹这是 TypeScript 编译后的产物。第四步启动并验证npm start看到OpenClaw started successfully后浏览器访问http://localhost:3000。3.2 Ubuntu 安装步骤Ubuntu 下命令行更顺但要注意 apt 源里的 Node.js 版本可能偏低。先更新源并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install git python3 python3-pip -yNode.js 建议用 nvm 装 v18避免 apt 版本过旧curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 18 nvm use 18然后拉源码、装依赖、编译mkdir -p ~/OpenClaw cd ~/OpenClaw git clone https://github.com/OpenClaw/openclaw.git cd openclaw npm config set registry https://registry.npmmirror.com npm install npm run build npm start后台运行可以用nohup npm start 停止时用ps aux | grep node找到进程 ID 再kill -9。3.3 config.toml 与 settings.json 骨架OpenClaw 的模型接入配置集中在 config.toml下面这份骨架把 TaoToken 的统一地址和 Key 填进去就能用# config.toml [server] port 3000 host 127.0.0.1 [model] provider openai-compatible base_url https://taotoken.net/api api_key 你的_TaoToken_API_Key default_model gpt-3.5-turbo timeout 60 [agent] max_steps 20 workspace ./workspace对应的 settings.json 用于前端和运行时参数{ model: { baseUrl: https://taotoken.net/api, apiKey: 你的_TaoToken_API_Key, defaultModel: gpt-3.5-turbo }, server: { port: 3000 }, agent: { maxSteps: 20, workspace: ./workspace } }两个文件里的 base_url 和 baseUrl 都指向https://taotoken.net/api不要写成带/v1的路径否则会出现 404。Key 填控制台生成的那一串前后不要有空格。4. 验证请求确认 OpenClaw 真的连上了模型配置写完后先别急着跑复杂任务用一条最小指令验证连通性。启动 OpenClawnpm start浏览器打开http://localhost:3000在输入框里输入请回复OpenClaw 连通性测试成功如果模型正常返回这句话说明 TaoToken 的 Key、Base URL、模型名三者匹配链路是通的。如果返回的是报错先看终端里npm start的输出通常会打印 HTTP 状态码。你也可以绕过 OpenClaw直接用 curl 验证 TaoToken 通道本身是否可用curl https://taotoken.net/api/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的_TaoToken_API_Key \ -d { model: gpt-3.5-turbo, messages: [{role: user, content: ping}] }返回 JSON 里带choices字段就说明通道没问题此时如果 OpenClaw 还报错问题一定在 OpenClaw 的配置或依赖上而不是 Key。这个排查顺序能帮你省很多时间。5. 本篇常见错排查依赖缺失、启动失败、端口占用5.1 Node.js 与 TypeScript 编译类报错报错error TS2307: Cannot find module xxx说明依赖没装全或类型声明缺失。先重新npm install还不行就手动补npm install xxx --save-dev npm install types/xxx --save-dev报错error TS1086: An accessor cannot be declared in an ambient context基本是 TypeScript 版本过高。查 package.json 里指定的版本然后装回对应版本npm install typescript4.9.5 --save-dev npm run build5.2 npm 依赖安装类报错npm ERR! code EINTEGRITY是缓存损坏按顺序执行npm cache clean --force rm -rf node_modules package-lock.json npm installWindows 下删除用rd /s /q node_modules和del package-lock.json。gyp ERR! find Python说明某个依赖需要 Python 编译。Windows 装 Python 3.8 并勾选 Add to PATHUbuntu 执行sudo apt install python3 python3-pip -y然后重新npm install。5.3 启动失败与端口占用Error: listen EADDRINUSE: address already in use :::3000是 3000 端口被占。Windows 下netstat -ano | findstr :3000找到 PID 后在任务管理器结束进程。Ubuntu 下lsof -i:3000 kill -9 进程ID或者直接改 config.toml 里的port 3001重新npm run build再启动。访问localhost:3000提示无法访问先确认终端有没有OpenClaw started successfully。没有就是启动失败往上翻报错。有的话检查防火墙Windows 在“允许应用通过防火墙”里放行 Node.jsUbuntu 执行sudo ufw allow 3000。5.4 模型配置类报错API key is invalid优先检查三处Key 是否复制完整、base_url 是否写成https://taotoken.net/api、模型名是否在 TaoToken 支持的列表里。如果 curl 能通但 OpenClaw 报错多半是 config.toml 和 settings.json 里的地址不一致改完记得重启服务。6. 接入之后把 Key 管好把任务跑顺装好只是开始。日常使用中我建议把 config.toml 里的workspace指向一个独立目录避免 Agent 误操作你的主目录文件。模型切换时只改default_model字段即可base_url 和 Key 不用动这是统一通道最省事的地方。如果你后续要跑长时间编码任务或 Agent 自动化流程可以到 Coding Plan 页面看看额度方案比按次调用更划算。Key 轮换、用量查看都在控制台和 API Keys 页面完成。接入文档里有完整的参数说明和示例遇到本文没覆盖的报错先去 doc 页面搜关键词再对照终端输出定位。最后留一个实用习惯每次改完 config.toml 或 settings.json先跑一遍第 4 节的 curl 验证再启动 OpenClaw。这样能把“通道问题”和“应用问题”分开排障效率至少翻倍。