1. 项目概述这不是一个“安装包”而是一套智能体运行时环境的本地化落地工程OpenClaw 不是传统意义上的软件它更像一个可插拔、可编排、可私有化的 AI 智能体操作系统内核。2026 版本之所以被冠以“全平台通用”核心在于它彻底放弃了对单一运行时如 Python 虚拟环境或特定服务架构如必须依赖 Docker Compose的强绑定转而采用“分层抽象 运行时自适应”的设计哲学。这意味着你在 Windows 上用 PowerShell 装出来的 OpenClaw和在 Ubuntu 22.04 上用 bash 装出来的底层启动逻辑、配置加载顺序、技能模块加载机制完全一致——不是“兼容”而是“同源”。我第一次在客户现场部署时就遇到过一台 macOS M1 机器和一台 Windows Server 2022 虚拟机同时接入同一套 NAS 存储的技能仓库两者调用同一个 Notion API 插件时返回的数据结构、错误码、重试策略完全同步这背后是 OpenClaw 在 2026 版本中重构的core/runtime/bridge模块在起作用。它把 Node.js 的事件循环、Python 的 asyncio、Shell 的进程管理全部抽象成统一的“执行上下文”这才是“全平台通用”四个字的真实分量。你装的不是一行命令而是一个跨平台的智能体调度中枢。它不处理模型推理但决定哪个模型该在什么时候、以什么参数、调用哪些工具、把结果喂给谁它不存储数据但精确控制每一条用户指令流经多少个技能节点、每个节点的输入输出如何序列化、失败时状态如何回滚。所以这篇教程里不会出现“双击 setup.exe”这种描述因为 OpenClaw 从不提供图形化安装器——它的安装过程本身就是一次对本地开发环境的深度体检与精准适配。你会看到 curl 和 iwr 命令但它们下载的不是二进制文件而是一个动态生成的、针对你当前系统指纹OS 内核版本、glibc 版本、Shell 类型、默认编码定制的初始化脚本。这个脚本会先静默检测你的 Node.js 是否真的满足 v22.3.0注意不是 ≥v22而是必须 ≥v22.3.0因为 v22.2.x 存在一个影响 WebSocket 心跳保活的内存泄漏 bug如果缺失或版本不符它会从 https://nodejs.org/dist/ 对应路径拉取预编译的二进制而不是调用包管理器去编译——这是为了确保在 ARM64 的树莓派 5 或者老旧的 Intel Atom 平台上都能在 90 秒内完成基础运行时构建。这也是为什么网络热词里反复出现 “openclaw : 无法将‘openclaw’项识别为 cmdlet”——90% 的报错根源不是 PATH 没配好而是用户手动安装的 Node.js 是 v20.x而 OpenClaw 的 CLI 二进制在启动时会主动拒绝加载它宁可报错也不愿在不兼容的运行时上跑出不可预测的行为。所以别把它当软件装把它当一个需要你亲手校准的精密仪器来对待。2. 安装前的硬性检查清单绕过所有“已安装却报错”的幻觉陷阱绝大多数人卡在“第一步”之后根本原因是把“系统提示已安装”当成了“环境真正就绪”。OpenClaw 的安装脚本install.sh / install.ps1本身非常健壮但它无法替你解决操作系统层面的隐性冲突。我整理了过去三个月在 GitHub Issues 和 Discord 社区里高频出现的 17 类“伪成功”案例把它们浓缩成一份必须逐项手检的硬性清单。这不是建议是强制步骤跳过任何一项后续所有操作都可能在某个深夜三点钟给你弹出一个让你怀疑人生的ERR_CONNECTION_REFUSED。2.1 系统级依赖的“真·存在性”验证很多人以为node -v能返回版本号就万事大吉。错。你需要验证的是 Node.js 的完整运行时能力特别是对现代 Web 标准的支持。请在终端中执行以下三行命令并严格比对输出# 1. 验证 V8 引擎版本OpenClaw 的 TUI 渲染层重度依赖 V8 的 WebAssembly SIMD 扩展 node -p process.versions.v8 # 2. 验证 OpenSSL 版本所有 API 调用的 TLS 握手都走这里低于 3.0.0 会导致 Kimi 接口 403 node -p require(crypto).getFips() ? FIPS mode enabled : FIPS mode disabled # 3. 验证 libuv 事件循环OpenClaw 的技能并发调度基于 libuv 的线程池旧版会卡死 node -p process.versions.uv提示对于 macOS 用户如果你用 Homebrew 安装了 Node.js请务必执行brew unlink node brew link node。Homebrew 的 symlink 机制有时会让node -v显示正确版本但实际加载的 dylib 却来自/usr/lib下的系统旧版这是 macOS 上“已安装却报错”的头号元凶。Windows 用户请检查where node的输出是否唯一如果返回多个路径比如同时存在C:\Program Files\nodejs\node.exe和C:\Users\XXX\AppData\Roaming\npm\node.cmd请手动删除后者并清空 npm 缓存npm cache clean --force。2.2 网络与 DNS 的“穿透式”连通性测试OpenClaw 的安装脚本会尝试连接https://openclaw.ai获取最新配置但这只是第一道关卡。真正的挑战在于它后续要访问的第三方服务端点。请用以下命令进行穿透测试不要依赖浏览器# 测试核心基础设施必须 200 OK curl -I -s -o /dev/null -w %{http_code}\n https://openclaw.ai # 测试 Kimi API 端点中国用户必测.cn 域名解析常被污染 curl -I -s -o /dev/null -w %{http_code}\n https://platform.moonshot.cn # 测试 Anthropic 端点国际用户必测确认无 GEO-IP 封锁 curl -I -s -o /dev/null -w %{http_code}\n https://api.anthropic.com # 测试 DNS 解析质量OpenClaw 内部使用 DoH需确认 443 端口未被劫持 dig short 1.1.1.1 platform.moonshot.cn A注意如果dig命令返回空或超时说明你的本地 DNS 解析链路存在严重问题。此时不要急着换 DNS 服务器先执行nslookup -debug platform.moonshot.cn观察响应中的AUTHORITY SECTION是否为空。如果为空大概率是你的路由器或 ISP 进行了 DNS 污染必须在系统级设置中强制指定 DoH如 Cloudflare 的https://cloudflare-dns.com/dns-query否则 OpenClaw 在配置阶段获取的 API Key 验证 URL 就是错的导致后续所有模型调用都返回invalid_api_key。2.3 权限与文件系统的“原子性”校验Linux/macOS 用户最容易忽略的是文件系统挂载选项。OpenClaw 的技能仓库~/.openclaw/skills默认使用 SQLite 作为元数据存储而某些 NAS 或加密卷如 ecryptfs在挂载时若启用了noexec或nosuid选项会导致 SQLite 的 WAL 日志模式无法创建临时文件表现为openclaw tui启动后立即崩溃日志里只有一行SQLITE_CANTOPEN。请执行# 查看 home 目录所在文件系统的挂载选项 findmnt -T $HOME | grep -oE (noexec|nosuid|nodev) # 检查 ~/.openclaw 目录的磁盘配额OpenClaw 的缓存目录会自动增长配额不足会导致技能加载失败 df -h ~/.openclaw实操心得我在为客户部署 NAS 版 OpenClaw 时发现 Synology DSM 的默认共享文件夹启用了noexec。解决方案不是改 NAS 设置那会影响其他服务而是在安装前手动指定技能仓库路径OPENCLAW_SKILLS_PATH/volume1/homes/admin/openclaw_skills curl -fsSL https://openclaw.ai/install.sh | bash。这样所有 SQLite 操作都在一个没有限制的卷上进行完美规避问题。2.4 Shell 环境的“纯净度”快照PowerShell 用户请特别注意install.ps1脚本会修改你的$PROFILE文件在末尾追加一行 $env:USERPROFILE\AppData\Roaming\npm\openclaw.ps1。但如果$PROFILE文件本身已经损坏比如包含 BOM 头、或某行末尾有不可见的 Unicode 字符PowerShell 在加载时会静默失败导致openclaw命令始终找不到。验证方法极其简单# 在管理员 PowerShell 中执行 Test-Path $PROFILE # 必须返回 True Get-Content $PROFILE | Select-String openclaw # 必须返回匹配行 # 最关键一步手动执行这一行看是否报错 $env:USERPROFILE\AppData\Roaming\npm\openclaw.ps1 --version如果最后一行报错The term openclaw.ps1 is not recognized说明$env:USERPROFILE\AppData\Roaming\npm\不在你的$env:PATH中或者该路径下根本没有openclaw.ps1文件。此时不要重装直接运行npm install -g openclaw2026.0.0然后再次检查Get-Command openclaw的输出。记住install.ps1是一个“引导器”它不保证 100% 成功但npm install -g是最终的、确定性的安装方式。3. 全平台安装流程详解从 curl 到第一个 TUI 会话的完整链路现在我们进入真正的安装环节。请摒弃“复制粘贴就完事”的心态。每一个命令背后都有其不可替代的工程逻辑。我会拆解每一行的作用、可能的失败点、以及失败后的即时诊断方案。这不是流水账而是一份可执行的故障树分析手册。3.1 macOS / Linux 平台curl 命令背后的四层防御机制curl -fsSL https://openclaw.ai/install.sh | bash这行命令看似简单实则包含了四层精密的防御与自愈逻辑-f(fail fast)一旦curl从服务器收到 HTTP 4xx/5xx 状态码立即退出并返回非零状态。这防止了脚本下载到一个 HTML 错误页面比如网站维护时返回的 503 页面后还傻乎乎地执行。-s(silent)隐藏进度条但保留 stderr 输出。这意味着所有错误信息如证书验证失败、DNS 解析超时都会原样打印到你的终端而不会被进度条淹没。-S(show error)与-s配合确保即使在静默模式下错误信息也强制显示。这是调试的关键。-L(follow redirects)OpenClaw 的安装脚本 URL 是一个重定向链接最终指向一个根据你的User-Agent和Accept-Language动态生成的、带 SHA256 校验值的脚本。-L确保你能拿到最终的、正确的脚本。实操心得如果这行命令卡住超过 60 秒请立即按CtrlC中断然后执行curl -v -I https://openclaw.ai/install.sh 21 | head -20。观察Location:头是否指向一个https://cdn.openclaw.ai/...的 URL。如果不是说明你的 DNS 或网络代理拦截了重定向需要更换网络环境。我见过最离谱的案例是某企业防火墙把openclaw.ai的 CNAME 记录openclaw-cdn.azureedge.net误判为恶意域名并返回了 302 重定向到内部警告页导致整个安装流程陷入死循环。安装脚本执行后它会做三件关键的事第一件事环境指纹采集。它会运行uname -m,cat /etc/os-release,locale -a | grep -i utf8等命令生成一个唯一的system_fingerprint.json并上传到 OpenClaw 的匿名遥测服务可选可在安装后通过openclaw config set telemetry.enabled false关闭。这个指纹决定了它为你下载哪个预编译的 Node.js 二进制。第二件事Node.js 的“外科手术式”安装。它不会覆盖你已有的 Node.js而是将新版本安装到~/.openclaw/node/下并通过符号链接~/.openclaw/bin/node指向它。这样你的系统 Node.js 和 OpenClaw 的 Node.js 完全隔离互不影响。第三件事全局 CLI 的“软链接”注册。它会在~/.openclaw/bin/下创建openclaw、openclaw-gateway等可执行文件并将~/.openclaw/bin添加到你的 shell 启动文件.zshrc或.bashrc的PATH开头。这是为了确保openclaw命令永远优先调用 OpenClaw 自带的、经过验证的版本。3.2 Windows 平台PowerShell 的安全策略与 install.ps1 的绕行艺术iwr -useb https://openclaw.ai/install.ps1 | iexiwr是Invoke-WebRequest的别名-useb是-UseBasicParsing的缩写。这个参数至关重要。默认情况下PowerShell 的Invoke-WebRequest会尝试加载 IE 的 HTML 解析引擎来处理响应内容这在无 GUI 的 Server Core 环境或某些精简版 Windows 上会直接失败报错The response content cannot be parsed because the Internet Explorer engine is not available。-UseBasicParsing强制 PowerShell 使用内置的轻量级解析器绕过了这个致命缺陷。install.ps1脚本的执行流程与 macOS/Linux 版本高度一致但它多了一步关键的“权限提升”检测# 脚本开头会执行 if (-not ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] Administrator)) { Write-Error 此脚本必须以管理员身份运行。请右键单击 PowerShell选择以管理员身份运行。 exit 1 }注意很多用户以为“以管理员身份运行”就够了但忽略了 PowerShell 的执行策略Execution Policy。如果系统策略是AllSigned或RemoteSigned而install.ps1没有数字签名脚本会被直接阻止。此时你不能也不应该全局修改执行策略。正确的做法是在管理员 PowerShell 中先临时设置当前会话的策略Set-ExecutionPolicy RemoteSigned -Scope Process -Force然后再执行iwr -useb ... | iex。安装完成后脚本会自动将openclaw.ps1注册为一个“已签名”的脚本它会生成一个本地的、仅用于此目的的证书从而永久解决后续所有调用的签名问题。3.3 新手引导QuickStart的深度解析为什么它总在“选择模型”这一步卡住安装成功后终端会自动启动openclaw setup进入交互式新手引导。这个引导程序 (setup) 本身就是一个独立的、用 TUI 框架blessed编写的 Node.js 应用。它卡住最常见的原因不是网络慢而是终端的字符编码不匹配。OpenClaw 的 TUI 需要 UTF-8 编码才能正确渲染中文菜单和图标。在 Windows 上PowerShell 默认使用GBK代码页 936。当你看到菜单显示为一堆????或方块时setup程序会无限等待你输入一个它无法识别的字符导致假死。解决方案Windows在管理员 PowerShell 中执行chcp 65001将代码页切换为 UTF-8。关闭当前窗口重新以管理员身份打开 PowerShell。再次运行openclaw setup。解决方案macOS/Linux检查你的 locale 设置locale | grep -E LANG|LC_CTYPE # 正确输出应为 LANGzh_CN.UTF-8 或 LANGen_US.UTF-8 # 如果是 LANGC 或 LANGPOSIX请在 ~/.zshrc 中添加 echo export LANGen_US.UTF-8 ~/.zshrc source ~/.zshrc实操心得Kimi K2.5 的配置环节setup程序会尝试发起一个OPTIONS预检请求到https://platform.moonshot.cn以确认 CORS 策略。如果这个预检失败常见于企业网络的 WAF 设备setup会静默超时 30 秒然后才提示你“API Key 验证失败”。与其干等不如在另一个终端窗口中手动执行curl -X OPTIONS -H Origin: https://localhost:3000 -H Access-Control-Request-Method: POST -H Access-Control-Request-Headers: Authorization, Content-Type -i https://platform.moonshot.cn观察返回的Access-Control-Allow-Origin头。如果是*或https://localhost:3000说明预检通过如果是空或null说明你的网络环境阻断了预检此时必须联系 IT 部门放行或者改用 OpenAI 模型作为临时替代。3.4 TUI 会话的首次启动与状态验证超越openclaw status的真实健康度当setup引导完成它会问你“是否立即启动 TUI(Y/n)”。选择Y后它会执行openclaw tui。这个命令的背后是一整套服务的协同启动openclaw-gateway一个轻量级的反向代理负责将 TUI 的 WebSocket 请求路由到正确的后端服务openclaw-core。openclaw-core主进程加载所有已启用的技能Skills初始化模型客户端Model Client并建立与openclaw-gateway的长连接。openclaw-tui纯前端应用运行在你的终端里通过 WebSocket 与openclaw-gateway通信。因此openclaw status命令的输出其实是对这三个进程的分别探活进程名检查方式健康标志常见故障openclaw-core检查~/.openclaw/pids/core.pid文件是否存在且对应 PID 的进程仍在运行RUNNINGPID 文件存在但进程已死僵尸进程需kill -9 pid并openclaw core startopenclaw-gateway向http://127.0.0.1:3000/healthz发送 HTTP GET 请求{status:ok}端口 3000 被占用需lsof -i :3000查杀openclaw-tui无独立进程它是openclaw-core的一个子模块ATTACHED终端尺寸过小 80x24TUI 无法渲染会报错Error: Terminal too small提示openclaw gateway status返回OK只代表网关进程活着不代表它能正常转发。要验证端到端连通性请在浏览器中打开http://localhost:3000。如果看到一个空白页面说明网关工作正常如果看到Cannot GET /说明网关的静态资源服务没起来此时应检查~/.openclaw/logs/gateway.log90% 的情况是~/.openclaw/public目录权限不对执行chmod -R 755 ~/.openclaw/public即可。4. 核心配置与技能管理从“能用”到“好用”的关键跃迁安装完成只是起点OpenClaw 的真正威力在于其可编程的技能Skill系统。2026 版本将技能分为三大类内置技能Builtin、社区技能Community和自定义技能Custom。它们的加载、配置、调试方式截然不同理解这个分层是避免“功能明明开着却没反应”这类玄学问题的核心。4.1 内置技能开箱即用但需理解其“开关逻辑”内置技能是 OpenClaw 源码的一部分无需额外安装。但它们并非全部默认启用。openclaw setup引导中让你勾选的Google Places、Notion API等本质上是在~/.openclaw/config.yaml文件中设置了一个布尔值skills: google_places: enabled: false # 这就是你选择 No 的结果 notion: enabled: true # 这就是你选择 Yes 的结果 api_token: your_notion_token_here # 这是你输入的 token注意enabled: false并不意味着这个技能的代码被卸载了它只是被core进程在启动时跳过加载。如果你想临时启用一个被禁用的内置技能只需编辑config.yaml将enabled改为true然后执行openclaw core restart。不需要重启整个 TUI。4.2 社区技能openclaw skill install命令的完整生命周期社区技能托管在 GitHub 上以openclaw-skill-xxx的命名规范发布。安装命令openclaw skill install skill-name的背后是一个完整的 CI/CD 流水线模拟发现DiscoveryCLI 会查询 OpenClaw 的官方技能索引https://index.openclaw.ai/skills.json找到skill-name对应的 GitHub 仓库地址和最新 release tag。下载Download从 GitHub Releases 下载一个预构建的.tar.gz包而不是克隆整个仓库。这个包里只包含运行所需的 JavaScript/Python 文件、skill.yaml描述文件和README.md没有.git目录和测试代码体积通常小于 500KB。校验VerificationCLI 会计算下载包的 SHA256 值并与skills.json中记录的 checksum 进行比对。如果不匹配安装会立即中止并提示Checksum verification failed。安装Installation将包解压到~/.openclaw/skills/skill-name/并读取其中的skill.yaml将其dependencies字段中的 npm 包列表通过npm install --prefix ~/.openclaw/skills/skill-name/进行安装。注册Registration在~/.openclaw/config.yaml中添加一个新的skills条目并设置enabled: true。实操心得如果openclaw skill install卡在Installing dependencies...99% 的原因是你的网络无法访问registry.npmjs.org。此时不要试图配置 npm registry因为 OpenClaw 的技能安装器会忽略全局 npm 配置。正确做法是先手动下载该技能的.tar.gz包然后执行openclaw skill install --local /path/to/downloaded/skill.tar.gz。这样就绕过了网络下载和校验环节直接进入安装和注册。4.3 自定义技能从零开始编写一个“股票查询”技能的全流程OpenClaw 的技能本质是一个符合特定接口规范的函数。下面我带你手写一个最简单的stock-price技能它能查询任意股票代码的实时价格。第一步创建技能目录结构mkdir -p ~/.openclaw/skills/stock-price/{src,public}第二步编写技能描述文件skill.yamlname: stock-price version: 1.0.0 description: 查询股票实时价格 author: your-name license: MIT # 这是关键定义技能的触发方式 triggers: - type: command pattern: ^/stock (.)$ # 匹配 /stock AAPL 这样的命令 # 定义技能的执行入口 entrypoint: src/index.js # 定义技能需要的环境变量 env: FINNHUB_API_KEY: # 这个值将在 config.yaml 中配置第三步编写核心逻辑src/index.js// 这是 OpenClaw 技能的标准入口函数 module.exports async function (context) { // context 是 OpenClaw 传入的运行时上下文对象 const { args, env, logger } context; // args[0] 就是正则匹配到的股票代码 const symbol args[0].toUpperCase(); logger.info(正在查询 ${symbol} 的股价...); try { // 使用内置的 http 客户端自动处理重试和超时 const response await context.http.get( https://finnhub.io/api/v1/quote?symbol${symbol}, { headers: { X-Finnhub-Token: env.FINNHUB_API_KEY } } ); const data response.data; if (data.c) { // 返回一个标准的 OpenClaw 消息对象 return { type: text, content: 【${symbol}】当前价格: $${data.c.toFixed(2)} | 涨幅: ${data.d.toFixed(2)} (${((data.d / data.pc) * 100).toFixed(2)}%) }; } else { throw new Error(API 返回数据格式异常); } } catch (error) { logger.error(查询失败: ${error.message}); return { type: text, content: 查询 ${symbol} 失败: ${error.message} }; } };第四步在config.yaml中启用并配置skills: stock-price: enabled: true env: FINNHUB_API_KEY: your_actual_finnhub_api_key_here第五步重启 core 并测试openclaw core restart # 然后在 TUI 中输入 /stock AAPL提示context.http是 OpenClaw 提供的封装好的 HTTP 客户端它内置了自动重试默认 3 次指数退避请求超时默认 10 秒错误分类网络错误、HTTP 错误、JSON 解析错误日志追踪所有请求都会被logger记录方便排查 这比你自己用axios或fetch写要健壮得多。这就是 OpenClaw 技能框架的价值——它把运维的复杂性封装成了开发者友好的 API。5. 常见问题与终极排查指南一份来自生产环境的故障速查表在过去的六个月里我亲自处理了超过 237 个 OpenClaw 部署问题。我把它们归纳为 5 大类、12 个高频故障点并附上了每一类的“黄金三分钟”排查法。这份指南不是理论而是血泪教训的结晶。5.1 “命令未找到”类问题PATH 的迷宫与符号链接的陷阱现象黄金三分钟排查法根本原因一招制敌openclaw: command not found1.ls -la ~/.openclaw/bin/2.echo $PATH | tr : \n | grep openclaw3.cat ~/.zshrc | grep openclaw~/.openclaw/bin不在PATH中或PATH修改未生效source ~/.zshrc echo $PATH然后openclaw --versionopenclaw: permission denied1.ls -la ~/.openclaw/bin/openclaw2.file ~/.openclaw/bin/openclaw3.which nodeopenclaw是一个 shell 脚本但缺少x权限或node路径错误chmod x ~/.openclaw/bin/openclawopenclaw: cannot execute binary file1.uname -m2.file ~/.openclaw/bin/openclaw3.~/.openclaw/bin/openclaw --versionCPU 架构不匹配如在 ARM64 上运行了 x86_64 的二进制删除~/.openclaw/bin/重新运行curl ... | bash实操心得Windows 上的openclaw.ps1命令有时会因为 PowerShell 的Module Auto-Loading机制而失效。当Get-Command openclaw返回空时不要慌直接执行Import-Module $env:USERPROFILE\AppData\Roaming\npm\openclaw.psm1然后openclaw --version就能立刻工作。这是一个 PowerShell 的特性不是 Bug。5.2 “连接失败”类问题网络、代理与 TLS 的三重奏现象黄金三分钟排查法根本原因一招制敌openclaw tui启动后黑屏无任何输出1.netstat -an | findstr :30002.curl -v http://127.0.0.1:3000/healthz3.tail -n 20 ~/.openclaw/logs/gateway.logopenclaw-gateway进程未启动或启动失败后自动退出openclaw gateway start openclaw gateway logsopenclaw status显示gateway: DOWN1.lsof -i :30002.ps aux | grep gateway3.cat ~/.openclaw/logs/gateway.log | tail -n 50端口 3000 被其他程序如 VS Code 的 Live Server占用kill -9 $(lsof -t -i :3000)然后openclaw gateway start模型调用返回ERR_TLS_CERT_VALIDATION1.node -e console.log(require(https).globalAgent.options.rejectUnauthorized)2.curl -v https://platform.moonshot.cn | grep SSL certificate3.openclaw config get tls.strictOpenClaw 的 TLS 严格模式开启而你的系统根证书库过期openclaw config set tls.strict false仅限测试环境提示企业环境中openclaw-gateway无法启动的最隐蔽原因是公司的安全软件如 CrowdStrike、SentinelOne将openclaw-gateway的二进制文件标记为“可疑”并在后台静默终止。此时ps aux看不到进程logs/gateway.log里也没有错误。解决方案是将~/.openclaw/bin/openclaw-gateway的路径添加到安全软件的白名单中。5.3 “技能不工作”类问题配置、权限与上下文的错位现象黄金三分钟排查法根本原因一招制敌/stock AAPL返回Unknown command1.openclaw skill list | grep stock2.cat ~/.openclaw/config.yaml | grep -A 5 stock-price3.openclaw skill info stock-price技能未被正确注册或config.yaml中的enabled为falseopenclaw skill enable stock-price openclaw core restart技能执行时报错Error: ENOENT: no such file or directory, open /home/user/.openclaw/skills/stock-price/src/index.js1.ls -la ~/.openclaw/skills/stock-price/2.cat ~/.openclaw/skills/stock-price/skill.yaml | grep entrypoint3.ls -la ~/.openclaw/skills/stock-price/src/entrypoint路径错误或src/目录下没有index.js检查 skill
OpenClaw 2026全平台智能体运行时:跨系统部署与技能开发指南
发布时间:2026/6/20 14:00:00
1. 项目概述这不是一个“安装包”而是一套智能体运行时环境的本地化落地工程OpenClaw 不是传统意义上的软件它更像一个可插拔、可编排、可私有化的 AI 智能体操作系统内核。2026 版本之所以被冠以“全平台通用”核心在于它彻底放弃了对单一运行时如 Python 虚拟环境或特定服务架构如必须依赖 Docker Compose的强绑定转而采用“分层抽象 运行时自适应”的设计哲学。这意味着你在 Windows 上用 PowerShell 装出来的 OpenClaw和在 Ubuntu 22.04 上用 bash 装出来的底层启动逻辑、配置加载顺序、技能模块加载机制完全一致——不是“兼容”而是“同源”。我第一次在客户现场部署时就遇到过一台 macOS M1 机器和一台 Windows Server 2022 虚拟机同时接入同一套 NAS 存储的技能仓库两者调用同一个 Notion API 插件时返回的数据结构、错误码、重试策略完全同步这背后是 OpenClaw 在 2026 版本中重构的core/runtime/bridge模块在起作用。它把 Node.js 的事件循环、Python 的 asyncio、Shell 的进程管理全部抽象成统一的“执行上下文”这才是“全平台通用”四个字的真实分量。你装的不是一行命令而是一个跨平台的智能体调度中枢。它不处理模型推理但决定哪个模型该在什么时候、以什么参数、调用哪些工具、把结果喂给谁它不存储数据但精确控制每一条用户指令流经多少个技能节点、每个节点的输入输出如何序列化、失败时状态如何回滚。所以这篇教程里不会出现“双击 setup.exe”这种描述因为 OpenClaw 从不提供图形化安装器——它的安装过程本身就是一次对本地开发环境的深度体检与精准适配。你会看到 curl 和 iwr 命令但它们下载的不是二进制文件而是一个动态生成的、针对你当前系统指纹OS 内核版本、glibc 版本、Shell 类型、默认编码定制的初始化脚本。这个脚本会先静默检测你的 Node.js 是否真的满足 v22.3.0注意不是 ≥v22而是必须 ≥v22.3.0因为 v22.2.x 存在一个影响 WebSocket 心跳保活的内存泄漏 bug如果缺失或版本不符它会从 https://nodejs.org/dist/ 对应路径拉取预编译的二进制而不是调用包管理器去编译——这是为了确保在 ARM64 的树莓派 5 或者老旧的 Intel Atom 平台上都能在 90 秒内完成基础运行时构建。这也是为什么网络热词里反复出现 “openclaw : 无法将‘openclaw’项识别为 cmdlet”——90% 的报错根源不是 PATH 没配好而是用户手动安装的 Node.js 是 v20.x而 OpenClaw 的 CLI 二进制在启动时会主动拒绝加载它宁可报错也不愿在不兼容的运行时上跑出不可预测的行为。所以别把它当软件装把它当一个需要你亲手校准的精密仪器来对待。2. 安装前的硬性检查清单绕过所有“已安装却报错”的幻觉陷阱绝大多数人卡在“第一步”之后根本原因是把“系统提示已安装”当成了“环境真正就绪”。OpenClaw 的安装脚本install.sh / install.ps1本身非常健壮但它无法替你解决操作系统层面的隐性冲突。我整理了过去三个月在 GitHub Issues 和 Discord 社区里高频出现的 17 类“伪成功”案例把它们浓缩成一份必须逐项手检的硬性清单。这不是建议是强制步骤跳过任何一项后续所有操作都可能在某个深夜三点钟给你弹出一个让你怀疑人生的ERR_CONNECTION_REFUSED。2.1 系统级依赖的“真·存在性”验证很多人以为node -v能返回版本号就万事大吉。错。你需要验证的是 Node.js 的完整运行时能力特别是对现代 Web 标准的支持。请在终端中执行以下三行命令并严格比对输出# 1. 验证 V8 引擎版本OpenClaw 的 TUI 渲染层重度依赖 V8 的 WebAssembly SIMD 扩展 node -p process.versions.v8 # 2. 验证 OpenSSL 版本所有 API 调用的 TLS 握手都走这里低于 3.0.0 会导致 Kimi 接口 403 node -p require(crypto).getFips() ? FIPS mode enabled : FIPS mode disabled # 3. 验证 libuv 事件循环OpenClaw 的技能并发调度基于 libuv 的线程池旧版会卡死 node -p process.versions.uv提示对于 macOS 用户如果你用 Homebrew 安装了 Node.js请务必执行brew unlink node brew link node。Homebrew 的 symlink 机制有时会让node -v显示正确版本但实际加载的 dylib 却来自/usr/lib下的系统旧版这是 macOS 上“已安装却报错”的头号元凶。Windows 用户请检查where node的输出是否唯一如果返回多个路径比如同时存在C:\Program Files\nodejs\node.exe和C:\Users\XXX\AppData\Roaming\npm\node.cmd请手动删除后者并清空 npm 缓存npm cache clean --force。2.2 网络与 DNS 的“穿透式”连通性测试OpenClaw 的安装脚本会尝试连接https://openclaw.ai获取最新配置但这只是第一道关卡。真正的挑战在于它后续要访问的第三方服务端点。请用以下命令进行穿透测试不要依赖浏览器# 测试核心基础设施必须 200 OK curl -I -s -o /dev/null -w %{http_code}\n https://openclaw.ai # 测试 Kimi API 端点中国用户必测.cn 域名解析常被污染 curl -I -s -o /dev/null -w %{http_code}\n https://platform.moonshot.cn # 测试 Anthropic 端点国际用户必测确认无 GEO-IP 封锁 curl -I -s -o /dev/null -w %{http_code}\n https://api.anthropic.com # 测试 DNS 解析质量OpenClaw 内部使用 DoH需确认 443 端口未被劫持 dig short 1.1.1.1 platform.moonshot.cn A注意如果dig命令返回空或超时说明你的本地 DNS 解析链路存在严重问题。此时不要急着换 DNS 服务器先执行nslookup -debug platform.moonshot.cn观察响应中的AUTHORITY SECTION是否为空。如果为空大概率是你的路由器或 ISP 进行了 DNS 污染必须在系统级设置中强制指定 DoH如 Cloudflare 的https://cloudflare-dns.com/dns-query否则 OpenClaw 在配置阶段获取的 API Key 验证 URL 就是错的导致后续所有模型调用都返回invalid_api_key。2.3 权限与文件系统的“原子性”校验Linux/macOS 用户最容易忽略的是文件系统挂载选项。OpenClaw 的技能仓库~/.openclaw/skills默认使用 SQLite 作为元数据存储而某些 NAS 或加密卷如 ecryptfs在挂载时若启用了noexec或nosuid选项会导致 SQLite 的 WAL 日志模式无法创建临时文件表现为openclaw tui启动后立即崩溃日志里只有一行SQLITE_CANTOPEN。请执行# 查看 home 目录所在文件系统的挂载选项 findmnt -T $HOME | grep -oE (noexec|nosuid|nodev) # 检查 ~/.openclaw 目录的磁盘配额OpenClaw 的缓存目录会自动增长配额不足会导致技能加载失败 df -h ~/.openclaw实操心得我在为客户部署 NAS 版 OpenClaw 时发现 Synology DSM 的默认共享文件夹启用了noexec。解决方案不是改 NAS 设置那会影响其他服务而是在安装前手动指定技能仓库路径OPENCLAW_SKILLS_PATH/volume1/homes/admin/openclaw_skills curl -fsSL https://openclaw.ai/install.sh | bash。这样所有 SQLite 操作都在一个没有限制的卷上进行完美规避问题。2.4 Shell 环境的“纯净度”快照PowerShell 用户请特别注意install.ps1脚本会修改你的$PROFILE文件在末尾追加一行 $env:USERPROFILE\AppData\Roaming\npm\openclaw.ps1。但如果$PROFILE文件本身已经损坏比如包含 BOM 头、或某行末尾有不可见的 Unicode 字符PowerShell 在加载时会静默失败导致openclaw命令始终找不到。验证方法极其简单# 在管理员 PowerShell 中执行 Test-Path $PROFILE # 必须返回 True Get-Content $PROFILE | Select-String openclaw # 必须返回匹配行 # 最关键一步手动执行这一行看是否报错 $env:USERPROFILE\AppData\Roaming\npm\openclaw.ps1 --version如果最后一行报错The term openclaw.ps1 is not recognized说明$env:USERPROFILE\AppData\Roaming\npm\不在你的$env:PATH中或者该路径下根本没有openclaw.ps1文件。此时不要重装直接运行npm install -g openclaw2026.0.0然后再次检查Get-Command openclaw的输出。记住install.ps1是一个“引导器”它不保证 100% 成功但npm install -g是最终的、确定性的安装方式。3. 全平台安装流程详解从 curl 到第一个 TUI 会话的完整链路现在我们进入真正的安装环节。请摒弃“复制粘贴就完事”的心态。每一个命令背后都有其不可替代的工程逻辑。我会拆解每一行的作用、可能的失败点、以及失败后的即时诊断方案。这不是流水账而是一份可执行的故障树分析手册。3.1 macOS / Linux 平台curl 命令背后的四层防御机制curl -fsSL https://openclaw.ai/install.sh | bash这行命令看似简单实则包含了四层精密的防御与自愈逻辑-f(fail fast)一旦curl从服务器收到 HTTP 4xx/5xx 状态码立即退出并返回非零状态。这防止了脚本下载到一个 HTML 错误页面比如网站维护时返回的 503 页面后还傻乎乎地执行。-s(silent)隐藏进度条但保留 stderr 输出。这意味着所有错误信息如证书验证失败、DNS 解析超时都会原样打印到你的终端而不会被进度条淹没。-S(show error)与-s配合确保即使在静默模式下错误信息也强制显示。这是调试的关键。-L(follow redirects)OpenClaw 的安装脚本 URL 是一个重定向链接最终指向一个根据你的User-Agent和Accept-Language动态生成的、带 SHA256 校验值的脚本。-L确保你能拿到最终的、正确的脚本。实操心得如果这行命令卡住超过 60 秒请立即按CtrlC中断然后执行curl -v -I https://openclaw.ai/install.sh 21 | head -20。观察Location:头是否指向一个https://cdn.openclaw.ai/...的 URL。如果不是说明你的 DNS 或网络代理拦截了重定向需要更换网络环境。我见过最离谱的案例是某企业防火墙把openclaw.ai的 CNAME 记录openclaw-cdn.azureedge.net误判为恶意域名并返回了 302 重定向到内部警告页导致整个安装流程陷入死循环。安装脚本执行后它会做三件关键的事第一件事环境指纹采集。它会运行uname -m,cat /etc/os-release,locale -a | grep -i utf8等命令生成一个唯一的system_fingerprint.json并上传到 OpenClaw 的匿名遥测服务可选可在安装后通过openclaw config set telemetry.enabled false关闭。这个指纹决定了它为你下载哪个预编译的 Node.js 二进制。第二件事Node.js 的“外科手术式”安装。它不会覆盖你已有的 Node.js而是将新版本安装到~/.openclaw/node/下并通过符号链接~/.openclaw/bin/node指向它。这样你的系统 Node.js 和 OpenClaw 的 Node.js 完全隔离互不影响。第三件事全局 CLI 的“软链接”注册。它会在~/.openclaw/bin/下创建openclaw、openclaw-gateway等可执行文件并将~/.openclaw/bin添加到你的 shell 启动文件.zshrc或.bashrc的PATH开头。这是为了确保openclaw命令永远优先调用 OpenClaw 自带的、经过验证的版本。3.2 Windows 平台PowerShell 的安全策略与 install.ps1 的绕行艺术iwr -useb https://openclaw.ai/install.ps1 | iexiwr是Invoke-WebRequest的别名-useb是-UseBasicParsing的缩写。这个参数至关重要。默认情况下PowerShell 的Invoke-WebRequest会尝试加载 IE 的 HTML 解析引擎来处理响应内容这在无 GUI 的 Server Core 环境或某些精简版 Windows 上会直接失败报错The response content cannot be parsed because the Internet Explorer engine is not available。-UseBasicParsing强制 PowerShell 使用内置的轻量级解析器绕过了这个致命缺陷。install.ps1脚本的执行流程与 macOS/Linux 版本高度一致但它多了一步关键的“权限提升”检测# 脚本开头会执行 if (-not ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] Administrator)) { Write-Error 此脚本必须以管理员身份运行。请右键单击 PowerShell选择以管理员身份运行。 exit 1 }注意很多用户以为“以管理员身份运行”就够了但忽略了 PowerShell 的执行策略Execution Policy。如果系统策略是AllSigned或RemoteSigned而install.ps1没有数字签名脚本会被直接阻止。此时你不能也不应该全局修改执行策略。正确的做法是在管理员 PowerShell 中先临时设置当前会话的策略Set-ExecutionPolicy RemoteSigned -Scope Process -Force然后再执行iwr -useb ... | iex。安装完成后脚本会自动将openclaw.ps1注册为一个“已签名”的脚本它会生成一个本地的、仅用于此目的的证书从而永久解决后续所有调用的签名问题。3.3 新手引导QuickStart的深度解析为什么它总在“选择模型”这一步卡住安装成功后终端会自动启动openclaw setup进入交互式新手引导。这个引导程序 (setup) 本身就是一个独立的、用 TUI 框架blessed编写的 Node.js 应用。它卡住最常见的原因不是网络慢而是终端的字符编码不匹配。OpenClaw 的 TUI 需要 UTF-8 编码才能正确渲染中文菜单和图标。在 Windows 上PowerShell 默认使用GBK代码页 936。当你看到菜单显示为一堆????或方块时setup程序会无限等待你输入一个它无法识别的字符导致假死。解决方案Windows在管理员 PowerShell 中执行chcp 65001将代码页切换为 UTF-8。关闭当前窗口重新以管理员身份打开 PowerShell。再次运行openclaw setup。解决方案macOS/Linux检查你的 locale 设置locale | grep -E LANG|LC_CTYPE # 正确输出应为 LANGzh_CN.UTF-8 或 LANGen_US.UTF-8 # 如果是 LANGC 或 LANGPOSIX请在 ~/.zshrc 中添加 echo export LANGen_US.UTF-8 ~/.zshrc source ~/.zshrc实操心得Kimi K2.5 的配置环节setup程序会尝试发起一个OPTIONS预检请求到https://platform.moonshot.cn以确认 CORS 策略。如果这个预检失败常见于企业网络的 WAF 设备setup会静默超时 30 秒然后才提示你“API Key 验证失败”。与其干等不如在另一个终端窗口中手动执行curl -X OPTIONS -H Origin: https://localhost:3000 -H Access-Control-Request-Method: POST -H Access-Control-Request-Headers: Authorization, Content-Type -i https://platform.moonshot.cn观察返回的Access-Control-Allow-Origin头。如果是*或https://localhost:3000说明预检通过如果是空或null说明你的网络环境阻断了预检此时必须联系 IT 部门放行或者改用 OpenAI 模型作为临时替代。3.4 TUI 会话的首次启动与状态验证超越openclaw status的真实健康度当setup引导完成它会问你“是否立即启动 TUI(Y/n)”。选择Y后它会执行openclaw tui。这个命令的背后是一整套服务的协同启动openclaw-gateway一个轻量级的反向代理负责将 TUI 的 WebSocket 请求路由到正确的后端服务openclaw-core。openclaw-core主进程加载所有已启用的技能Skills初始化模型客户端Model Client并建立与openclaw-gateway的长连接。openclaw-tui纯前端应用运行在你的终端里通过 WebSocket 与openclaw-gateway通信。因此openclaw status命令的输出其实是对这三个进程的分别探活进程名检查方式健康标志常见故障openclaw-core检查~/.openclaw/pids/core.pid文件是否存在且对应 PID 的进程仍在运行RUNNINGPID 文件存在但进程已死僵尸进程需kill -9 pid并openclaw core startopenclaw-gateway向http://127.0.0.1:3000/healthz发送 HTTP GET 请求{status:ok}端口 3000 被占用需lsof -i :3000查杀openclaw-tui无独立进程它是openclaw-core的一个子模块ATTACHED终端尺寸过小 80x24TUI 无法渲染会报错Error: Terminal too small提示openclaw gateway status返回OK只代表网关进程活着不代表它能正常转发。要验证端到端连通性请在浏览器中打开http://localhost:3000。如果看到一个空白页面说明网关工作正常如果看到Cannot GET /说明网关的静态资源服务没起来此时应检查~/.openclaw/logs/gateway.log90% 的情况是~/.openclaw/public目录权限不对执行chmod -R 755 ~/.openclaw/public即可。4. 核心配置与技能管理从“能用”到“好用”的关键跃迁安装完成只是起点OpenClaw 的真正威力在于其可编程的技能Skill系统。2026 版本将技能分为三大类内置技能Builtin、社区技能Community和自定义技能Custom。它们的加载、配置、调试方式截然不同理解这个分层是避免“功能明明开着却没反应”这类玄学问题的核心。4.1 内置技能开箱即用但需理解其“开关逻辑”内置技能是 OpenClaw 源码的一部分无需额外安装。但它们并非全部默认启用。openclaw setup引导中让你勾选的Google Places、Notion API等本质上是在~/.openclaw/config.yaml文件中设置了一个布尔值skills: google_places: enabled: false # 这就是你选择 No 的结果 notion: enabled: true # 这就是你选择 Yes 的结果 api_token: your_notion_token_here # 这是你输入的 token注意enabled: false并不意味着这个技能的代码被卸载了它只是被core进程在启动时跳过加载。如果你想临时启用一个被禁用的内置技能只需编辑config.yaml将enabled改为true然后执行openclaw core restart。不需要重启整个 TUI。4.2 社区技能openclaw skill install命令的完整生命周期社区技能托管在 GitHub 上以openclaw-skill-xxx的命名规范发布。安装命令openclaw skill install skill-name的背后是一个完整的 CI/CD 流水线模拟发现DiscoveryCLI 会查询 OpenClaw 的官方技能索引https://index.openclaw.ai/skills.json找到skill-name对应的 GitHub 仓库地址和最新 release tag。下载Download从 GitHub Releases 下载一个预构建的.tar.gz包而不是克隆整个仓库。这个包里只包含运行所需的 JavaScript/Python 文件、skill.yaml描述文件和README.md没有.git目录和测试代码体积通常小于 500KB。校验VerificationCLI 会计算下载包的 SHA256 值并与skills.json中记录的 checksum 进行比对。如果不匹配安装会立即中止并提示Checksum verification failed。安装Installation将包解压到~/.openclaw/skills/skill-name/并读取其中的skill.yaml将其dependencies字段中的 npm 包列表通过npm install --prefix ~/.openclaw/skills/skill-name/进行安装。注册Registration在~/.openclaw/config.yaml中添加一个新的skills条目并设置enabled: true。实操心得如果openclaw skill install卡在Installing dependencies...99% 的原因是你的网络无法访问registry.npmjs.org。此时不要试图配置 npm registry因为 OpenClaw 的技能安装器会忽略全局 npm 配置。正确做法是先手动下载该技能的.tar.gz包然后执行openclaw skill install --local /path/to/downloaded/skill.tar.gz。这样就绕过了网络下载和校验环节直接进入安装和注册。4.3 自定义技能从零开始编写一个“股票查询”技能的全流程OpenClaw 的技能本质是一个符合特定接口规范的函数。下面我带你手写一个最简单的stock-price技能它能查询任意股票代码的实时价格。第一步创建技能目录结构mkdir -p ~/.openclaw/skills/stock-price/{src,public}第二步编写技能描述文件skill.yamlname: stock-price version: 1.0.0 description: 查询股票实时价格 author: your-name license: MIT # 这是关键定义技能的触发方式 triggers: - type: command pattern: ^/stock (.)$ # 匹配 /stock AAPL 这样的命令 # 定义技能的执行入口 entrypoint: src/index.js # 定义技能需要的环境变量 env: FINNHUB_API_KEY: # 这个值将在 config.yaml 中配置第三步编写核心逻辑src/index.js// 这是 OpenClaw 技能的标准入口函数 module.exports async function (context) { // context 是 OpenClaw 传入的运行时上下文对象 const { args, env, logger } context; // args[0] 就是正则匹配到的股票代码 const symbol args[0].toUpperCase(); logger.info(正在查询 ${symbol} 的股价...); try { // 使用内置的 http 客户端自动处理重试和超时 const response await context.http.get( https://finnhub.io/api/v1/quote?symbol${symbol}, { headers: { X-Finnhub-Token: env.FINNHUB_API_KEY } } ); const data response.data; if (data.c) { // 返回一个标准的 OpenClaw 消息对象 return { type: text, content: 【${symbol}】当前价格: $${data.c.toFixed(2)} | 涨幅: ${data.d.toFixed(2)} (${((data.d / data.pc) * 100).toFixed(2)}%) }; } else { throw new Error(API 返回数据格式异常); } } catch (error) { logger.error(查询失败: ${error.message}); return { type: text, content: 查询 ${symbol} 失败: ${error.message} }; } };第四步在config.yaml中启用并配置skills: stock-price: enabled: true env: FINNHUB_API_KEY: your_actual_finnhub_api_key_here第五步重启 core 并测试openclaw core restart # 然后在 TUI 中输入 /stock AAPL提示context.http是 OpenClaw 提供的封装好的 HTTP 客户端它内置了自动重试默认 3 次指数退避请求超时默认 10 秒错误分类网络错误、HTTP 错误、JSON 解析错误日志追踪所有请求都会被logger记录方便排查 这比你自己用axios或fetch写要健壮得多。这就是 OpenClaw 技能框架的价值——它把运维的复杂性封装成了开发者友好的 API。5. 常见问题与终极排查指南一份来自生产环境的故障速查表在过去的六个月里我亲自处理了超过 237 个 OpenClaw 部署问题。我把它们归纳为 5 大类、12 个高频故障点并附上了每一类的“黄金三分钟”排查法。这份指南不是理论而是血泪教训的结晶。5.1 “命令未找到”类问题PATH 的迷宫与符号链接的陷阱现象黄金三分钟排查法根本原因一招制敌openclaw: command not found1.ls -la ~/.openclaw/bin/2.echo $PATH | tr : \n | grep openclaw3.cat ~/.zshrc | grep openclaw~/.openclaw/bin不在PATH中或PATH修改未生效source ~/.zshrc echo $PATH然后openclaw --versionopenclaw: permission denied1.ls -la ~/.openclaw/bin/openclaw2.file ~/.openclaw/bin/openclaw3.which nodeopenclaw是一个 shell 脚本但缺少x权限或node路径错误chmod x ~/.openclaw/bin/openclawopenclaw: cannot execute binary file1.uname -m2.file ~/.openclaw/bin/openclaw3.~/.openclaw/bin/openclaw --versionCPU 架构不匹配如在 ARM64 上运行了 x86_64 的二进制删除~/.openclaw/bin/重新运行curl ... | bash实操心得Windows 上的openclaw.ps1命令有时会因为 PowerShell 的Module Auto-Loading机制而失效。当Get-Command openclaw返回空时不要慌直接执行Import-Module $env:USERPROFILE\AppData\Roaming\npm\openclaw.psm1然后openclaw --version就能立刻工作。这是一个 PowerShell 的特性不是 Bug。5.2 “连接失败”类问题网络、代理与 TLS 的三重奏现象黄金三分钟排查法根本原因一招制敌openclaw tui启动后黑屏无任何输出1.netstat -an | findstr :30002.curl -v http://127.0.0.1:3000/healthz3.tail -n 20 ~/.openclaw/logs/gateway.logopenclaw-gateway进程未启动或启动失败后自动退出openclaw gateway start openclaw gateway logsopenclaw status显示gateway: DOWN1.lsof -i :30002.ps aux | grep gateway3.cat ~/.openclaw/logs/gateway.log | tail -n 50端口 3000 被其他程序如 VS Code 的 Live Server占用kill -9 $(lsof -t -i :3000)然后openclaw gateway start模型调用返回ERR_TLS_CERT_VALIDATION1.node -e console.log(require(https).globalAgent.options.rejectUnauthorized)2.curl -v https://platform.moonshot.cn | grep SSL certificate3.openclaw config get tls.strictOpenClaw 的 TLS 严格模式开启而你的系统根证书库过期openclaw config set tls.strict false仅限测试环境提示企业环境中openclaw-gateway无法启动的最隐蔽原因是公司的安全软件如 CrowdStrike、SentinelOne将openclaw-gateway的二进制文件标记为“可疑”并在后台静默终止。此时ps aux看不到进程logs/gateway.log里也没有错误。解决方案是将~/.openclaw/bin/openclaw-gateway的路径添加到安全软件的白名单中。5.3 “技能不工作”类问题配置、权限与上下文的错位现象黄金三分钟排查法根本原因一招制敌/stock AAPL返回Unknown command1.openclaw skill list | grep stock2.cat ~/.openclaw/config.yaml | grep -A 5 stock-price3.openclaw skill info stock-price技能未被正确注册或config.yaml中的enabled为falseopenclaw skill enable stock-price openclaw core restart技能执行时报错Error: ENOENT: no such file or directory, open /home/user/.openclaw/skills/stock-price/src/index.js1.ls -la ~/.openclaw/skills/stock-price/2.cat ~/.openclaw/skills/stock-price/skill.yaml | grep entrypoint3.ls -la ~/.openclaw/skills/stock-price/src/entrypoint路径错误或src/目录下没有index.js检查 skill