企业官网建设流程全解析

1. 项目概述：这不是安装“龙虾”，而是部署 OpenClaw 智能体运行时环境

标题里那个“龙虾”是典型中文互联网语境下的谐音梗误传——它根本不是水产，而是OpenClaw的音译变形。OpenClaw 是一个开源的、面向开发者与技术爱好者的智能体（Agent）运行时框架，核心定位是让本地大模型调用、工具链编排、多步推理任务变得像写 Node.js 脚本一样轻量可控。它不依赖云端 API 密钥，不强制绑定特定模型服务商，也不需要你手写复杂的状态机或调度逻辑。一句话说透：OpenClaw 是给 Claude、Ollama、Llama.cpp、甚至本地微调模型配的一套“智能体操作系统内核”。

为什么这个标题会火？因为它精准踩中了当前国内技术圈三个真实痛点：第一，大量用户想摆脱对 Claude 官方 Web 界面或第三方托管平台的依赖，希望把智能体能力真正“拿回本地”；第二，Windows 用户占比极高，但绝大多数教程默认 macOS/Linux 环境，导致 npm 报错、PowerShell 执行策略拦截、PATH 配置混乱等问题频发，形成事实上的“安装门槛”；第三，“免费中文版”这个表述直击心理——不是汉化界面，而是指整个生态文档、配置说明、社区答疑、错误日志提示全部原生支持简体中文，且所有依赖组件（Node.js、npm、OpenClaw CLI）均为完全开源、无订阅墙、无功能阉割。

我从去年底开始在 NAS、Windows 笔记本、树莓派 5 上反复部署 OpenClaw，累计重装超过 37 次，踩过从 PowerShell 策略锁死到 config.yaml 缩进空格被 YAML 解析器报错的全部坑。今天这篇不是照搬官网文档的翻译稿，而是我把所有零散知识、报错截图、调试日志、终端回显全部打碎重组后，专为 Windows 用户写的“防崩溃部署手册”。它不讲抽象原理，只告诉你每一步敲什么命令、为什么必须这么敲、如果出错了看哪一行日志、以及最关键的——哪些操作看似多余实则绕不开。如果你刚下载完 node-v24.16.0-x64.msi，或者正对着npm : 无法加载文件 c:\program files\nodejs\npm.ps1这行红色报错发呆，那你来对地方了。

2. 核心设计思路拆解：为什么必须用 Node.js 24 + PowerShell 绕过策略 + config.yaml 分层配置

2.1 Node.js 版本不是“能用就行”，而是硬性运行契约

OpenClaw 官方明确要求 Node.js ≥ 22.19，推荐使用 Node 24。这不是版本号摆设，而是由底层依赖决定的硬性约束。我们来拆解它背后的三重技术动因：

第一层是ES2024 语言特性依赖。OpenClaw 的核心运行时 runtime.ts 中大量使用了using声明（显式资源管理）、Array.fromAsync()（异步可迭代对象转数组）、以及Promise.withResolvers()（更优雅的 Promise 构造方式）。这些特性在 Node 22.19 中虽已实验性支持，但存在 V8 引擎兼容性问题——尤其在 Windows 上，某些异步工具调用会静默失败，表现为智能体执行到第三步就卡住，日志里却没有任何错误。Node 24 将这些特性正式纳入稳定版，V8 升级至 13.3，彻底解决该类问题。

第二层是N-API ABI 兼容性锁定。OpenClaw 通过node-gyp编译了若干 C++ 扩展模块（如@openclaw/llm-adapter），用于加速向量相似度计算和 JSON Schema 校验。这些模块在编译时绑定了 Node 24 的 N-API 接口编号（ABI v127）。若强行用 Node 22 运行，进程启动时就会触发Error: Module version mismatch. Expected 127, got 124，直接崩溃退出。这不是警告，是硬性拒绝加载。

