1. 为什么要在本地跑 OpenClawClawdbot以及它到底能做什么OpenClaw曾用名 Clawdbot是一个可以装在自己电脑上的 AI 智能体框架它和网页版聊天机器人最大的区别在于它能真正动手操作你的本地文件、执行命令、调用浏览器、管理知识库并且把记忆存在本地。你可以把它理解成一个「住在你电脑里的助理」你说一句「帮我把下载文件夹里所有截图按月份归档」它会自己写脚本、执行、汇报结果而不是只回你一段文字。适合谁用三类人最合适一是想用自然语言自动化日常重复操作的人比如整理文件、批量重命名、定时抓取信息二是想研究智能体框架、Skills 插件机制的开发者三是对数据隐私敏感、不希望对话内容全部上传到第三方的人。OpenClaw 的模型调用可以走统一 API 通道本地只负责执行和存储可控性比纯云端方案高不少。这篇教程的目标很明确从零开始在本地把 OpenClaw 装起来跑通第一个任务全程控制在 8 分钟左右。我会用 Node.js 作为运行底座因为 OpenClaw 本身就是 Node 生态的工具装好 Node 之后剩下的基本就是复制命令。整个过程分四块环境准备、安装初始化、Skills 加载、模型接入与验证。模型接入这块我会用 TaoToken 的统一 Key 通道来演示因为它把多家模型的 Base URL 和 Key 格式统一了配置一次就能切换模型省去反复改配置文件的麻烦。先说清楚一个前提OpenClaw 本身不包含模型能力它是个「壳」负责调度和执行真正理解你指令的是背后的大模型。所以安装分两步走先把壳装好再把模型通道接上。很多人卡在第二步报错五花八门后面我会把常见错误一个个拆开讲。环境要求不复杂Node.js 22.x 及以上、一个终端、能正常访问外部网络。Windows 11、macOS 12、主流 Linux 发行版都行。内存建议 2GB 以上本地机器一般都没问题。下面直接进入操作。2. 安装前的环境检查与 Node.js 底座配置这一步是整个流程里最容易被跳过、也最容易出问题的地方。OpenClaw 对 Node.js 版本有硬性要求低于 22.x 会在安装依赖时报错所以先确认版本再动手装。打开你的终端Windows 用 PowerShellmacOS/Linux 用系统终端执行两条检查命令node -v npm -v如果输出类似v22.0.0和10.x.x说明环境可用直接跳到下一节。如果提示command not found或不是内部或外部命令说明 Node.js 还没装按下面的系统对应操作。macOS 用户推荐用 Homebrew 装一条命令搞定/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) brew install nodeLinuxUbuntu/Debian用户sudo apt update sudo apt install -y curl git nodejs npm sudo npm install -g n sudo n stableWindows 11 用户用 winget 最省事以管理员身份打开 PowerShellwinget install OpenJS.NodeJS --version 22.0.0装完之后关掉终端重新打开再跑一次node -v确认版本。这里有个坑Windows 上如果之前装过旧版 Nodewinget 可能不会覆盖建议先去「应用和功能」里卸载旧版本再装。接下来配置 npm 镜像。默认源在国内访问速度不稳定安装 OpenClaw 这种依赖较多的包时容易超时中断换成国内镜像会顺畅很多npm config set registry https://registry.npmmirror.com验证镜像是否生效npm config get registry输出https://registry.npmmirror.com就对了。这一步看似简单但后面 Skills 安装失败、clawhub命令不可用等问题很多都是镜像没配好导致的所以别省。环境检查这块我建议你多花一分钟确认三件事Node 版本 ≥ 22、npm 能正常执行、镜像已切换。这三件事确认完后面的安装基本不会卡。如果你是在公司网络环境下注意有些内网会拦截 npm 请求遇到ETIMEDOUT就换个网络试试。3. 可复制的 OpenClaw 安装与初始化配置环境就绪后正式安装 OpenClaw。全局安装一条命令npm install -g openclaw安装完成后执行初始化向导openclaw onboard向导会依次问你几个问题按下面选择即可同意协议选 yes启动模式选「快速启动」模型配置这一步先跳过我们后面单独配避免这里填错导致启动失败通道channel全部启用。初始化完成后OpenClaw 会在你的用户目录下生成配置文件夹。配置文件路径要记牢后面改模型配置全靠它macOS / Linux~/.openclaw/config.jsonWindowsC:\Users\你的用户名\.openclaw\config.json接下来设置网关监听地址和端口。默认只监听本地如果你想让同一局域网的其他设备也能访问把 host 改成0.0.0.0openclaw config set gateway.host 0.0.0.0 openclaw config set gateway.port 18789然后启动服务openclaw gateway start浏览器打开http://127.0.0.1:18789能看到 Web 控制台就说明壳装好了。如果打不开先别急用openclaw gateway status看服务状态再用openclaw logs看日志具体排查放到第 5 节。现在到了关键一步接入模型通道。OpenClaw 需要一个兼容 OpenAI 格式的 API 端点。我用 TaoToken 来演示因为它把 Base URL 和 Key 统一了配置一次就能用切换模型只改 Model ID 就行。先到 TaoToken 控制台创建一个 API Key地址是https://taotoken.net/api-keys。创建后复制保存注意 Key 只显示一次。然后编辑config.json把 model 段落改成下面这样。这是一个可直接复制的 JSON 片段路径和字段名与 OpenClaw 实际读取的一致{ model: { type: openai, api_key: 你的TaoToken_API_Key, base_url: https://taotoken.net/api, model_name: claude-sonnet-4-20250514, max_tokens: 2048, temperature: 0.7, timeout: 60, reasoning: false } }这里三件套要写全Base URL 填https://taotoken.net/apiKey 填你刚创建的Model ID 填你要用的模型名。三个字段缺一个都会导致调用失败。改完保存重启网关让配置生效openclaw gateway restart如果你更习惯用命令行改配置也可以用openclaw config set model.base_url https://taotoken.net/api这种方式逐项设置效果一样。我个人建议直接编辑 JSON因为字段多的时候命令行容易漏。4. 验证请求与 Skills 技能加载全流程配置改完先验证模型通道是否真的通了。最直接的办法是在 Web 控制台里发一句话比如「你好帮我确认一下当前使用的模型」。如果收到正常回复说明 Base URL、Key、Model ID 三件套都对了。如果回复为空或报错先看第 5 节。命令行验证也可以用 curl 直接打 TaoToken 的接口确认 Key 本身有效curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的TaoToken_API_Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回里有choices字段和内容就说明通道没问题。这一步能把「Key 问题」和「OpenClaw 配置问题」区分开排查时非常有用。模型通了之后装 Skills。Skills 是 OpenClaw 的功能扩展模块搜索、浏览器操作、内容摘要、文件管理都靠它。先装技能管理工具npm install -g clawhub然后按需安装常用技能clawhub install tavily-search clawhub install agent-browser clawhub install summarize clawhub install skill-vetter clawhub install proactive-agent通用格式就是clawhub install 技能名称。装完查看列表openclaw skill list启动或重启某个技能openclaw skill start tavily-search openclaw skill restart summarize查看技能状态openclaw skill status tavily-search所有技能装完后重启网关让它们加载生效openclaw gateway restart到这里一个能跑任务的本地 OpenClaw 就搭好了。你可以试着下第一个指令比如「用搜索技能查一下今天的技术新闻摘要成三条」。如果它能调用 tavily-search 和 summarize 完成说明 Skills 加载正常。5. 本篇常见报错排查对照表这一节按真实报错来遇到问题直接对号入座。401 Unauthorized / invalid api keyKey 错了或没生效。先确认config.json里api_key没有多余空格再确认 Key 没过期。用第 4 节的 curl 单独测一次curl 通但 OpenClaw 不通就是配置文件没保存或没重启网关。local proxy failed / connection refusedBase URL 写错了。检查是不是漏了/api或者写成了带/v1的完整路径。TaoToken 的 Base URL 就是https://taotoken.net/api不要自己加后缀。reading choices 报错 / 返回结构解析失败通常是模型名写错或者接口返回了错误信息但被当成正常响应解析。确认model_name是有效 Model ID然后看openclaw logs里原始返回内容。OAuth 相关报错如果你之前配过其他需要 OAuth 的通道残留配置会冲突。执行openclaw onboard --reset重新初始化再重新填模型配置。openclaw: command not found全局安装没成功或 PATH 没生效。重新执行npm install -g openclaw然后关掉终端重开。Linux/macOS 权限不足时加sudo。clawhub 命令不可用npm install -g clawhub没装成功或者镜像没配好。先npm config set registry https://registry.npmmirror.com再重装。技能安装后不生效忘了重启网关。执行openclaw gateway restart再用openclaw skill list确认技能在列表里。服务启动后自动关闭内存不足。本地关掉占资源的程序服务器建议 2GB 以上。用openclaw logs看具体错误。端口 18789 被占用Linux/macOS 用lsof -i:18789找到进程 ID 后kill -9Windows 用netstat -ano | findstr 18789找到 PID 后taskkill /F /PID 进程ID。AI 回复为空在 model 配置里加reasoning: false重启服务。这个字段对某些模型是必须的。响应超时把timeout从 30 调到 60max_tokens从 2048 降到 1024再检查网络。Windows 执行策略禁止运行脚本以管理员身份运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。无法写入配置文件检查当前用户对.openclaw目录的读写权限必要时openclaw onboard --reset重新初始化。排查的核心思路是分层先确认 Node 和 npm 正常再确认 OpenClaw 服务能起再确认模型通道通最后确认 Skills 加载。每一层用对应命令验证不要跳层猜。6. 把模型通道固定下来长期用更省心装好只是开始真正影响体验的是模型通道稳不稳定。我自己的做法是把 TaoToken 的 Key 固定在一个配置文件里切换模型只改model_name一行Base URL 和 Key 不动。这样不管是日常对话、写代码还是跑 Agent 任务都不用反复折腾配置。如果你主要用来做长期编码或者跑自动化 Agent可以了解一下 Coding Plan它把调用方式做了打包适合高频使用。日常验证模型是否正常直接用模型对话页面发一句话最快。需要管理多个 Key 或者查看用量控制台里都能看到。接入文档里有完整的字段说明遇到配置疑问可以先翻一遍。最后留一个实用习惯每次改完config.json先跑openclaw gateway restart再用openclaw logs --follow盯着日志发一条测试消息。日志里能看到请求发出、模型返回、技能调用的完整链路比盲猜快得多。这套流程跑顺之后8 分钟装完不是口号是真的能复现。
1. 为什么要在本地跑 OpenClawClawdbot以及它到底能做什么OpenClaw曾用名 Clawdbot是一个可以装在自己电脑上的 AI 智能体框架它和网页版聊天机器人最大的区别在于它能真正动手操作你的本地文件、执行命令、调用浏览器、管理知识库并且把记忆存在本地。你可以把它理解成一个「住在你电脑里的助理」你说一句「帮我把下载文件夹里所有截图按月份归档」它会自己写脚本、执行、汇报结果而不是只回你一段文字。适合谁用三类人最合适一是想用自然语言自动化日常重复操作的人比如整理文件、批量重命名、定时抓取信息二是想研究智能体框架、Skills 插件机制的开发者三是对数据隐私敏感、不希望对话内容全部上传到第三方的人。OpenClaw 的模型调用可以走统一 API 通道本地只负责执行和存储可控性比纯云端方案高不少。这篇教程的目标很明确从零开始在本地把 OpenClaw 装起来跑通第一个任务全程控制在 8 分钟左右。我会用 Node.js 作为运行底座因为 OpenClaw 本身就是 Node 生态的工具装好 Node 之后剩下的基本就是复制命令。整个过程分四块环境准备、安装初始化、Skills 加载、模型接入与验证。模型接入这块我会用 TaoToken 的统一 Key 通道来演示因为它把多家模型的 Base URL 和 Key 格式统一了配置一次就能切换模型省去反复改配置文件的麻烦。先说清楚一个前提OpenClaw 本身不包含模型能力它是个「壳」负责调度和执行真正理解你指令的是背后的大模型。所以安装分两步走先把壳装好再把模型通道接上。很多人卡在第二步报错五花八门后面我会把常见错误一个个拆开讲。环境要求不复杂Node.js 22.x 及以上、一个终端、能正常访问外部网络。Windows 11、macOS 12、主流 Linux 发行版都行。内存建议 2GB 以上本地机器一般都没问题。下面直接进入操作。2. 安装前的环境检查与 Node.js 底座配置这一步是整个流程里最容易被跳过、也最容易出问题的地方。OpenClaw 对 Node.js 版本有硬性要求低于 22.x 会在安装依赖时报错所以先确认版本再动手装。打开你的终端Windows 用 PowerShellmacOS/Linux 用系统终端执行两条检查命令node -v npm -v如果输出类似v22.0.0和10.x.x说明环境可用直接跳到下一节。如果提示command not found或不是内部或外部命令说明 Node.js 还没装按下面的系统对应操作。macOS 用户推荐用 Homebrew 装一条命令搞定/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) brew install nodeLinuxUbuntu/Debian用户sudo apt update sudo apt install -y curl git nodejs npm sudo npm install -g n sudo n stableWindows 11 用户用 winget 最省事以管理员身份打开 PowerShellwinget install OpenJS.NodeJS --version 22.0.0装完之后关掉终端重新打开再跑一次node -v确认版本。这里有个坑Windows 上如果之前装过旧版 Nodewinget 可能不会覆盖建议先去「应用和功能」里卸载旧版本再装。接下来配置 npm 镜像。默认源在国内访问速度不稳定安装 OpenClaw 这种依赖较多的包时容易超时中断换成国内镜像会顺畅很多npm config set registry https://registry.npmmirror.com验证镜像是否生效npm config get registry输出https://registry.npmmirror.com就对了。这一步看似简单但后面 Skills 安装失败、clawhub命令不可用等问题很多都是镜像没配好导致的所以别省。环境检查这块我建议你多花一分钟确认三件事Node 版本 ≥ 22、npm 能正常执行、镜像已切换。这三件事确认完后面的安装基本不会卡。如果你是在公司网络环境下注意有些内网会拦截 npm 请求遇到ETIMEDOUT就换个网络试试。3. 可复制的 OpenClaw 安装与初始化配置环境就绪后正式安装 OpenClaw。全局安装一条命令npm install -g openclaw安装完成后执行初始化向导openclaw onboard向导会依次问你几个问题按下面选择即可同意协议选 yes启动模式选「快速启动」模型配置这一步先跳过我们后面单独配避免这里填错导致启动失败通道channel全部启用。初始化完成后OpenClaw 会在你的用户目录下生成配置文件夹。配置文件路径要记牢后面改模型配置全靠它macOS / Linux~/.openclaw/config.jsonWindowsC:\Users\你的用户名\.openclaw\config.json接下来设置网关监听地址和端口。默认只监听本地如果你想让同一局域网的其他设备也能访问把 host 改成0.0.0.0openclaw config set gateway.host 0.0.0.0 openclaw config set gateway.port 18789然后启动服务openclaw gateway start浏览器打开http://127.0.0.1:18789能看到 Web 控制台就说明壳装好了。如果打不开先别急用openclaw gateway status看服务状态再用openclaw logs看日志具体排查放到第 5 节。现在到了关键一步接入模型通道。OpenClaw 需要一个兼容 OpenAI 格式的 API 端点。我用 TaoToken 来演示因为它把 Base URL 和 Key 统一了配置一次就能用切换模型只改 Model ID 就行。先到 TaoToken 控制台创建一个 API Key地址是https://taotoken.net/api-keys。创建后复制保存注意 Key 只显示一次。然后编辑config.json把 model 段落改成下面这样。这是一个可直接复制的 JSON 片段路径和字段名与 OpenClaw 实际读取的一致{ model: { type: openai, api_key: 你的TaoToken_API_Key, base_url: https://taotoken.net/api, model_name: claude-sonnet-4-20250514, max_tokens: 2048, temperature: 0.7, timeout: 60, reasoning: false } }这里三件套要写全Base URL 填https://taotoken.net/apiKey 填你刚创建的Model ID 填你要用的模型名。三个字段缺一个都会导致调用失败。改完保存重启网关让配置生效openclaw gateway restart如果你更习惯用命令行改配置也可以用openclaw config set model.base_url https://taotoken.net/api这种方式逐项设置效果一样。我个人建议直接编辑 JSON因为字段多的时候命令行容易漏。4. 验证请求与 Skills 技能加载全流程配置改完先验证模型通道是否真的通了。最直接的办法是在 Web 控制台里发一句话比如「你好帮我确认一下当前使用的模型」。如果收到正常回复说明 Base URL、Key、Model ID 三件套都对了。如果回复为空或报错先看第 5 节。命令行验证也可以用 curl 直接打 TaoToken 的接口确认 Key 本身有效curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的TaoToken_API_Key \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}] }返回里有choices字段和内容就说明通道没问题。这一步能把「Key 问题」和「OpenClaw 配置问题」区分开排查时非常有用。模型通了之后装 Skills。Skills 是 OpenClaw 的功能扩展模块搜索、浏览器操作、内容摘要、文件管理都靠它。先装技能管理工具npm install -g clawhub然后按需安装常用技能clawhub install tavily-search clawhub install agent-browser clawhub install summarize clawhub install skill-vetter clawhub install proactive-agent通用格式就是clawhub install 技能名称。装完查看列表openclaw skill list启动或重启某个技能openclaw skill start tavily-search openclaw skill restart summarize查看技能状态openclaw skill status tavily-search所有技能装完后重启网关让它们加载生效openclaw gateway restart到这里一个能跑任务的本地 OpenClaw 就搭好了。你可以试着下第一个指令比如「用搜索技能查一下今天的技术新闻摘要成三条」。如果它能调用 tavily-search 和 summarize 完成说明 Skills 加载正常。5. 本篇常见报错排查对照表这一节按真实报错来遇到问题直接对号入座。401 Unauthorized / invalid api keyKey 错了或没生效。先确认config.json里api_key没有多余空格再确认 Key 没过期。用第 4 节的 curl 单独测一次curl 通但 OpenClaw 不通就是配置文件没保存或没重启网关。local proxy failed / connection refusedBase URL 写错了。检查是不是漏了/api或者写成了带/v1的完整路径。TaoToken 的 Base URL 就是https://taotoken.net/api不要自己加后缀。reading choices 报错 / 返回结构解析失败通常是模型名写错或者接口返回了错误信息但被当成正常响应解析。确认model_name是有效 Model ID然后看openclaw logs里原始返回内容。OAuth 相关报错如果你之前配过其他需要 OAuth 的通道残留配置会冲突。执行openclaw onboard --reset重新初始化再重新填模型配置。openclaw: command not found全局安装没成功或 PATH 没生效。重新执行npm install -g openclaw然后关掉终端重开。Linux/macOS 权限不足时加sudo。clawhub 命令不可用npm install -g clawhub没装成功或者镜像没配好。先npm config set registry https://registry.npmmirror.com再重装。技能安装后不生效忘了重启网关。执行openclaw gateway restart再用openclaw skill list确认技能在列表里。服务启动后自动关闭内存不足。本地关掉占资源的程序服务器建议 2GB 以上。用openclaw logs看具体错误。端口 18789 被占用Linux/macOS 用lsof -i:18789找到进程 ID 后kill -9Windows 用netstat -ano | findstr 18789找到 PID 后taskkill /F /PID 进程ID。AI 回复为空在 model 配置里加reasoning: false重启服务。这个字段对某些模型是必须的。响应超时把timeout从 30 调到 60max_tokens从 2048 降到 1024再检查网络。Windows 执行策略禁止运行脚本以管理员身份运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。无法写入配置文件检查当前用户对.openclaw目录的读写权限必要时openclaw onboard --reset重新初始化。排查的核心思路是分层先确认 Node 和 npm 正常再确认 OpenClaw 服务能起再确认模型通道通最后确认 Skills 加载。每一层用对应命令验证不要跳层猜。6. 把模型通道固定下来长期用更省心装好只是开始真正影响体验的是模型通道稳不稳定。我自己的做法是把 TaoToken 的 Key 固定在一个配置文件里切换模型只改model_name一行Base URL 和 Key 不动。这样不管是日常对话、写代码还是跑 Agent 任务都不用反复折腾配置。如果你主要用来做长期编码或者跑自动化 Agent可以了解一下 Coding Plan它把调用方式做了打包适合高频使用。日常验证模型是否正常直接用模型对话页面发一句话最快。需要管理多个 Key 或者查看用量控制台里都能看到。接入文档里有完整的字段说明遇到配置疑问可以先翻一遍。最后留一个实用习惯每次改完config.json先跑openclaw gateway restart再用openclaw logs --follow盯着日志发一条测试消息。日志里能看到请求发出、模型返回、技能调用的完整链路比盲猜快得多。这套流程跑顺之后8 分钟装完不是口号是真的能复现。
