1. 龙虾 OpenClaw 到底是个什么东西如果你第一次听到「龙虾 OpenClaw」大概率会以为是个爬虫工具或者某个游戏外挂。其实它是一个本地优先、强调执行力的开源 AI 智能体框架。用一句人话概括它给大模型装上了手和脚让 AI 不只是陪你聊天而是真的能操作你的电脑、读写文件、调用工具、跑脚本。它的架构是三层解耦的云端大脑Orchestrator负责理解你的自然语言指令并做任务拆解协议桥Gateway负责鉴权、流量管理把通用指令翻译成本地能听懂的操作指令本地执行端Pi-embedded真正干活在沙箱里动态加载并执行 Skill 脚本。这个设计的好处是分工明确云端负责思考本地负责执行安全边界清晰。适合谁来用三类人最合适一是想让 AI 帮自己处理重复性桌面操作的开发者二是想研究智能体框架内部机制的技术爱好者三是需要把大模型能力接入自己工作流、又不想把敏感数据全丢到云端的团队。它支持飞书、Telegram、Web UI 等多种交互渠道你可以按自己的习惯选入口。安装 OpenClaw 的核心门槛其实不在它本身而在两件事Node.js 环境要装对版本以及 Gateway 要正确接入一个可用的大模型 API 通道。这篇就按「从零到跑通」的顺序把 Node.js 版本要求、clawhub 安装命令、Gateway 配置骨架、启动验证和常见报错全部走一遍。2. 前置准备Node.js 版本与 TaoToken 通道2.1 Node.js 版本要求OpenClaw 对 Node.js 版本有硬性要求必须是 v20.x LTS 或更高推荐 v22 或 v24。低于 v20 会在安装阶段直接报引擎不兼容别想着绕过升级就完事。我建议用版本管理器而不是直接装全局 Node这样以后切换版本不污染系统。Windows 用 nvm-windowsmacOS 和 Linux 用 nvm 或 fnm 都行。以 nvm 为例# 安装并切换到 Node 22 LTS nvm install 22 nvm use 22 node -v # 应输出 v22.x.x npm -v如果你在 Ubuntu 上想用系统级安装走 NodeSource 源curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs node -v2.2 为什么 Gateway 要接 TaoTokenGateway 这一层需要调用大模型来完成指令理解和任务拆解所以你必须给它配一个模型 API 通道。直接对接各家官方 API 的问题是Key 分散、计费口径不一、切换模型要改配置。TaoToken 提供统一 Key 和统一 API 通道地址一个 Key 就能覆盖多种模型Gateway 配置里只填一个 base_url 和一个 api_key 即可后续换模型不用动 Gateway 骨架。TaoToken 官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 通道地址是 https://taotoken.net/api 。注意 API 地址不带任何查询参数配置时直接填这个根地址。你需要先去控制台创建一个 API Key这个 Key 就是后面 Gateway 配置里的凭证。创建入口在 API Keys 页面生成后复制保存页面关闭后不再完整显示。3. 安装 OpenClaw 与 clawhub3.1 安装 OpenClaw 本体macOS 和 Linux 用统一脚本curl -fsSL https://openclaw.ai/install.sh | bashWindows 在管理员 PowerShell 里执行Set-ExecutionPolicy Bypass -Scope Process -Force iwr -useb https://openclaw.ai/install.ps1 | iex安装完成后验证openclaw --version如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里。npm 全局安装的包默认在~/.npm-global/bin或/usr/local/bin用npm config get prefix看一下实际路径。3.2 安装 clawhub 并登录clawhub 是技能Skill的包管理器OpenClaw 的能力扩展全靠它。安装npm install -g clawhub clawhub -V登录需要 token。去 clawhub 官网点右上角头像进 settings找到 API token 生成一个然后clawhub login --token 你的token这里有个坑如果本地不登录直接装技能会报Rate limit exceeded。不是网络问题是匿名请求被限流了登录后就好了。装一个技能试试clawhub install tavily-search卸载用clawhub uninstall tavily-search。技能装完后要在 OpenClaw 的技能配置里启用不是装上就自动生效。4. Gateway 配置文件骨架与 TaoToken 接入4.1 初始化配置先跑初始化向导openclaw onboard --flow quickstart向导会问你几个问题同意风险声明、选模型、填 API Key、配交互通道飞书/Telegram/Web UI可以先跳过、技能配置选 npm、钩子跳过、安装 Gateway。走完之后把 Gateway 设为本地模式openclaw config set gateway.mode local4.2 Gateway 配置骨架OpenClaw 的配置文件通常在~/.openclaw/openclaw.jsonWindows 在C:\Users\你的用户名\.openclaw\openclaw.json。Gateway 接入 TaoToken 的关键字段如下这是一个最小可用骨架{ gateway: { mode: local, port: 18789, auth: { token: 自动生成的本地访问token }, upstream: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: 你在TaoToken控制台创建的Key, model: claude-sonnet-4-20250514 } } }几个字段说明provider填openai-compatible因为 TaoToken 走的是 OpenAI 兼容协议baseUrl就是https://taotoken.net/api不要加/v1后缀框架会自己拼apiKey填你创建的那个 Keymodel填你想用的模型标识具体可用模型列表在 TaoToken 文档里查。如果你不想手改 JSON也可以用命令行逐项设置openclaw config set gateway.upstream.baseUrl https://taotoken.net/api openclaw config set gateway.upstream.apiKey 你的Key openclaw config set gateway.upstream.model claude-sonnet-4-20250514改完配置后重启 Gateway 生效openclaw gateway restart5. 启动验证与成功结果5.1 启动 Gatewayopenclaw gateway start openclaw gateway statusstatus应该显示 running端口 18789 处于监听状态。如果显示 stopped 或端口被占用看下一节的排查。5.2 获取访问 token 并打开控制台openclaw config get gateway.auth.token复制输出的 token浏览器访问http://127.0.0.1:18789/?token你的token看到 Web 控制台界面就说明 Gateway 起来了。如果页面能打开但对话报错问题多半在 upstream 配置不是 Gateway 本身。5.3 验证模型通道是否通在 Web 控制台里发一句简单指令比如「列出当前目录下的文件」。如果模型正常返回并触发了技能执行说明 TaoToken 通道、Gateway、Pi-embedded 三层都通了。也可以直接用命令行测openclaw doctordoctor会逐项检查环境、Node 版本、Gateway 状态、upstream 连通性哪一项红了就修哪一项。6. 本篇常见报错排查6.1 Node 版本不兼容报错关键词Unsupported engine或requires node 20。解决nvm install 22 nvm use 22然后重新执行安装脚本。别用--force跳过引擎检查后面运行时会出更诡异的问题。6.2 Gateway 启动失败或端口占用报错关键词EADDRINUSE。说明 18789 被占了。查占用进程# macOS / Linux lsof -i :18789 # Windows netstat -ano | findstr 18789要么杀掉占用进程要么改 Gateway 端口openclaw config set gateway.port 18790然后重启。6.3 upstream 401 或 403说明 API Key 不对或没生效。检查三件事Key 是否复制完整前后无空格baseUrl是否误加了/v1配置改完后是否执行了openclaw gateway restart。改配置不重启是不生效的这个坑我踩过。6.4 clawhub 安装技能报 Rate limit exceeded前面说过本地没登录。执行clawhub login --token 你的token后再装。如果登录了还报检查 token 是否过期去 clawhub 官网重新生成。6.5 指令无响应如果 Web 控制台能打开、模型也能返回文本但执行类指令截图、读写文件没反应大概率是 Gateway 这一层的节点注册出了问题。先openclaw gateway status看 Pi-embedded 是否注册成功再openclaw logs follow实时看日志日志里会明确写出是哪个 Skill 加载失败还是沙箱启动超时。6.6 卸载重装清残留如果安装过程被中断过残留配置会导致各种奇怪问题。先卸载npm uninstall -g openclaw再备份并删除配置目录Windows 路径示例copy C:\Users\你的用户名\.openclaw\openclaw.json C:\Users\你的用户名\.openclaw\openclaw.json.bak rm -r C:\Users\你的用户名\.openclaw然后重新走安装流程。备份是好习惯配置里可能有你调了很久的参数。如果你卡在 Gateway 接入或 API Key 配置这一步直接去 TaoToken 的 API Keys 页面重新生成一个 Key对照接入文档逐字段核对 baseUrl 和 model 名称比反复重启 Gateway 有效得多。想先验证模型通道是否通用模型对话页面发一条测试指令最快。长期跑编码类任务或 Agent 工作流的话Coding Plan 的额度模型更适合持续调用不用每次手动续。