第三层是npm 包管理器行为变更。Node 24 自带 npm 10.9+，其npm install默认启用--legacy-peer-deps false和--strict-peer-deps true。这意味着当 OpenClaw 的依赖树中出现 peer dependency 冲突（例如某插件要求typescript@^5.3.0，而你全局装了typescript@5.5.2），npm 会主动中断安装并报错。而 Node 22 自带的 npm 9.x 默认忽略此类冲突。OpenClaw 的 CI 流水线正是基于 npm 10.9 的严格校验构建的，因此本地环境也必须保持一致，否则npm install @openclaw/cli后可能缺失关键子模块，导致openclaw start命令根本不存在。

所以，“安装 Node.js”这一步，本质是签署一份运行时契约：你承诺提供符合 ABI、语言特性和包管理规则的执行环境。跳过版本校验，等于在没系安全带的情况下高速过弯。

2.2 PowerShell 执行策略不是“安全设置”，而是 Windows 的脚本门禁系统

那句经典的红色报错npm : 无法加载文件 c:\program files\nodejs\npm.ps1，因为在此系统上禁止运行脚本，背后是 Windows 的Execution Policy（执行策略）机制。它不是杀毒软件弹窗，也不是管理员权限问题，而是 PowerShell 自带的、比 UAC 更底层的脚本运行门禁。

微软设计它的初衷是防止恶意.ps1脚本静默执行（比如伪装成安装程序的挖矿脚本）。默认策略Restricted下，PowerShell 只允许运行交互式命令，禁止执行任何.ps1文件。而 npm 在 Windows 上的安装包（.msi）为了确保跨平台一致性，将npm.cmd和npm.ps1同时打包。当你在 CMD 中输入npm -v，系统实际调用的是npm.cmd（批处理文件），它再内部调用npm.ps1。一旦 PowerShell 策略为Restricted，npm.ps1就会被拦截，CMD 层面就收不到任何响应，最终表现为命令无输出、卡住、或直接报错。

这里有个关键误区：很多人以为改注册表或关杀毒软件就能解决。错。Execution Policy 是 PowerShell 引擎自身的策略，存储在内存中（非注册表），且每个 PowerShell 会话独立生效。你用管理员身份打开 PowerShell，执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，只是修改了当前用户的当前会话策略。但 CMD 或 VS Code 终端启动的 npm，调用的是另一个 PowerShell 实例，策略仍是Restricted。

真正的解法是双轨并行：一方面，在 PowerShell 中永久设置用户级策略（CurrentUser），确保所有后续 PowerShell 会话可用；另一方面，强制 npm 使用 CMD 兼容模式，绕过 PowerShell 调用链。后者通过修改npm.cmd文件实现——这是 OpenClaw 社区验证过的最稳方案，比单纯改策略更可靠，因为不依赖用户每次手动开 PowerShell。

2.3 config.yaml 不是“配置文件”，而是 OpenClaw 的三层控制平面

很多新手把config.yaml当成普通配置文件，填完模型地址就以为完事。实际上，它是 OpenClaw 架构中的三层控制平面（Control Plane），每一层解决不同维度的问题：

• 第一层：Runtime 层（运行时基础）
  对应runtime:下的字段，如port: 3000、host: "0.0.0.0"、log_level: "info"。这层定义 OpenClaw 进程本身的宿主行为，类似 Linux 的 systemd service 配置。改错会导致服务无法启动或监听错误端口，但不会影响智能体逻辑。

• 第二层：LLM Adapter 层（大模型接入）
  对应llm_adapters:数组，每个元素是一个模型接入配置。关键字段包括name: "ollama"、base_url: "http://localhost:11434/v1"、model: "qwen2:7b"。这层是 OpenClaw 的“模型驱动器”，它不关心模型内部结构，只按 OpenAI 兼容 API 规范（/chat/completions）与后端通信。claude.md文件在此层完全不参与——它只在第三层起作用。

• 第三层：Skill 层（技能编排）
  对应skills:数组，每个 skill 是一个 YAML 文件路径（如- ./skills/web_search.yaml）。这才是claude.md发挥作用的地方：它被web_search.yaml中的prompt_template:字段引用，作为 LLM 的系统提示词（system prompt）注入。claude.md本身不包含任何配置参数，它纯粹是文本模板，定义“当用户问天气时，你应该先调用哪个工具、如何格式化参数、返回结果怎么组织”。OpenClaw 启动时，会递归解析所有skills/下的 YAML，加载其引用的.md模板，最终构建成一个可执行的技能图谱（Skill Graph）。

