Openclaw本地部署指南:Node.js 20+环境搭建与Skill开发实战
1. 项目概述:Clawdbot 与 Openclaw 是什么,为什么需要“部署”而不是“安装”
Clawdbot 和 Openclaw 这两个名字在最近半年的技术社区里出现频率陡增,但很多人第一次看到时会下意识以为是某个新出的聊天机器人App——点开官网、下载安装包、双击运行完事。我最初也这么想,直到在本地跑第一条openclaw start命令时,终端弹出一连串红色报错:“command not found”、“node: command not found”、“git: command not found”,才意识到:这不是一个“装好就能用”的桌面软件,而是一套基于 Node.js 构建的、面向开发者和高级用户的可扩展智能体(Agent)运行时框架。Clawdbot 是它的核心引擎代号,Openclaw 是面向用户暴露的 CLI 工具与配置入口。它不提供图形界面,不打包 Electron,也不内置模型推理能力——它干的是更底层的事:把 LLM 调用、工具编排、记忆管理、多步任务拆解、插件加载这些能力,抽象成一套可声明、可调试、可嵌入的运行时协议。
所以,“部署教程”这个说法非常准确,甚至比“安装方法”更本质。安装(install)只是把二进制或源码放到本地;而部署(deploy)意味着你要为它准备好运行环境、配置好依赖链路、校准好路径与权限、验证好各模块间的通信状态,并最终让它稳定地作为一个长期服务进程存在。这就像你不会说“部署一个微信”,但你会说“部署一个 Nginx 反向代理”或“部署一个 Prometheus 监控栈”。Clawdbot/Openclaw 的定位,就是那个需要你亲手搭好脚手架、拧紧每一颗螺丝的基础设施级组件。
它解决的核心问题,是当前大模型应用开发中普遍存在的“胶水代码黑洞”:你写好了一个调用 Qwen 的函数,又写了一个查天气的 API 封装,再写了一个读取本地 Excel 的工具,最后发现它们之间调用混乱、错误难追踪、状态无法持久、调试全靠 console.log。Openclaw 把这些都收束到一个统一的技能(Skill)注册机制下,用 YAML 定义行为,用 TypeScript 编写逻辑,用openclaw run --skill=weather这样的命令驱动执行。它不替代你的业务代码,而是让你的业务代码变得可组合、可复用、可版本化。这也是为什么所有热词里反复出现 “dify本地部署教程”“ollama本地部署教程”——大家正在从“用现成AI产品”转向“搭自己的AI工作流”,而 Openclaw 就是这条路上一把趁手的扳手。
适合谁来参考这篇内容?不是只想体验 AI 聊天的普通用户,而是三类人:第一类是已经用过 Dify/Ollama/OneAPI,想进一步把多个 Agent 编排成复杂工作流的中级开发者;第二类是企业内部希望将已有 Python/Java 工具快速封装为 LLM 可调用 Skill 的运维或后端工程师;第三类是高校研究者,需要一个轻量、透明、可打断调试的 Agent 运行沙盒,用于测试新的规划算法或记忆机制。如果你属于这三类中的任何一类,那么接下来每一个步骤,都不是“照着敲就行”的流水账,而是我在真实项目中踩坑、回溯、重试十几次后,确认最稳、最易维护、最利于后续升级的路径。
2. 整体设计思路与方案选型:为什么必须用 Node.js 20+,为什么不用 Docker 封装,为什么 Git 不是可选项
在开始敲命令前,先说清楚三个关键决策点。这不是教条,而是我在 Windows 11 + WSL2 Ubuntu 24.04 + macOS Sonoma 三套环境反复验证后,放弃其他路径后留下的最优解。很多教程一上来就让你npm install -g openclaw,结果卡在 node 版本不兼容上;或者直接甩一个docker-compose.yml,结果发现 Windows 上 Docker Desktop 启动失败,又得去折腾 WSL2 内核更新。我们得从根上理清逻辑。
2.1 Node.js 版本:为什么死守 v20.12.0–v20.15.0 这个窄窗口
Openclaw 的 package.json 明确锁定了"engines": {"node": ">=20.12.0 <21.0.0"}。这不是作者任性,而是有硬性技术约束。它重度依赖 Node.js 20 引入的fetch全局 API 原生支持(无需额外 polyfill)、stream/web模块的完整实现(用于处理 SSE 流式响应),以及node:fs/promises的稳定性增强(避免在高并发 Skill 调用时出现 Promise 链断裂)。我试过强行用 v21.7.0,openclaw init能跑,但一旦启用--watch模式监听 Skill 文件变更,就会触发 V8 引擎的一个已知内存泄漏 bug,30 分钟后进程 OOM 自杀。我也试过降级到 v18.20.4,结果在加载@clawdbot/core时,TypeScript 编译器报错TS2792: Cannot find module './types'——因为 v18 的--resolve算法不兼容 Openclaw 使用的 ESM + CommonJS 混合模块解析策略。
所以,v20.12.0–v20.15.0 是目前唯一经过全链路压测的黄金区间。v20.12.0 是第一个完整修复fetch在 Windows 下 DNS 缓存 bug 的版本;v20.15.0 是最后一个在 Node.js 官方 LTS 支持列表里的 v20 小版本。中间的 v20.13.x/v20.14.x 全部可用,但建议优先选 v20.15.0,因为它的 npm 9.9.2 对workspaces的依赖解析更鲁棒,能避免后续添加自定义 Skill 时出现ERR_OSSL_EVP_UNSUPPORTED这类 OpenSSL 错误。
提示:不要用系统自带的 Node.js(比如 Ubuntu
apt install nodejs装出来的是 v18.x,macOS Homebrew 默认也是旧版)。必须用 Node Version Manager(nvm)或官方 .msi/.pkg 安装包。nvm 的优势在于可以一键切换,比如你同时要跑 Dify(需 v18)和 Openclaw(需 v20),nvm use 20.15.0就能秒切,互不干扰。
2.2 为什么推荐本地部署而非 Docker 封装
搜索热词里高频出现 “openclaw本地docker部署教程”,但我实测下来,在绝大多数个人开发与中小团队场景下,Docker 反而是引入复杂度的源头。原因有三:
第一,文件系统映射的不可见损耗。Openclaw 的 Skill 开发是强交互过程:你改一行 YAML,保存,openclaw run就该立刻生效。但在 Docker 中,你需要docker cp或挂载 volume,而 Windows/macOS 的文件系统事件(inotify)在容器内常被截断,导致--watch失效,你得手动docker restart,开发节奏被打断。
第二,网络调试的黑盒化。Openclaw 默认启动http://localhost:3000提供 Skill 调试面板,且支持openclaw proxy命令转发请求到本地 LLM 服务(如 Ollama 的http://localhost:11434)。在 Docker 网络模型下,localhost指向的是容器内部,不是宿主机。你得记一堆--network=host、--add-host=host.docker.internal:host-gateway参数,稍有遗漏,面板打不开、代理连不上,新手直接卡死。
第三,调试工具链的割裂。VS Code 的 Node.js 调试器、Chrome DevTools 的node inspect、甚至最简单的console.log,在容器内都需要额外配置--inspect端口映射和调试器连接。而本地部署,F5 一键 attach,断点打在哪,变量值实时可见,这才是高效开发该有的样子。
当然,Docker 在生产环境仍有价值——比如你要把 Openclaw 作为 Kubernetes 中的一个 Job 来批量执行数据清洗任务。但那属于另一个话题。本文聚焦“本地部署”,目标是让你在 30 分钟内,从零开始,看到openclaw run --skill=hello打印出 “Hello from Clawdbot!”。这个目标,Docker 不是捷径,而是绕远路。
2.3 为什么 Git 是硬性依赖,且必须配置好全局 user.name/user.email
这可能是最容易被忽略,却最致命的一环。Openclaw 的init命令不只是创建文件夹,它会自动执行git init,并生成一个.gitignore,里面预置了node_modules/、dist/、.env.local等关键排除项。更重要的是,它的 Skill 版本管理机制(openclaw skill publish)底层调用的是git tag和git push。如果你没配user.name,git commit会失败,整个初始化流程中断。
更隐蔽的问题是:Openclaw 的 CLI 会读取git config --global user.name作为默认的 Skill 作者标识,写入skill.yaml的author字段。如果你跳过这步,后续当你想把 Skill 发布到私有 Registry 时,服务器会拒绝没有 author 信息的包。我曾因此浪费 2 小时排查,最后发现只是git config --global user.name "Your Name"没执行。
所以,Git 不是“可能用到”,而是 Openclaw 运行时的元数据基础设施。它不参与模型推理,但决定了你的 Skill 是否具备可追溯、可协作、可发布的工程属性。这正是它区别于玩具级脚本的关键。
3. 核心细节解析与实操要点:环境准备、依赖校验、权限陷阱与路径规范
现在进入真正动手环节。别急着复制粘贴命令,先理解每个动作背后的“为什么”,否则一个字符输错,你就得花半小时翻日志。以下所有步骤,我都已在 Windows 11(WSL2 Ubuntu)、macOS Sonoma、原生 Ubuntu 24.04 上逐条验证。差异点我会明确标出。
3.1 环境准备:三步锁定纯净基线
第一步:清理潜在冲突的 Node.js
Windows 用户请打开 PowerShell(非 CMD),执行:
Get-Command node, npm, nvm | Select-Object -ExpandProperty Definition如果返回路径包含Program Files\nodejs\或AppData\Roaming\npm\,说明你装过旧版。请彻底卸载:控制面板 → 卸载程序 → 找到 Node.js → 卸载。然后删除残留文件夹C:\Users\<user>\AppData\Roaming\npm和C:\Users\<user>\AppData\Roaming\npm-cache。
macOS 用户请检查:
which node brew list | grep node如果which node返回/opt/homebrew/bin/node(Homebrew 装的),或/usr/local/bin/node(旧版 pkg 装的),请先brew uninstall node或手动删掉/usr/local/bin/node及其符号链接。
Ubuntu 用户请执行:
sudo apt remove nodejs npm sudo apt autoremove rm -rf ~/.nvm注意:不要用
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash这种一键脚本。它会修改你的~/.bashrc,而某些终端(如 VS Code 内置终端)可能不加载它,导致nvm命令找不到。我们手动安装,确保可控。
第二步:手动安装 nvm(Node Version Manager)
Windows(WSL2)用户:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 然后关闭当前终端,重新打开,执行: export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"macOS 用户(使用 Homebrew):
brew install nvm echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc echo '[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"' >> ~/.zshrc source ~/.zshrcUbuntu 用户:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"第三步:安装并锁定 Node.js v20.15.0
执行:
nvm install 20.15.0 nvm use 20.15.0 nvm alias default 20.15.0验证:
node -v # 必须输出 v20.15.0 npm -v # 必须输出 9.9.2如果npm -v输出低于 9.9.0,请强制升级:npm install -g npm@9.9.2。低版本 npm 在处理 Openclaw 的 workspace 依赖时,会错误地将@clawdbot/core解析为file:../core而非^1.2.0,导致后续openclaw run找不到模块。
3.2 依赖校验:Git 配置、权限、PATH 的三重确认
Git 配置是单点故障,必须一次做对:
git config --global user.name "Your Real Name" git config --global user.email "your.email@example.com" git config --global init.defaultBranch main git config --global core.autocrlf input # Windows 用户务必加这一行,避免换行符污染验证:
git config --global --list | grep -E "(name|email|branch)"应看到三行输出,无报错。
权限陷阱常出现在 Windows 和 macOS 上。Openclaw 的 CLI 二进制(openclaw)在 npm 全局安装后,会放在~/.nvm/versions/node/v20.15.0/bin/openclaw(macOS/Linux)或C:\Users\<user>\AppData\Roaming\nvm\v20.15.0\node_modules\openclaw\bin\openclaw(Windows)。如果PATH没包含这个路径,openclaw命令就找不到。
检查PATH:
echo $PATH | tr ':' '\n' | grep -i "nvm\|node"macOS/Linux 应看到类似/home/username/.nvm/versions/node/v20.15.0/bin的路径。Windows(PowerShell)执行:
$env:PATH -split ';' | Select-String nvm如果没输出,手动添加:
- macOS/Linux:
echo 'export PATH="$NVM_DIR/versions/node/$(nvm current)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc - Windows:在系统环境变量中,编辑
PATH,新增C:\Users\<user>\AppData\Roaming\nvm\v20.15.0\node_modules\openclaw\bin
实操心得:Windows 用户最容易在这里栽跟头。CMD 和 PowerShell 的
PATH是分开的。你可能在 PowerShell 里配好了,但用 VS Code 终端(默认是 PowerShell)却还是报错。解决方案是:在 VS Code 设置里搜索terminal.integrated.defaultProfile.windows,设为PowerShell,然后重启终端。这是血泪教训。
3.3 初始化项目:openclaw init的隐藏参数与目录结构真相
现在终于可以运行核心命令了。但别急着openclaw init myproject。先执行:
openclaw init --help你会看到几个关键选项:
--template:指定初始化模板,默认是basic,但还有ollama、dify、qwen等。--template ollama会自动生成连接本地 Ollama 的 Skill 示例。--git:是否初始化 git 仓库,默认true,但如果你确定不用 git,可加--no-git。--skip-install:跳过npm install,适合网络受限环境,之后手动cd myproject && npm install。
推荐首次使用:
openclaw init myagent --template basic --git它会创建以下结构:
myagent/ ├── .git/ # Git 仓库(含预设 .gitignore) ├── .openclaw/ # Openclaw 运行时元数据(不要手动改) ├── skills/ # 所有 Skill 的存放目录 │ └── hello/ # 示例 Skill │ ├── skill.yaml # Skill 描述文件(名称、描述、输入输出 schema) │ ├── index.ts # 主逻辑(TypeScript) │ └── test.ts # 单元测试(Jest) ├── package.json # 项目根配置(含 openclaw 脚本) ├── tsconfig.json # TypeScript 编译配置 └── README.md重点看skills/hello/skill.yaml:
name: hello description: A simple greeting skill version: 0.1.0 author: Your Real Name input: type: object properties: name: type: string description: The name to greet output: type: object properties: message: type: string这个 YAML 不是装饰品,它是 Openclaw 的“契约”。input和output的 JSON Schema 会被用来在运行时做参数校验和类型提示。如果你删掉name字段,openclaw run --skill=hello --input='{"name":"Alice"}'就会报错Input validation failed: missing required property 'name'。这就是它比裸写 JS 函数更工程化的体现。
4. 实操过程与核心环节实现:从零运行第一个 Skill,调试、修改、发布全流程
现在,我们让第一个 Skill 真正跑起来。这不是 demo,而是生产级调试的起点。
4.1 第一次运行:openclaw run的完整链条与日志解读
进入项目目录:
cd myagent执行:
openclaw run --skill=hello --input='{"name":"Clawdbot"}'预期输出:
{ "message": "Hello, Clawdbot! Welcome to Openclaw." }如果成功,恭喜,你已通过最基础的“心跳测试”。但真正的价值在日志里。加-v(verbose)参数:
openclaw run --skill=hello --input='{"name":"Clawdbot"}' -v你会看到类似:
[INFO] Initializing runtime with config: { ... } [DEBUG] Loading skill 'hello' from /path/to/myagent/skills/hello [DEBUG] Compiling TypeScript for skill 'hello'... [INFO] Compiled 1 file in 123ms [DEBUG] Validating input against schema... [INFO] Input valid [DEBUG] Executing skill 'hello' with input: {"name":"Clawdbot"} [INFO] Skill 'hello' executed successfully in 45ms注意[DEBUG] Compiling TypeScript...这一行。Openclaw 默认使用ts-node动态编译.ts文件,不生成.js。这意味着你改完index.ts,保存,再openclaw run,就是最新代码。没有tsc && node dist/index.js的繁琐步骤。这是为快速迭代设计的。
4.2 修改与调试:在 VS Code 中设置断点,实时观察变量
打开skills/hello/index.ts。默认代码是:
import { Skill } from '@clawdbot/core'; export const skill: Skill = { async execute(input: any) { return { message: `Hello, ${input.name}! Welcome to Openclaw.` }; } };现在,我们在return语句前加一个断点(VS Code 编辑器左侧行号旁点击),然后按Ctrl+Shift+P(macOSCmd+Shift+P),输入Debug: Open Configuration,选择Node.js,生成.vscode/launch.json。修改为:
{ "version": "0.2.0", "configurations": [ { "type": "node", "request": "launch", "name": "Run Hello Skill", "program": "${workspaceFolder}/node_modules/openclaw/bin/openclaw.js", "args": ["run", "--skill=hello", "--input={\"name\":\"Clawdbot\"}"], "console": "integratedTerminal", "internalConsoleOptions": "neverOpen", "skipFiles": ["<node_internals>/**"] } ] }按F5启动调试。程序会在断点处暂停,你可以鼠标悬停看input的值,打开 Debug Console 输入input.name查看,甚至修改input.name = "Openclaw"然后F10单步执行。这才是调试 Agent 的正确姿势——不是靠console.log,而是真·可视化调试。
实操心得:很多新手卡在
openclaw run没反应,其实是没等Compiling TypeScript完成。大型 Skill 可能编译要 2-3 秒,终端没输出不代表卡死。加-v就能看到进度。另外,--input的 JSON 字符串里双引号必须转义,Windows CMD 下要用双引号包裹整个字符串,如--input="{\"name\":\"Clawdbot\"}",而 PowerShell 下用单引号:--input='{"name":"Clawdbot"}'。这是跨平台最常出错的地方。
4.3 创建新 Skill:从零封装一个“天气查询”功能
现在,我们做一个实用的 Skill:调用和风天气免费 API 获取城市天气。这能体现 Openclaw 的核心价值——把外部服务变成 LLM 可调用的原子能力。
首先,申请 API Key:访问 https://dev.qweather.com ,注册,获取location_id(如北京是101010100)和key。
创建 Skill:
openclaw skill create weather它会生成skills/weather/目录。编辑skills/weather/skill.yaml:
name: weather description: Get current weather for a city version: 0.1.0 author: Your Real Name input: type: object properties: city: type: string description: City name in Chinese, e.g., "北京" output: type: object properties: temperature: type: number description: Current temperature in Celsius condition: type: string description: Weather condition, e.g., "晴" humidity: type: number description: Relative humidity percentage编辑skills/weather/index.ts:
import { Skill } from '@clawdbot/core'; import fetch from 'node-fetch'; // 替换为你的真实 key 和 location_id const QWEATHER_KEY = 'your_qweather_key'; const BEIJING_ID = '101010100'; export const skill: Skill = { async execute(input: { city: string }) { // 简单映射:实际项目应调用地理编码 API const cityMap: Record<string, string> = { '北京': BEIJING_ID, '上海': '101020100', '广州': '101280101' }; const locationId = cityMap[input.city] || BEIJING_ID; try { const res = await fetch( `https://devapi.qweather.com/v7/weather/now?location=${locationId}&key=${QWEATHER_KEY}` ); const data = await res.json(); if (data.code !== '200') { throw new Error(`QWeather API error: ${data.msg}`); } return { temperature: parseFloat(data.now.temp), condition: data.now.textDay, humidity: parseInt(data.now.humidity) }; } catch (err) { console.error('Weather skill error:', err); throw err; } } };安装依赖(node-fetch是必需的):
cd skills/weather npm init -y npm install node-fetch cd ../..运行测试:
openclaw run --skill=weather --input='{"city":"北京"}' -v你会看到完整的天气数据返回。此时,这个 Skill 就已具备被任何 LLM 调用的能力。你可以在 Dify 的自定义工具里,用 Openclaw 的 HTTP 代理模式暴露它,或者直接在openclaw chat的 REPL 环境里调用。
4.4 发布 Skill:openclaw skill publish到私有 Registry
Openclaw 支持将 Skill 打包发布到私有 NPM Registry(如 Verdaccio)或 GitHub Packages。这里以最简单的 GitHub Packages 为例。
首先,确保你已登录 GitHub CLI:
gh auth login然后,在项目根目录,创建.npmrc:
echo "//npm.pkg.github.com/:_authToken=\${GITHUB_TOKEN}" > .npmrc echo "@YOUR-GITHUB-USERNAME:registry=https://npm.pkg.github.com" >> .npmrc将YOUR-GITHUB-USERNAME替换为你的真实用户名。
发布:
openclaw skill publish weather --registry=https://npm.pkg.github.com --access=public它会自动:
- 读取
skills/weather/skill.yaml生成package.json - 打包
index.ts和skill.yaml为 tarball - 调用
npm publish推送到 GitHub Packages
发布后,其他同事只需:
openclaw skill add @your-username/weather就能把这个天气 Skill 拉到他们的项目里,无需复制代码。这就是 Openclaw 的协作价值:Skill 成为可复用、可版本化、可审计的工程资产。
5. 常见问题与排查技巧实录:从“command not found”到“Skill execution timeout”的全链路诊断
以下是我在过去三个月,帮 27 位不同背景的开发者(学生、前端、Java 后端、数据分析师)远程排查时,遇到的最高频、最棘手的 7 类问题。每一条都附带真实终端日志、根本原因和一招见效的解决方案。这不是理论,是现场抢救记录。
5.1 问题速查表:症状、日志、原因、解法
| 症状 | 典型终端日志 | 根本原因 | 一招解法 |
|---|---|---|---|
openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名 | PowerShell 报错 | Windows 下openclaw二进制未加入PATH,或 PowerShell 未加载 nvm 配置 | 在 PowerShell 执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser,然后nvm use 20.15.0,再npm install -g openclaw |
Error: Cannot find module '@clawdbot/core' | Node.js 报错Cannot find module | openclaw全局安装后,其依赖未正确 link 到项目本地node_modules | 进入项目目录,执行npm link openclaw,强制建立符号链接 |
Input validation failed: missing required property 'xxx' | [ERROR] Input validation failed | skill.yaml的inputschema 与openclaw run --input提供的 JSON 结构不匹配 | 用在线 JSON Schema Validator(如 jsonschemavalidator.net)校验skill.yaml和你的 input JSON |
Skill execution timeout after 30000ms | [ERROR] Skill 'xxx' execution timeout | Skill 代码中有死循环、未 resolve 的 Promise,或外部 API 调用超时未设限 | 在index.ts的execute函数开头加const controller = new AbortController(); setTimeout(() => controller.abort(), 25000);,并在fetch中传入{ signal: controller.signal } |
TypeError: fetch is not a function | Node.js 报错fetch is not a function | Node.js 版本低于 v20.12.0,或全局fetch被其他库覆盖 | 执行nvm install 20.15.0 && nvm use 20.15.0,然后npm install -g openclaw重装 |
Error: EACCES: permission denied, mkdir '/root/.openclaw' | Linux/macOS 权限错误 | 用sudo openclaw init创建了 root 权限的目录,后续操作无权限 | sudo chown -R $USER:$GROUPS ~/.openclaw,然后rm -rf myproject && openclaw init myproject |
openclaw chat启动后无响应 | 终端光标闪烁,无提示符 | openclaw chat依赖readline模块,某些终端(如 Windows Terminal 的旧版)不兼容 | 在 VS Code 终端或 macOS Terminal 中运行;或改用openclaw run --skill=chat --input='{"query":"Hello"}'模拟 |
5.2 深度案例:解决 “openclaw proxy无法连接本地 Ollama” 的完整排查链
这是热词里高频出现的问题:“openclaw接入ollama”。现象是:openclaw proxy --target http://localhost:11434 --port 3001启动成功,但 LLM 调用时返回502 Bad Gateway。
第一步:确认 Ollama 确实在运行
ollama list # 应看到模型列表 curl http://localhost:11434/api/tags # 应返回 JSON如果失败,Ollama 服务没起来,openclaw proxy再完美也没用。
第二步:确认openclaw proxy的 target 地址是否可达在openclaw proxy运行的同一台机器上:
curl -v http://localhost:11434/api/tags如果返回Connection refused,说明openclaw proxy的--target写错了。常见错误:
- Windows 用户写
--target http://host.docker.internal:11434(当 Ollama 在 Docker 中),但host.docker.internal是 Docker Desktop 的特殊 DNS,WSL2 不识别。应改用--target http://172.17.0.1:11434(Docker 默认网关 IP)。 - macOS 用户写
--target http://localhost:11434,但 Ollama 是通过brew services start ollama启动的,它绑定的是127.0.0.1,而localhost在某些 DNS 配置下可能解析为::1(IPv6),导致连接失败。应显式写--target http://127.0.0.1:11434。
第三步:确认 Skill 中的 API 调用 URL 是否指向 proxy 端口在 Skill 代码里,不要直接fetch('http://localhost:11434/api/chat'),而要fetch('http://localhost:3001/api/chat')(即 proxy 的--port)。这是最关键的一步,90% 的人在这里写错。
第四步:启用 proxy 日志
openclaw proxy --target http://127.0.0.1:11434 --port 3001 --log-level debug你会看到每条请求的转发详情。如果看到Forwarding request to http://127.0.0.1:11434/api/chat但无响应,说明是 Ollama 侧问题;如果根本没看到Forwarding日志,说明请求根本没打到 proxy,是 Skill 代码 URL 写错了。
这个案例的价值在于:它展示了 Openclaw 的定位——它不是万能胶,而是精密的管道工。它不解决 Ollama 启动问题,不解决网络连通问题,但它提供了清晰的日志和可控的代理层,让你能把问题精准定位到“是管道坏了,还是水源没开”。
5.3 终极避坑指南:三个我绝不再犯的错误
绝不共享
node_modules文件夹
有人为了“省事”,把整个node_modules打包发给同事。这是灾难。Openclaw 的node_modules里包含平台特定的二进制(如esbuild),Windows 的node_modules在 macOS 上直接npm start会报Error: Cannot find module './esbuild-linux-64'。正确做法:只共享package-lock.json,让对方npm ci重建。绝不修改
.openclaw/目录下的任何文件
这个目录是 Openclaw 的运行时数据库,存储 Skill 编译缓存、执行历史、临时密钥。我曾
