1. OpenClaw 安装前先把这几件事想清楚OpenClaw 是一个可以跑在本地的 AI 智能体运行框架它能对接聊天平台、调用大模型、加载技能插件适合想把 AI 助手私有化部署、又不想被单一云平台绑死的开发者。它的安装方式主要有两条路一条是 nodejs/npm 全局安装适合快速体验和日常开发另一条是 docker 部署适合长期运行、环境隔离和迁移。两条路最终都会落到同一个配置文件 config.toml 上而模型接入点则统一走 TaoToken 的 Key这样无论你后面换模型还是换部署方式配置骨架都不用大改。我试过在 Windows 和 Linux 上分别跑一遍踩过的坑集中在三处Node.js 版本不够、npm 镜像源指向了过期地址、以及自定义模型时上下文窗口没改导致启动报错。这篇就把从环境准备到连通性验证的完整流程拆开讲每一步都给可复制的命令和配置你照着做基本能一次跑通。先明确适用人群有基础命令行操作经验、想本地跑 AI Agent、需要统一管理多个模型 Key 的开发者。如果你只是想点开网页聊两句那不用装 OpenClaw直接用模型对话就行但如果你要做长期编码助手、接聊天平台、跑自动化任务那这套环境值得花半小时搭起来。2. 环境准备nodejs 与 npm 的版本底线OpenClaw 对 Node.js 版本有硬性要求官方建议 22。低于这个版本安装阶段可能不报错但运行时会因为缺少新的 API 而崩溃。所以第一步永远是查版本node -v npm -v如果 node 版本低于 22去 Node.js 官网下载 LTS 版本覆盖安装或者用 nvm 切换nvm install 22 nvm use 22npm 一般随 Node.js 一起装好不用单独处理。但国内网络环境下npm 默认源可能很慢很多人会配三方镜像。这里有个细节如果你之前配过三方镜像安装 OpenClaw 时可能拉到旧版本或直接 404这时候临时指定官方源最稳妥npm i -g openclaw --registryhttps://registry.npmjs.org/这条命令的意思是全局安装 openclaw并且这一次安装强制走官方 registry不读你本地的 .npmrc 配置。装完之后验证openclaw --version能打印出版本号说明 npm 这条路通了。Windows 用户如果不想手动装 Node.js也可以用 PowerShell 一行脚本iwr -useb https://openclaw.ai/install.ps1 | iex这个脚本会自动检测环境并安装依赖适合不想折腾版本管理的新手。不过企业内网或受限网络下脚本可能拉不到资源那就回到手动装 Node.js 的路线。3. TaoToken 前置统一 Key 接入点怎么拿OpenClaw 本身不带模型能力它需要你提供一个模型接入点。TaoToken 在这里扮演的角色是统一网关你只需要一个 Key就能在 OpenClaw 里切换不同模型不用为每个模型单独配一套地址和密钥。对本地部署来说这能省掉大量配置文件来回改的麻烦。获取 Key 的入口在控制台注册登录后进 API Keys 页面创建即可。地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite创建时注意两点一是 Key 只显示一次复制后立刻存到安全的地方二是如果你打算长期跑编码类任务可以顺手看一下 Coding Plan 的额度说明避免跑一半额度不够。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite文档里会给出 base_url 的标准写法一般是https://taotoken.net/api这种形式不带多余路径。这个地址后面要填进 config.toml所以先记下来。如果你只是想先验证模型能不能通可以先用模型对话页面发一条消息确认 Key 有效再往下走https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite这一步不是必须的但能帮你把「Key 无效」和「OpenClaw 配置错」两类问题提前分开排障时省时间。4. 可复制配置config.toml 骨架与 docker 部署OpenClaw 的配置文件默认在~/.openclaw/config.tomldocker 部署时对应容器内的/root/.openclaw/config.toml。下面这份骨架可以直接复制把your_taotoken_key换成你刚创建的 Key 即可[model] provider custom base_url https://taotoken.net/api api_key your_taotoken_key model_name your_model_name context_window 32000 [server] port 3000 host 0.0.0.0 [log] level info几个参数说明一下。provider选 custom 表示自定义接入点这样 OpenClaw 不会去猜你的服务商类型。context_window必须大于 16000否则启动时会报model context window too small (4096 tokens). Minimum is 16000这是新手最容易卡住的地方。model_name填你在 TaoToken 控制台看到的模型标识不确定就先用文档里的示例模型名。docker 部署的话先拉镜像docker pull openclaw/openclaw:latest然后准备一个环境变量文件~/.openclaw/.env内容至少包含 KeyTAOTOKEN_API_KEYyour_taotoken_key启动容器docker run -d --name openclaw -p 3000:3000 \ -v ~/.openclaw:/root/.openclaw \ --env-file ~/.openclaw/.env \ openclaw/openclaw:latest这里-v把宿主机的配置目录挂进容器这样你改 config.toml 不用进容器。-p 3000:3000把服务端口暴露出来后面验证连通性要用。如果你在 Windows 上跑 docker路径写法改成%USERPROFILE%\.openclaw对应的形式或者用 docker desktop 的挂载界面选目录。离线安装适合内网环境思路是克隆仓库后本地构建git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm run build pnpm run openclaw onboard这条路线依赖 pnpm构建时间较长但完全不依赖外部 registry适合网络受限的场景。5. 验证请求doctor 检查与首次对话配置写完后先跑诊断命令openclaw doctor它会依次检查 Node.js 版本、依赖完整性、配置文件语法和网络连通性。输出里每一项前面有状态标记如果网络那一项失败多半是 base_url 写错或 Key 无效。这一步能把大部分低级错误拦下来。接着启动服务openclaw start或者 docker 方式下直接看容器日志docker logs -f openclaw日志里出现监听 3000 端口的提示说明服务起来了。然后用 curl 发一条测试请求curl -X POST http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -d {model:your_model_name,messages:[{role:user,content:你好}]}如果返回里有正常的回复内容说明从 OpenClaw 到 TaoToken 再到模型的整条链路通了。这一步成功之后你就可以接聊天平台或加载技能插件了。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否多了斜杠或路径返回超时检查本机网络是否能访问外网。6. 本篇常见错排查报错model context window too small (4096 tokens). Minimum is 16000是最常见的原因就是 config.toml 里没写 context_window 或者写得太小。解决办法是在[model]段加上context_window 32000然后重启服务。这个值不要设得比模型实际支持的上限还大否则请求会被模型侧拒绝。第二个常见问题是 npm 安装卡住或报错。如果你之前配过三方镜像先临时指定官方源重装一遍命令在前面给过了。如果还是慢检查本机 DNS 和网络出口不要用来源不明的镜像地址。第三个是 docker 挂载后配置不生效。多半是宿主机目录权限问题容器内进程读不到 config.toml。可以进容器确认文件是否存在docker exec -it openclaw cat /root/.openclaw/config.toml如果文件不存在说明挂载路径写错了检查-v参数两边的路径。第四个是端口冲突。3000 端口被占用时容器起不来或服务启动失败。改-p左边的宿主机端口即可比如-p 3001:3000然后访问 3001。7. 跑通之后Key 和文档放哪环境跑通只是第一步后面你大概率会碰到换模型、加技能、接聊天平台这些需求。这时候统一 Key 接入点的优势就体现出来了你只需要在 TaoToken 控制台管理 Key 和额度OpenClaw 这边改一下 model_name 就能切换不用动 base_url。长期跑编码或 Agent 任务的话建议看一下 Coding Plan 的额度方案避免频繁手动充值https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite接入过程中遇到配置问题优先翻接入文档里面有针对 OpenClaw 这类自定义接入点的参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite需要新建或轮换 Key 的时候回控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite最后提醒一句config.toml 里的 Key 是明文存储的别把这个文件提交到公开仓库。docker 部署时用--env-file把 Key 放在环境变量里比直接写进 toml 更安全一些。跑通之后先别急着加一堆技能把基础对话验证稳定了再逐步往上叠功能这样出问题也好定位。
OpenClaw入门——OpenClaw安装：从nodejs/npm到docker的TaoToken配置骨架
1. OpenClaw 安装前先把这几件事想清楚OpenClaw 是一个可以跑在本地的 AI 智能体运行框架它能对接聊天平台、调用大模型、加载技能插件适合想把 AI 助手私有化部署、又不想被单一云平台绑死的开发者。它的安装方式主要有两条路一条是 nodejs/npm 全局安装适合快速体验和日常开发另一条是 docker 部署适合长期运行、环境隔离和迁移。两条路最终都会落到同一个配置文件 config.toml 上而模型接入点则统一走 TaoToken 的 Key这样无论你后面换模型还是换部署方式配置骨架都不用大改。我试过在 Windows 和 Linux 上分别跑一遍踩过的坑集中在三处Node.js 版本不够、npm 镜像源指向了过期地址、以及自定义模型时上下文窗口没改导致启动报错。这篇就把从环境准备到连通性验证的完整流程拆开讲每一步都给可复制的命令和配置你照着做基本能一次跑通。先明确适用人群有基础命令行操作经验、想本地跑 AI Agent、需要统一管理多个模型 Key 的开发者。如果你只是想点开网页聊两句那不用装 OpenClaw直接用模型对话就行但如果你要做长期编码助手、接聊天平台、跑自动化任务那这套环境值得花半小时搭起来。2. 环境准备nodejs 与 npm 的版本底线OpenClaw 对 Node.js 版本有硬性要求官方建议 22。低于这个版本安装阶段可能不报错但运行时会因为缺少新的 API 而崩溃。所以第一步永远是查版本node -v npm -v如果 node 版本低于 22去 Node.js 官网下载 LTS 版本覆盖安装或者用 nvm 切换nvm install 22 nvm use 22npm 一般随 Node.js 一起装好不用单独处理。但国内网络环境下npm 默认源可能很慢很多人会配三方镜像。这里有个细节如果你之前配过三方镜像安装 OpenClaw 时可能拉到旧版本或直接 404这时候临时指定官方源最稳妥npm i -g openclaw --registryhttps://registry.npmjs.org/这条命令的意思是全局安装 openclaw并且这一次安装强制走官方 registry不读你本地的 .npmrc 配置。装完之后验证openclaw --version能打印出版本号说明 npm 这条路通了。Windows 用户如果不想手动装 Node.js也可以用 PowerShell 一行脚本iwr -useb https://openclaw.ai/install.ps1 | iex这个脚本会自动检测环境并安装依赖适合不想折腾版本管理的新手。不过企业内网或受限网络下脚本可能拉不到资源那就回到手动装 Node.js 的路线。3. TaoToken 前置统一 Key 接入点怎么拿OpenClaw 本身不带模型能力它需要你提供一个模型接入点。TaoToken 在这里扮演的角色是统一网关你只需要一个 Key就能在 OpenClaw 里切换不同模型不用为每个模型单独配一套地址和密钥。对本地部署来说这能省掉大量配置文件来回改的麻烦。获取 Key 的入口在控制台注册登录后进 API Keys 页面创建即可。地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite创建时注意两点一是 Key 只显示一次复制后立刻存到安全的地方二是如果你打算长期跑编码类任务可以顺手看一下 Coding Plan 的额度说明避免跑一半额度不够。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite文档里会给出 base_url 的标准写法一般是https://taotoken.net/api这种形式不带多余路径。这个地址后面要填进 config.toml所以先记下来。如果你只是想先验证模型能不能通可以先用模型对话页面发一条消息确认 Key 有效再往下走https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite这一步不是必须的但能帮你把「Key 无效」和「OpenClaw 配置错」两类问题提前分开排障时省时间。4. 可复制配置config.toml 骨架与 docker 部署OpenClaw 的配置文件默认在~/.openclaw/config.tomldocker 部署时对应容器内的/root/.openclaw/config.toml。下面这份骨架可以直接复制把your_taotoken_key换成你刚创建的 Key 即可[model] provider custom base_url https://taotoken.net/api api_key your_taotoken_key model_name your_model_name context_window 32000 [server] port 3000 host 0.0.0.0 [log] level info几个参数说明一下。provider选 custom 表示自定义接入点这样 OpenClaw 不会去猜你的服务商类型。context_window必须大于 16000否则启动时会报model context window too small (4096 tokens). Minimum is 16000这是新手最容易卡住的地方。model_name填你在 TaoToken 控制台看到的模型标识不确定就先用文档里的示例模型名。docker 部署的话先拉镜像docker pull openclaw/openclaw:latest然后准备一个环境变量文件~/.openclaw/.env内容至少包含 KeyTAOTOKEN_API_KEYyour_taotoken_key启动容器docker run -d --name openclaw -p 3000:3000 \ -v ~/.openclaw:/root/.openclaw \ --env-file ~/.openclaw/.env \ openclaw/openclaw:latest这里-v把宿主机的配置目录挂进容器这样你改 config.toml 不用进容器。-p 3000:3000把服务端口暴露出来后面验证连通性要用。如果你在 Windows 上跑 docker路径写法改成%USERPROFILE%\.openclaw对应的形式或者用 docker desktop 的挂载界面选目录。离线安装适合内网环境思路是克隆仓库后本地构建git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm run build pnpm run openclaw onboard这条路线依赖 pnpm构建时间较长但完全不依赖外部 registry适合网络受限的场景。5. 验证请求doctor 检查与首次对话配置写完后先跑诊断命令openclaw doctor它会依次检查 Node.js 版本、依赖完整性、配置文件语法和网络连通性。输出里每一项前面有状态标记如果网络那一项失败多半是 base_url 写错或 Key 无效。这一步能把大部分低级错误拦下来。接着启动服务openclaw start或者 docker 方式下直接看容器日志docker logs -f openclaw日志里出现监听 3000 端口的提示说明服务起来了。然后用 curl 发一条测试请求curl -X POST http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -d {model:your_model_name,messages:[{role:user,content:你好}]}如果返回里有正常的回复内容说明从 OpenClaw 到 TaoToken 再到模型的整条链路通了。这一步成功之后你就可以接聊天平台或加载技能插件了。如果返回 401检查 Key 是否复制完整返回 404检查 base_url 是否多了斜杠或路径返回超时检查本机网络是否能访问外网。6. 本篇常见错排查报错model context window too small (4096 tokens). Minimum is 16000是最常见的原因就是 config.toml 里没写 context_window 或者写得太小。解决办法是在[model]段加上context_window 32000然后重启服务。这个值不要设得比模型实际支持的上限还大否则请求会被模型侧拒绝。第二个常见问题是 npm 安装卡住或报错。如果你之前配过三方镜像先临时指定官方源重装一遍命令在前面给过了。如果还是慢检查本机 DNS 和网络出口不要用来源不明的镜像地址。第三个是 docker 挂载后配置不生效。多半是宿主机目录权限问题容器内进程读不到 config.toml。可以进容器确认文件是否存在docker exec -it openclaw cat /root/.openclaw/config.toml如果文件不存在说明挂载路径写错了检查-v参数两边的路径。第四个是端口冲突。3000 端口被占用时容器起不来或服务启动失败。改-p左边的宿主机端口即可比如-p 3001:3000然后访问 3001。7. 跑通之后Key 和文档放哪环境跑通只是第一步后面你大概率会碰到换模型、加技能、接聊天平台这些需求。这时候统一 Key 接入点的优势就体现出来了你只需要在 TaoToken 控制台管理 Key 和额度OpenClaw 这边改一下 model_name 就能切换不用动 base_url。长期跑编码或 Agent 任务的话建议看一下 Coding Plan 的额度方案避免频繁手动充值https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite接入过程中遇到配置问题优先翻接入文档里面有针对 OpenClaw 这类自定义接入点的参数说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite需要新建或轮换 Key 的时候回控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentopenclaw_installutm_campaignrewrite最后提醒一句config.toml 里的 Key 是明文存储的别把这个文件提交到公开仓库。docker 部署时用--env-file把 Key 放在环境变量里比直接写进 toml 更安全一些。跑通之后先别急着加一堆技能把基础对话验证稳定了再逐步往上叠功能这样出问题也好定位。