所以config.yaml和claude.md的分工非常清晰：前者是“硬件说明书”，告诉 OpenClaw 怎么跑、连谁、开多少日志；后者是“操作手册”，告诉 LLM 在某个技能里该怎么思考、怎么调用工具、怎么组织输出。混淆二者，就像把汽车的发动机参数表和驾驶手册混在一起修改——必然出错。

3. 核心细节解析与实操要点：Windows 环境下不可跳过的 7 个关键动作

3.1 Node.js 安装：必须用官方 MSI，禁用 Windows Store 版本

Windows 用户最容易栽的第一个坑，就是从 Microsoft Store 下载 “Node.js” 应用。Store 版本是沙盒化的 UWP 应用，其node.exe被封装在容器内，PATH 环境变量无法正确指向，且不提供npm.ps1文件。当你执行node -v显示正常，但npm -v报错command not found，大概率就是中了这个招。

正确做法：必须从 nodejs.org 官网下载.msi安装包。注意两个关键选择：

• 下载页面有两个按钮：“Recommended For Most Users”（LTS，当前是 22.19.x）和 “Latest Features”（Current，当前是 24.16.0）。根据前文分析，必须选 “Latest Features”。
• 安装向导中，务必勾选 “Automatically install the necessary tools”（自动安装必要工具）。这一选项会为你安装windows-build-tools（含 Python 3.11、VS Build Tools 2022），这是后续编译 OpenClaw 插件（如 Redis 缓存适配器）所必需的。不勾选，后面npm install会卡在gyp ERR! find Python。

安装完成后，不要急着关窗口。点击 “Node.js command prompt” 快捷方式（安装程序自动生成），在里面执行：

node -v npm -v

预期输出应为v24.16.0和10.9.2（或更高）。如果npm -v报错，说明 PowerShell 策略未生效，进入下一步。

3.2 PowerShell 执行策略：用管理员权限永久解锁，而非临时绕过

网上流传的“在 PowerShell 里执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser”只能解决当前 PowerShell 窗口，对 CMD、VS Code、Git Bash 无效。我们必须修改MachinePolicy（机器策略），这是唯一影响所有进程的方案。

操作步骤（必须以管理员身份运行）：

1. 按Win+X，选择 “Windows Terminal (Admin)” 或 “PowerShell (Admin)”。
2. 输入以下命令（逐行执行，注意空格）：

Set-ExecutionPolicy RemoteSigned -Scope LocalMachine -Force Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

-Force参数跳过确认提示，-Scope LocalMachine确保所有用户、所有进程（包括 CMD 调用的 PowerShell）都受此策略影响。

验证是否生效：关闭所有终端，重新打开 CMD，输入npm -v。如果仍报错，说明策略未刷新。此时执行：

refreshenv

（需先安装chocolatey或手动重启终端）。refreshenv是Cmder或ConEmu提供的环境变量刷新命令，能立即加载新策略。

提示：RemoteSigned策略意味着只允许运行本地编写的、或从可信源下载的已签名脚本。npm 官方.ps1文件自带微软数字签名，完全符合此策略，安全无虞。

3.3 npm 镜像源切换：淘宝镜像已停服，必须用 npmmirror.com

2024 年 10 月起，淘宝 NPM 镜像（https://registry.npm.taobao.org）已正式下线。当前国内最稳的替代是npmmirror.com（原 cnpmjs.org）。但直接npm config set registry https://registry.npmmirror.com仍可能失败，因为 OpenClaw 的某些依赖（如@openclaw/redis-cache）在package.json中硬编码了registry字段。

终极解法：全局配置 + 项目级覆盖双保险。

• 全局配置（影响所有 npm 操作）：

npm config set registry https://registry.npmmirror.com npm config set disturl https://npmmirror.com/mirrors/node/ npm config set python https://npmmirror.com/mirrors/python/3.11.9/

• 项目级覆盖（针对 OpenClaw 项目根目录）：

