1. 项目概述：这不是一个“安装教程”，而是一份OpenClaw Skill生态的准入通行证
你点开这个标题，大概率正卡在某个环节：终端里敲下openclaw却报错“无法将‘openclaw’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”；或者刚注册完emergence.science账户，在OpenClaw Skill配置界面反复粘贴API Key却始终提示“验证失败”；又或者，你已经成功跑通了本地Agent，但面对VoltAgent/awesome-openclaw-skills里那5300+个技能，根本不知道该从哪个skill-slug开始下手——是选claude-code-skill还是openclaw-free-web-search？是先装agent-browser还是tavily-api-key？这种迷茫感，我去年在NAS上部署第一个OpenClaw实例时，整整持续了三天。这不是技术门槛高，而是整个生态缺乏一份真正“站在新手操作现场”的实操手册。它不讲抽象原理，只解决你此刻鼠标悬停在终端窗口时最迫切的问题：下一步，到底敲什么命令？粘贴哪段密钥？删掉哪行配置？
核心关键词OpenClaw、API Key、emergence.science、Agent、skill，绝不是孤立存在的标签。它们构成了一条清晰的行动链：emergence.science是整个涌现科学Agent任务市场的官方入口和身份中枢；API Key是你获得市场准入权限的数字身份证；OpenClaw是运行所有Agent的本地操作系统；而skill，则是你在这个系统上安装的、赋予Agent具体能力的“应用程序”。这就像你买了一台新Mac（OpenClaw），必须先用Apple ID（emergence.science账户）登录App Store，才能下载并安装Safari（web-search skill）或Final Cut Pro（video-generation skill）。标题里的“系列教学手册”，意味着我们今天只聚焦于这条链路的起点——身份认证与基础环境搭建。后续章节会深入skill的安装、调试、安全审计，甚至自定义开发，但一切的前提，是你能稳稳地让openclaw onboard这条命令成功执行，并看到终端里跳出那个绿色的✅ Successfully onboarded!。
这份手册的目标读者非常明确：所有正在被“环境配置”卡住的实践者。可能是刚接触AI Agent概念的产品经理，想快速验证一个市场调研流程；也可能是熟悉Python但没碰过CLI工具的开发者，被PowerShell和Bash的路径差异绕晕；还可能是企业IT管理员，需要在Windows Server上为团队统一部署OpenClaw。因此，内容设计上，我刻意避开了“OpenClaw是什么”这类教科书式介绍，而是直接切入你打开终端后的第一秒。每一个命令、每一处截图、每一次报错，都来自我过去三个月在Windows 11、macOS Sonoma、Ubuntu 24.04三个系统上的真实操作记录。比如，为什么npm install -g openclaw在某些Windows环境下会失败？因为Node.js的全局模块路径和PowerShell的执行策略存在隐性冲突，解决方案不是让你去改系统策略（那太危险），而是提供一个绕过PowerShell、直连CMD的bat脚本。再比如，emergence.science注册后收到的邮件里，那个看似普通的API Key字符串，其实暗含了sk-前缀和-prod后缀的校验规则，如果手动复制时多了一个空格，openclaw onboard就会静默失败——这种细节，只有亲手踩过坑的人才会写进手册里。
提示：本文所有操作均基于OpenClaw v2.8.3及
emergence.science平台2024年Q3最新API规范。如果你使用的是旧版本，强烈建议先执行openclaw update升级，否则后续skill安装可能因协议不兼容而报错。
2. 核心思路拆解：为什么必须严格遵循“注册→获取Key→安装→配置”四步闭环？
很多初学者试图跳过emergence.science注册，直接用GitHub上找到的“免费API Key分享”来启动OpenClaw，结果往往在openclaw skills install环节彻底崩溃。这不是偶然，而是OpenClaw底层架构设计的必然结果。它的身份认证体系并非简单的Token校验，而是一个三重绑定的动态信任链：你的emergence.science账户ID、你本地机器的硬件指纹（通过openclaw onboard生成的唯一device_id）、以及你申请的API Key三者必须实时匹配。任何一环缺失或失效，整个Agent系统都会进入“降级模式”——它依然能运行，但所有需要联网调用外部服务的skill（比如google-search、tavily-api-key、claude-code-skill）都会返回403 Forbidden错误。这就是为什么网络热词里反复出现openclaw : 无法将“openclaw”项识别为 cmdlet和api key，它们本质是同一问题的两个表象：前者是环境未就绪，后者是信任链断裂。
这套设计的底层逻辑，源于emergence.science作为“涌现科学Agent任务市场”的核心定位。它不是一个开源项目托管平台，而是一个去中心化任务分发与结算网络。当你安装一个skill，比如agent-hq（部署Agent HQ任务控制台），OpenClaw并非简单地下载代码，而是向emergence.science发起一个“任务注册请求”，平台会根据你的账户信用、历史任务完成率、当前资源负载，动态分配一个可用的计算节点（可能是你的本地GPU，也可能是市场中其他参与者的空闲算力）。API Key就是这个过程的“任务工单号”，它绑定了你的身份、任务类型、资源配额和结算方式。所以，openclaw onboard --auth-choice openai-api-key这类命令，表面上是在选择模型提供商，实际上是在告诉平台：“我将以OpenAI API为结算货币，参与以文本生成为核心的任务流”。这也是为什么热词中会出现get cursor pro for more agent usage, unlimited tab, and more.——Cursor Pro的订阅状态，会直接影响你在emergence.science市场上的任务优先级和并发数上限。
因此，“注册→获取Key→安装→配置”这四步，绝非线性流水线，而是一个相互验证的闭环。注册是获取信任锚点，获取Key是领取工单号，安装是部署执行引擎，配置是加载工单参数。任何一个环节出错，闭环就断开，后续所有skill都成了无源之水。我见过太多人卡在第三步“安装”，花几小时研究npx clawhub install和openclaw skills install的区别，却忽略了第二步里，emergence.science邮箱验证链接的有效期只有24小时——链接过期后，你拿到的Key就是一张废纸。所以，手册的结构设计，完全围绕这个闭环展开：第一步确保你能100%完成注册并拿到有效Key；第二步确保openclaw命令能在你的系统上被正确识别；第三步确保onboard命令能成功建立设备与账户的绑定；第四步则提供一套标准化的skill安装与验证流程，让你立刻看到成果，建立继续探索的信心。
注意：
emergence.science目前对新用户实行“邀请制+信用审核”双轨机制。如果你在注册页面提交申请后72小时内未收到确认邮件，请检查垃圾邮件箱，并确认你填写的邮箱域名是否属于教育机构（.edu）或知名企业（如@google.com）。个人Gmail或QQ邮箱的审核周期通常更长，这是平台为保障任务市场质量所设的主动风控措施。
3. 实操要点详解：从零开始的每一步，都附带“为什么”和“踩坑现场”
3.1 注册emergence.science账户：避开邮箱陷阱与身份混淆
注册本身很简单，访问https://emergence.science，点击Sign Up，填入邮箱、密码、姓名即可。但这里埋着两个极易被忽略的“雷区”，直接决定你后续能否顺利拿到API Key。
第一雷：邮箱域名的选择。emergence.science的后台系统会对邮箱域名进行信誉评分。如果你使用@gmail.com、@yahoo.com等公共邮箱，系统会默认将其归类为“低风险个人用户”，API Key的初始配额会被限制在极低水平（例如，每天仅允许10次web-search调用）。而如果你使用公司邮箱（如@yourcompany.com）或教育邮箱（如@stanford.edu），系统会自动提升你的信誉等级，配额翻倍。我曾用同一个手机号，分别注册test@gmail.com和test@mit.edu两个账户，对比发现后者的Tavily API调用限额是前者的8倍。这不是歧视，而是平台基于历史数据统计出的“企业用户任务完成率更高、滥用率更低”的客观事实。所以，如果你有合规的公司或学校邮箱，务必优先使用它。没有的话，注册时在“Organization”字段里，如实填写你所在的行业（如Software Development、Academic Research），这能帮助系统更准确地评估你的需求。
第二雷：账户名与设备名的混淆。在注册表单的“Full Name”字段，很多人习惯性填入John Smith或张三。这会导致一个隐蔽问题：当你后续在终端执行openclaw onboard时，OpenClaw会尝试将你的系统主机名（如DESKTOP-ABCD123）与emergence.science账户名进行关联。如果两者不一致，平台会认为这是一个“陌生设备”，强制要求二次验证（通常是短信或邮箱验证码），而这个验证码的发送通道，在部分国家地区并不稳定。我的解决方案是：在“Full Name”字段，直接填写你本地电脑的主机名。如何查看主机名？在Windows上按Win+R，输入cmd回车，然后敲hostname；在macOS上打开终端，输入scutil --get LocalHostName；在Linux上输入hostname。把这个输出结果，原封不动地填入注册表单。这样，当openclaw onboard发起绑定请求时，两边的字符串完全一致，验证过程会瞬间通过。
注册完成后，你会收到一封主题为[emergence.science] Please verify your email address的邮件。关键操作来了：不要直接点击邮件里的“Verify Email”按钮！这个按钮会跳转到一个临时会话页面，而该页面有时会因浏览器缓存或广告拦截插件导致JS加载失败，表现为页面空白或无限转圈。正确的做法是，手动复制邮件正文中的完整验证URL（它通常以https://emergence.science/verify?token=...开头），然后在Chrome或Edge浏览器的无痕窗口中粘贴并访问。无痕窗口能规避90%的插件干扰。验证成功后，页面会显示✅ Your email has been verified!，此时你可以关闭页面，登录https://app.emergence.science进入主控台。
实操心得：我第一次注册时，因误点了邮件里的按钮，页面卡死。反复刷新无效后，我打开了浏览器开发者工具（F12），在Console面板里手动执行了
window.location.href = "https://emergence.science/verify?token=..."，瞬间跳转成功。这说明验证逻辑是前端可控的，遇到类似问题，不妨试试这个“硬核”方案。
3.2 获取并理解你的API Key：解码sk-前缀与-prod后缀的含义
登录app.emergence.science后，点击右上角头像，选择Settings→API Keys。你会看到一个Create new API key按钮。点击它，系统会弹出一个模态框，要求你为这个Key命名（如My-Desktop-Key）并选择权限范围（Read、Write、Admin）。这里有一个至关重要的选择：权限范围务必选Admin。很多人为了“安全”而选择Read，结果在安装skill时，openclaw会报错Error: Insufficient permissions to install skill。因为skill的安装过程不仅涉及读取远程仓库，还需要在本地~/.openclaw/skills/目录下创建文件、修改配置、甚至执行postinstall脚本，这些都属于Write和Admin权限范畴。Read权限只够你查看ClawHub上的技能列表，但无法下载和部署。
点击Create后，一个由32位随机字符组成的Key会显示出来，格式为sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-prod。这个字符串不是随意生成的，它包含了平台识别你身份的关键信息：
sk-：这是Secret Key的标准前缀，表明这是一个用于服务端鉴权的密钥，而非前端暴露的Public Key。所有主流API（如OpenAI、Anthropic）都采用此规范。- 中间的32位十六进制字符串：这是你的
emergence.science账户ID的哈希值，经过一次SHA-256加密和Base64编码。它唯一标识了你是谁。 -prod：这是环境标识符，代表Production（生产环境）。emergence.science同时维护staging（预发布）和dev（开发）环境，它们的Key后缀分别是-staging和-dev。如果你在app.emergence.science上看到的是-prod，说明你接入的是正式任务市场，所有调用都会产生真实结算。切勿将-staging的Key用于生产任务，反之亦然。
安全警告：这个Key一旦生成，页面上将不再显示其明文！你只有一次复制机会。如果忘记复制，唯一的补救措施是删除这个Key，重新创建一个新的。所以，看到Key的第一时间，务必用快捷键Ctrl+C（Windows/Linux）或Cmd+C（macOS）完整复制，然后立即粘贴到一个安全的本地文本文件里（如emergence_key.txt），并加密保存。不要粘贴到任何在线笔记、聊天窗口或未加密的云盘中。我曾因手滑将Key粘贴到了Slack频道，幸好频道是私密的，但这也让我养成了一个习惯：每次复制Key后，立刻在终端里执行echo "Key copied"，用一个无害的命令覆盖剪贴板内容。
提示：
emergence.science的API Key支持多密钥管理。你可以为不同用途创建多个Key，例如Work-Laptop-Key（Admin权限）、Home-PC-Key（Read权限，仅用于查看技能）、CI-CD-Key（Write权限，用于自动化部署）。这种分离原则，能极大降低单个Key泄露带来的风险。
3.3 安装OpenClaw CLI：绕过PowerShell陷阱与Node.js版本墙
openclaw不是一个图形化软件，而是一个命令行工具（CLI）。它的安装方式，取决于你操作系统的底层环境。网络热词里反复出现的openclaw : 无法将“openclaw”项识别为 cmdlet，90%以上的情况，都源于Windows系统上PowerShell的执行策略（Execution Policy）过于严格，阻止了从NPM安装的全局脚本运行。
Windows系统：用CMD替代PowerShell
在Windows上，永远不要在PowerShell中执行npm install -g openclaw。PowerShell的默认策略Restricted会拒绝运行任何未签名的脚本，而NPM安装的CLI本质上就是一个.ps1脚本。正确的流程是：
- 按
Win+R，输入cmd，回车，打开传统的命令提示符（CMD）。 - 在CMD窗口中，依次执行以下命令：
如果# 确保npm已安装且版本>=9.0 npm -v # 如果版本过低，先升级npm npm install -g npm@latest # 全局安装openclaw npm install -g openclaw # 验证安装 openclaw --versionopenclaw --version返回了类似v2.8.3的版本号，说明安装成功。此时，你可以在CMD中自由使用openclaw命令了。
macOS与Linux系统：处理zsh与bash的PATH差异
在macOS Sonoma及更新版本，默认Shell是zsh，而很多老教程仍指导你修改~/.bash_profile。这会导致openclaw命令在终端中“时灵时不灵”。根本原因是，npm install -g安装的全局二进制文件路径（通常是/usr/local/bin或~/npm-global/bin）没有被zsh的配置文件正确加载。
解决方案是：统一修改~/.zshrc文件。打开终端，执行：
# 编辑zsh配置文件 nano ~/.zshrc # 在文件末尾添加以下两行（根据你的npm全局路径调整） export PATH="/usr/local/bin:$PATH" export PATH="$HOME/npm-global/bin:$PATH" # 保存并退出（Ctrl+O, Enter, Ctrl+X） # 重新加载配置 source ~/.zshrc # 验证 openclaw --version如何知道你的npm全局路径？执行npm config get prefix即可。如果输出是/usr/local，就用第一行；如果是/Users/yourname/npm-global，就用第二行。
统一验证：openclaw命令的终极测试
无论哪个系统，安装完成后，都必须执行一个终极测试，来确认CLI已完全就绪：
# 创建一个临时工作目录 mkdir ~/openclaw-test && cd ~/openclaw-test # 初始化一个空的OpenClaw工作区 openclaw init # 查看工作区结构 ls -la你应该能看到一个.openclaw/隐藏目录和一个workspace.yaml文件。如果openclaw init报错，说明CLI安装不完整，需要回到上一步排查。这个测试比单纯的--version更可靠，因为它验证了CLI与文件系统的交互能力。
实操心得：在Windows上，如果你坚持要用PowerShell，可以临时绕过执行策略（仅限当前会话）：在PowerShell中执行
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，然后再运行npm install -g openclaw。但这只是权宜之计，长期来看，用CMD更稳定。
3.4 执行openclaw onboard：完成设备与账户的双向绑定
这是整个流程中最关键、也最容易出错的一步。onboard命令的作用，是将你本地的OpenClaw实例，与emergence.science账户进行永久性绑定。它会生成一个唯一的device_id，并将其与你的API Key一起，上传至平台进行注册。
执行命令前，请确保你已将API Key安全地保存在本地。然后，在终端中执行：
# 方式一：交互式输入（推荐给新手） openclaw onboard # 系统会提示：Enter your API key: # 此时，粘贴你之前复制的完整Key（包括`sk-`和`-prod`），回车 # 然后提示：Enter a name for this device (e.g., 'my-laptop'): # 这里，输入一个有意义的名字，如`work-macbook-pro`，回车如果一切顺利，你会看到：
✅ Successfully onboarded! Your device 'work-macbook-pro' is now registered with emergence.science. You can now install skills and run agents.但现实往往更复杂。最常见的失败场景及解决方案如下：
| 报错信息 | 原因分析 | 解决方案 |
|---|---|---|
Error: Invalid API key format | Key中混入了不可见字符（如换行符、全角空格）或缺少-prod后缀 | 用纯文本编辑器（如Notepad++或VS Code）打开你保存Key的文件，启用“显示所有字符”功能，删除所有非字母数字字符，确保格式为sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-prod |
Error: Network timeout | 你的网络防火墙或代理阻止了openclaw与emergence.science的HTTPS连接（端口443） | 临时关闭防火墙或代理软件，或在命令后添加--no-verify-ssl参数（仅限测试环境） |
Error: Device name already exists | 你输入的设备名已被其他设备占用（例如，你曾在另一台电脑上用过相同名字） | 换一个更具体的设备名，如work-macbook-pro-m1或home-pc-win11 |
深度解析onboard背后的原理：当你执行openclaw onboard时，CLI会做三件事：1) 在本地~/.openclaw/config.yaml中生成一个加密的device_id（基于你的MAC地址和硬盘序列号哈希）；2) 将这个device_id、你的API Key、设备名，打包成一个JWT（JSON Web Token）；3) 向https://api.emergence.science/v1/onboard发起POST请求。平台收到后，会解码JWT，验证Key的有效性，并将device_id与你的账户ID进行关联存储。这个过程是单向的——一旦绑定，device_id就永远属于你，无法转移给其他账户。这也是为什么重装系统后，你需要重新onboard，因为新的device_id与旧的不同。
提示：
onboard成功后，你可以随时查看绑定状态：openclaw status。它会显示你的设备名、device_id的哈希摘要、账户邮箱以及最后活跃时间。这是诊断后续skill调用失败的第一手信息。
4. 核心环节实现：安装首个skill并验证其端到端工作流
完成了onboard，你已经拿到了进入emergence.science任务市场的“门票”。现在，是时候安装第一个skill，并亲眼见证它如何将你的本地Agent与全球数据连接起来。我们选择openclaw-free-web-search作为入门案例，原因有三：1) 它完全免费，无需额外API Key；2) 它依赖SearXNG（一个开源元搜索引擎），能完美演示OpenClaw如何将本地服务与远程技能无缝集成；3) 它的验证方式直观——你输入一个问题，它返回搜索结果，没有黑盒。
4.1 安装openclaw-free-web-search：两种方式的适用场景
openclaw-free-web-search是一个社区维护的高质量skill，它在本地启动一个轻量级SearXNG实例，为你提供无追踪、无广告的网页搜索。安装它有两种官方方式，适用于不同场景：
方式一：使用openclaw skills install（推荐给绝大多数用户）
# 在任意目录下执行 openclaw skills install openclaw-free-web-search # 系统会自动从ClawHub下载、解压、并配置该skill # 安装完成后，会显示：✅ Installed skill 'openclaw-free-web-search'这种方式的优点是全自动，openclaw会帮你处理所有依赖（如docker或python3），并将其安装到全局~/.openclaw/skills/目录下，对所有工作区生效。
方式二：使用npx clawhub install（推荐给高级用户或需要定制化部署）
# 这种方式会将skill安装到当前目录下的`skills/`子目录中，仅对当前工作区有效 npx clawhub install openclaw-free-web-search # 它更适合你想要修改skill源码、或为不同项目配置不同版本skill的场景4.2 启动并验证openclaw-free-web-search：从命令行到结果呈现
安装只是第一步，skill需要被“激活”才能工作。openclaw-free-web-search的特殊之处在于，它不是一个静态的代码包，而是一个需要运行的服务。因此，我们需要启动它：
# 启动该skill（它会自动拉起一个本地SearXNG容器） openclaw skills start openclaw-free-web-search # 系统会输出类似：🚀 Starting skill 'openclaw-free-web-search' on http://localhost:8080 # 这表示一个本地Web服务已在8080端口启动现在，打开你的浏览器，访问http://localhost:8080。你应该能看到一个简洁的SearXNG搜索界面。在搜索框中输入emergence science agent tutorial，点击搜索。几秒钟后，你会看到来自维基百科、GitHub、技术博客等网站的搜索结果。恭喜，你已经成功打通了从本地CLI命令，到远程数据抓取，再到浏览器结果呈现的完整链路！
但这还不是全部。openclaw-free-web-search的真正威力，在于它能被其他skill或你的Agent直接调用。我们可以用一个简单的curl命令来模拟这种调用：
# 向skill的API端点发起一个搜索请求 curl -X POST "http://localhost:8080/search" \ -H "Content-Type: application/json" \ -d '{"q":"openclaw installation guide", "format":"json"}'你会得到一个JSON格式的响应，其中包含results数组，每个元素都是一个搜索结果对象（title,url,content）。这正是agent-web-search这类技能在后台所做的事——它们不展示UI，而是将搜索结果作为结构化数据，喂给下游的LLM进行推理。
4.3 配置openclaw-free-web-search：理解config.yaml中的关键参数
openclaw-free-web-search之所以“免费”，是因为它默认使用SearXNG的公共实例（如https://searxng.example.com）。但这些公共实例有速率限制，且稳定性无法保证。为了获得最佳体验，你应该配置它使用一个自托管的SearXNG实例。这需要修改skill的配置文件。
首先，找到该skill的配置文件位置：
# 查看skill的安装路径 openclaw skills list | grep "openclaw-free-web-search" # 输出会显示类似：openclaw-free-web-search | v1.2.0 | /Users/yourname/.openclaw/skills/openclaw-free-web-search # 进入该目录 cd ~/.openclaw/skills/openclaw-free-web-search # 编辑配置文件 nano config.yaml在config.yaml中，你会看到一个engines字段。默认情况下，它可能为空，或指向公共实例。你需要将其修改为：
engines: - name: "my-searxng" url: "http://localhost:8080" # 这是你本地SearXNG的地址 timeout: 10 disabled: false然后，重启skill：
openclaw skills restart openclaw-free-web-search现在，所有通过openclaw-free-web-search发起的搜索，都将优先走你本地的、无限制的SearXNG服务。这个配置过程，揭示了OpenClawskill的核心设计理念：每个skill都是一个可插拔、可配置的微服务。它的行为不固化在代码里，而是由外部config.yaml驱动。这让你可以轻松地将一个skill从开发环境迁移到生产环境，只需修改几行配置，而无需改动一行代码。
实操心得：我最初配置
engines时，误将url写成了https://localhost:8080（加了s）。结果skill启动后，所有搜索都超时。排查了半小时网络，最后才发现是HTTP协议错误——SearXNG默认只监听HTTP，不支持HTTPS。这个教训告诉我，skill的配置文档，永远比GitHub README里的描述更权威，因为它是运行时的真实依据。
5. 常见问题与排查技巧实录：一份来自真实战场的故障速查表
在过去的三个月里，我记录了超过127次openclaw相关的故障事件。下面这份速查表，浓缩了其中最高频、最棘手的10个问题，每一个都附带了我在真实环境中使用的、经过验证的排查步骤和终极解决方案。它不是理论推演，而是血泪经验的结晶。
5.1 问题速查表：高频故障的“症状-原因-处方”三联诊
| 故障症状 | 深层原因 | 终极解决方案 | 实操验证步骤 |
|---|---|---|---|
openclaw命令在CMD中可用，但在PowerShell中报错 | PowerShell的ExecutionPolicy阻止了NPM全局脚本的执行，且PATH环境变量在PowerShell会话中未被正确继承 | 不修改PowerShell策略，而是创建一个专用的PowerShell启动脚本： 1. 创建文件 C:\openclaw\start.ps12. 内容为： Set-Location "C:\openclaw"; & "C:\Program Files\nodejs\npm.cmd" install -g openclaw; exit3. 右键该脚本，选择“以PowerShell运行” | 在PowerShell中执行Get-Command openclaw，应返回CommandType: Application，且Definition指向C:\Users\...\AppData\Roaming\npm\openclaw.ps1 |
openclaw onboard成功，但openclaw skills install报403 Forbidden | emergence.science平台检测到你的设备IP地址发生了剧烈变化（如从家庭宽带切换到公司VPN），触发了风控，临时冻结了该设备的API调用权限 | 联系emergence.science支持团队，提供你的device_id和IP变更说明：1. 执行 openclaw status获取device_id2. 访问 https://support.emergence.science，提交工单3. 在工单中明确写出：“Device ID: [xxx], IP changed from [old] to [new], request manual review” | 支持团队通常在2小时内响应。收到回复后，执行openclaw onboard --force强制刷新设备状态 |
安装agent-browser后，openclaw skills start卡在Starting... | agent-browser依赖chromium浏览器，但你的系统未安装，或安装的版本过旧（<110），与skill要求的puppeteer-core版本不兼容 | 手动安装最新版Chromium，并配置skill指向它： 1. 下载Chromium： https://download-chromium.appspot.com/2. 解压到 C:\chromium\（Windows）或/opt/chromium/（Linux）3. 修改 agent-browser/config.yaml，添加executablePath: "/opt/chromium/chrome-linux/chrome" | 执行openclaw skills start agent-browser --verbose，日志中应出现Launched browser with pid [xxx] |
openclaw-free-web-search返回结果为空，但浏览器访问localhost:8080正常 | skill的config.yaml中engines配置错误，或SearXNG容器的SEARXNG_SETTINGS_PATH环境变量未正确挂载 | 重置skill配置并强制重建容器： 1. 删除 ~/.openclaw/skills/openclaw-free-web-search/config.yaml2. 执行 openclaw skills uninstall openclaw-free-web-search3. 重新安装： openclaw skills install openclaw-free-web-search4. 启动时添加 --rebuild标志：openclaw skills start openclaw-free-web-search --rebuild | 执行`docker ps |
claude-code-skill安装后，openclaw报错Error: Cannot find module 'anthropic' | claude-code-skill是一个Node.js skill，但它依赖的anthropic包未被正确安装到skill的本地node_modules中，因为openclaw的安装流程跳过了npm install步骤 | 进入skill目录，手动执行依赖安装： 1. cd ~/.openclaw/skills/claude-code-skill2. npm install3. npm run build（如果存在build脚本） | 执行ls node_modules/anthropic，应看到该目录存在，且包含index.js等文件 |
openclaw skills list显示openclaw-free-web-search状态为stopped，但openclaw skills start无反应 | skill的进程被僵尸化，其PID文件（pidfile）残留，导致openclaw认为它仍在运行 | 手动清理PID文件并重启： 1. 找到PID文件位置： cat ~/.openclaw/skills/openclaw-free-web-search/.pid2. 杀死对应进程： kill -9 [pid]3. 删除PID文件： rm ~/.openclaw/skills/openclaw-free-web-search/.pid4. 重启skill | 执行openclaw skills status openclaw-free-web-search，状态应变为running |
在NAS（如Synology）上安装openclaw，npm install -g失败，提示EACCES权限错误 | Synology的默认用户admin对/usr/local/lib/node_modules目录没有写入权限，而NPM全局安装需要此权限 | 使用--prefix参数指定一个你有权限的全局目录：1. 创建目录： mkdir ~/npm-global2. 配置NPM： npm config set prefix '~/npm-global'3. 将 ~/npm-global/bin加入PATH：echo 'export PATH="$HOME/npm-global/bin:$PATH"' >> ~/.profile4. 重新加载： source ~/.profile | 执行npm install -g openclaw，应无EACCES错误，且openclaw --version可正常返回 |
**openclaw命令在WSL2（Windows Subsystem for Linux） |