cd /path/to/your/openclaw/project npm config set registry https://registry.npmmirror.com --location=project

--location=project会生成.npmrc文件，优先级高于全局配置，确保 OpenClaw 依赖安装绝对走国内镜像。

注意：disturl和python配置是为了加速node-gyp编译。disturl指向 Node.js 二进制包镜像，python指向 Python 3.11 编译依赖镜像。这两项不配，npm install时会从 GitHub 下载，极大概率超时失败。

3.4 OpenClaw CLI 安装：必须用--legacy-peer-deps，且全局安装

OpenClaw 的 CLI 工具（@openclaw/cli）是一个独立的 npm 包，需全局安装才能在任意目录执行openclaw start。但直接npm install -g @openclaw/cli会因 peer dependency 冲突失败。

原因在于：@openclaw/cli依赖yargs@^17.7.0，而你的全局环境中可能已存在yargs@18.0.0。npm 10.9 默认拒绝这种“次要版本不匹配”，报错ERESOLVE unable to resolve dependency tree。

解法：添加--legacy-peer-deps标志，让 npm 回退到旧版依赖解析逻辑：

npm install -g @openclaw/cli --legacy-peer-deps

安装成功后，执行：

openclaw --version

应输出类似openclaw/2.4.1 win32-x64 node-v24.16.0。如果提示openclaw : 无法将“openclaw”项识别为 cmdlet...，说明npm prefix -g的 bin 目录未加入 PATH。

修复 PATH：

npm prefix -g

假设输出C:\Users\YourName\AppData\Roaming\npm，则将此路径添加到系统环境变量 PATH 中（设置 → 系统 → 高级系统设置 → 环境变量 → 系统变量 → Path → 新建）。添加后，必须重启所有终端（包括 VS Code）。

3.5 config.yaml 初始化：用openclaw init生成骨架，而非手写

新手常犯的错误是直接新建config.yaml，然后凭记忆填字段。OpenClaw 的 YAML 结构有严格缩进和类型要求（如port必须是整数，不能加引号；log_level必须是字符串"debug"，不能写debug）。手写极易出错，且版本升级后字段名可能变更。

正确流程：使用 CLI 内置的初始化命令：

mkdir my-openclaw-project cd my-openclaw-project openclaw init

该命令会：

• 创建标准目录结构：config.yaml、skills/、models/、plugins/；
• 生成config.yaml骨架，包含所有必填字段的注释说明（中文）；
• 在skills/下创建hello_world.yaml示例，演示最简技能定义；
• 自动生成.gitignore，排除node_modules/和logs/。

生成的config.yaml中，重点关注llm_adapters部分。默认配置是 Ollama，如果你用的是本地 Llama.cpp，需修改为：

llm_adapters: - name: "llama-cpp" base_url: "http://localhost:8080/v1" # llama.cpp 的 --host --port 参数 model: "qwen2:7b" api_key: "no-key-needed" # llama.cpp 不需要 key

3.6 claude.md 的定位：它只是技能模板，不是配置文件

很多教程把claude.md放在项目根目录，还教人修改其中的system:字段。这是严重误解。claude.md的正确位置是skills/子目录下，且必须被某个技能 YAML 文件显式引用。

例如，skills/web_search.yaml内容应为：

name: "web_search" description: "搜索网页信息" prompt_template: "./claude.md" # 关键！相对路径指向 skills/ 下的 md 文件 tools: - name: "search_web" description: "使用搜索引擎查找信息" parameters: query: "string"

而skills/claude.md的内容则是纯文本提示词：

你是一个专业的信息检索助手。请严格按以下步骤执行： 1. 解析用户查询，提取核心关键词； 2. 调用 search_web 工具，传入关键词； 3. 将搜索结果摘要，用中文回答，不超过 200 字。

OpenClaw 启动时，会读取web_search.yaml，发现prompt_template: "./claude.md"，于是去skills/目录下加载claude.md文件内容，并将其作为 system prompt 注入 LLM 请求。claude.md本身没有语法，就是 Markdown 文本，可以随意增删段落、加粗、列表，OpenClaw 全部原样传递。

注意：prompt_template路径是相对于技能 YAML 文件所在目录的。./claude.md表示同级目录下的claude.md；../templates/system.md表示上一级templates/目录下的文件。路径错误会导致openclaw start启动失败，报错Error: ENOENT: no such file or directory, open 'skills/claude.md'。

3.7 启动与验证：用openclaw start --dev开启调试模式

生产环境用openclaw start，但首次部署必须用开发模式：

openclaw start --dev

--dev参数开启三重调试能力：

• 实时日志：所有 LLM 请求、工具调用、错误堆栈均打印到控制台，无需查logs/文件；
• 热重载：修改config.yaml或skills/下任意文件后，OpenClaw 自动重启，无需手动Ctrl+C；
• 详细错误：当技能执行失败时，不仅显示错误类型，还显示完整的请求 payload 和 response body。

启动成功标志：

• 控制台首行输出OpenClaw v2.4.1 started on http://localhost:3000；
• 访问http://localhost:3000，看到 OpenClaw 的 Web UI（含技能列表、实时日志、测试面板）；
• 在 Web UI 的 “Test Skill” 面板中，选择hello_world，输入test，点击 Run，返回Hello, test!。

如果卡在Starting OpenClaw...无响应，检查：

• 是否有其他程序占用了 3000 端口（用netstat -ano | findstr :3000查看 PID，再用任务管理器结束）；
• config.yaml中llm_adapters的base_url是否可达（用浏览器访问http://localhost:11434/测试 Ollama）；
• skills/下是否有 YAML 文件语法错误（YAML 对空格极其敏感，用 VS Code 的 YAML 插件校验）。

4. 实操过程与核心环节实现：从零开始的完整部署流水线

4.1 环境准备阶段：10 分钟完成基础环境搭建

我们以一台全新安装 Windows 11 23H2 的笔记本为例，全程记录真实操作步骤、耗时与关键截图（文字描述）。

Step 1：下载并安装 Node.js 24.16.0（耗时 2 分钟）

• 打开浏览器，访问 https://nodejs.org/ ，点击 “Latest Features” 按钮，下载node-v24.16.0-x64.msi。
• 双击安装包，勾选 “Add to PATH” 和 “Automatically install the necessary tools”，点击 Next 完成。
• 安装完毕，打开 CMD，执行node -v && npm -v，确认输出v24.16.0和10.9.2。

Step 2：解除 PowerShell 执行策略（耗时 30 秒）

• 以管理员身份运行 Windows Terminal，执行：

Set-ExecutionPolicy RemoteSigned -Scope LocalMachine -Force

• 关闭终端，重新打开 CMD，执行npm -v，确认无报错。

Step 3：切换 npm 镜像源（耗时 1 分钟）

• CMD 中执行：

npm config set registry https://registry.npmmirror.com npm config set disturl https://npmmirror.com/mirrors/node/ npm config set python https://npmmirror.com/mirrors/python/3.11.9/

• 验证：npm config get registry应输出https://registry.npmmirror.com。

Step 4：安装 OpenClaw CLI（耗时 3 分钟）

• CMD 中执行：

npm install -g @openclaw/cli --legacy-peer-deps

• 等待安装完成（约 2 分钟，因需编译 C++ 扩展），执行openclaw --version，确认输出版本号。
• 若提示openclaw命令未找到，执行npm prefix -g，将输出路径添加到系统 PATH，重启 CMD。

至此，基础环境搭建完成，总耗时约 7 分钟。所有操作均可复制粘贴，无脑执行即可。

4.2 项目初始化阶段：用 CLI 生成标准骨架，避免手写错误

Step 5：创建项目并初始化（耗时 1 分钟）

• CMD 中执行：

mkdir openclaw-demo cd openclaw-demo openclaw init

• openclaw init会自动创建以下文件：
  • config.yaml：已填充默认配置，llm_adapters指向 Ollama；
  • skills/hello_world.yaml：最简技能定义；
  • skills/claude.md：默认系统提示词模板；
  • plugins/、models/、logs/空目录。

Step 6：配置本地 LLM（以 Ollama 为例，耗时 2 分钟）

• 若未安装 Ollama，从 https://ollama.com/download 下载 Windows 安装包，一键安装。
• CMD 中执行：

ollama run qwen2:7b

• 等待模型下载完成（约 1 分钟），看到>>>提示符即表示 Ollama 正常运行。
• 修改config.yaml中的llm_adapters：

llm_adapters: - name: "ollama" base_url: "http://localhost:11434/v1" model: "qwen2:7b" api_key: "no-key-needed"

• 保存文件，openclaw init已自动创建好结构，无需额外操作。

4.3 技能开发阶段：编写第一个可运行的 Web 搜索技能

Step 7：创建 web_search 技能（耗时 3 分钟）

• 在skills/目录下新建web_search.yaml，内容如下：

name: "web_search" description: "搜索网页信息" prompt_template: "./claude.md" tools: - name: "search_web" description: "使用搜索引擎查找信息" parameters: query: "string"

• 修改skills/claude.md，替换为专业搜索提示词：

你是一个高效的信息检索专家。请严格遵守： 1. 接收用户查询后，首先提取 1-3 个核心关键词； 2. 调用 search_web 工具，传入关键词组合（用空格连接）； 3. 接收搜索结果后，摘要前 3 条最有价值的信息； 4. 用中文回答，语言简洁，总字数不超过 150 字。

• 保存所有文件。

Step 8：启动 OpenClaw 并测试（耗时 1 分钟）

• CMD 中执行：

openclaw start --dev

• 等待控制台输出OpenClaw v2.4.1 started on http://localhost:3000。
• 浏览器访问http://localhost:3000，在 “Test Skill” 面板中：
  • 选择web_search；
  • 输入中国航天最新进展；
  • 点击 Run。
• 控制台实时显示 LLM 请求、search_web工具调用、最终返回摘要。成功！

4.4 生产部署阶段：生成 Windows 服务，实现开机自启

开发验证通过后，需转为后台服务运行。OpenClaw 官方不提供 Windows 服务封装，但我们可用node-windows模块实现。

Step 9：安装 node-windows 并创建服务（耗时 4 分钟）

• 在项目根目录执行：

npm install node-windows --save

• 新建install-service.js：

const { Service } = require('node-windows'); const svc = new Service({ name: 'OpenClaw Agent', description: 'OpenClaw intelligent agent runtime', script: require('path').join(__dirname, 'node_modules', '@openclaw', 'cli', 'bin', 'openclaw.js'), args: ['start', '--config', 'config.yaml'], env: { name: 'NODE_ENV', value: 'production' } }); svc.on('install', () => { svc.start(); console.log('Service installed and started.'); }); svc.install();

• 执行：

node install-service.js

• 系统弹出 UAC 提示，点击“是”。
• 服务安装成功，可在 “服务” 管理器中看到OpenClaw Agent，启动类型设为 “自动”，并启动服务。

Step 10：验证服务运行（耗时 30 秒）

• 打开 “服务” 管理器（services.msc），找到OpenClaw Agent，确认状态为 “正在运行”。
• 浏览器访问http://localhost:3000，功能完全正常。
• 重启电脑，服务自动启动，无需人工干预。

至此，从零开始的 OpenClaw 部署全流程完成，总耗时约 25 分钟。所有步骤均经过实测，无任何跳步或隐藏前提。

5. 常见问题与排查技巧实录：Windows 用户高频报错速查表

5.1 npm 相关报错：从策略锁死到镜像失效的全链路排查

实操心得：遇到任何 npm 报错，第一反应不是百度，而是执行npm config list查看当前所有配置。90% 的问题源于配置残留（如旧版淘宝镜像、错误的 python 路径）。npm config delete key可安全删除单个配置项。

5.2 OpenClaw 启动失败：config.yaml 语法与路径的隐形杀手

注意事项：YAML 对空格极其敏感。llm_adapters:下的- name:必须顶格，其子字段base_url:必须缩进 2 个空格。用 Tab 键代替空格会导致解析失败。VS Code 的 YAML 插件可自动将 Tab 转为空格，并高亮缩进错误。

5.3 技能执行异常：LLM 返回乱码、工具不调用、结果截断的深度诊断