1. 这不是“龙虾”,是OpenClaw:先厘清概念再动手,避免从第一步就踩坑
“龙虾”这个叫法,在中文技术社区里已经跑偏得有点远了。它既不是官方命名,也不是项目源码里的任何标识,而是早期用户对OpenClaw这个开源AI Agent框架的戏称——因为其Logo设计带有一只抽象化的红色甲壳类生物轮廓,加上“Claw”(爪)字本义,被大家顺口叫成了“龙虾”。但必须强调:你在GitHub上搜不到任何叫“龙虾”的仓库,所有代码、文档、Issue、Release都只存在于openclaw-ai/openclaw这个官方组织下。我见过太多人卡在第一步:用“龙虾安装”去搜教程,结果点进一堆过期半年、基于v0.3.2旧版配置的博客,最后在pip install longxia或npm install longxia-cli上反复报错,折腾一整天才发现根本不存在这个包。
这背后反映的是一个更本质的问题:OpenClaw不是一个开箱即用的桌面软件,而是一个面向开发者与技术型用户的AI工作流编排框架。它的核心价值不在于“能聊天”,而在于“能调度”——把Claude、Qwen、本地Ollama模型、Python脚本、HTTP API、数据库查询甚至飞书/钉钉机器人,全部当作可插拔的“技能模块(Skill)”,由一个统一的Agent引擎按逻辑链路自动串联执行。所谓“微信直连”,其实是通过OpenClaw内置的wechat-skill插件,将微信个人号(非公众号/小程序)作为消息入口,把用户发来的文字、图片、位置等,转换成标准结构化事件,交由Agent处理后再把结果回传给微信。整个过程不依赖第三方中转服务器,所有消息解析、意图识别、工具调用、响应生成,全在你本地机器或NAS上完成。
所以,这篇指南的起点,不是教你点几下鼠标装个APP,而是帮你建立一个清晰的技术坐标系:
- OpenClaw = 框架(Framework),类似LangChain或LlamaIndex,但更聚焦于多模型协同与真实世界工具集成;
- Skill = 插件(Plugin),是连接外部服务的适配器,比如
wechat-skill、mysql-skill、file-skill; - Agent = 工作流实例,由YAML定义的一组Skill调用顺序与条件分支;
- CLI = 命令行工具,用于启动、调试、部署Agent,不是图形界面。
提示:如果你只想找个能直接用微信问问题的AI助手,OpenClaw不是最优解——它需要你理解YAML语法、会查日志、能读报错堆栈。但如果你希望AI能真正“干活”:比如自动查MySQL里上周销售额、把结果生成图表发到微信群、再根据反馈调用Python脚本重跑预测模型——那OpenClaw就是目前中文生态里最贴近这一目标的成熟方案。它不承诺“零门槛”,但承诺“全掌控”。
我第一次部署时也栽在概念混淆上。当时看到社区有人分享“三步安装龙虾”,点进去发现是用Docker Compose拉一个预置镜像,里面已经配好了微信登录和千问模型。我照着跑完,微信确实能回消息,但当我试图把Agent逻辑改成“收到‘报表’就查MySQL+发邮件”,却完全找不到配置文件在哪、日志输出在哪、模型参数怎么改。折腾两天后才明白:那个镜像只是别人打包好的一个特定用例,而OpenClaw真正的力量,在于你亲手写的每一个.yaml文件、每一个自定义Skill的Python函数、每一次对openclaw run --config agent.yaml命令的精准调用。所以,接下来的所有步骤,我们都会紧扣“可理解、可修改、可调试”这个原则,拒绝黑盒封装。
2. 环境准备:为什么必须用Python 3.11+、Git 2.35+、Node.js 18+?版本锁死不是矫情
OpenClaw对运行环境有明确且严格的版本要求,这不是开发团队“故意设门槛”,而是由其底层依赖链决定的硬性约束。我曾用Python 3.9试装,pip install openclaw表面成功,但运行openclaw init时直接报ModuleNotFoundError: No module named 'pydantic.v1'——因为OpenClaw v2026.1.x深度集成了Pydantic v2.7+,而该版本已彻底废弃v1兼容层,Python 3.9默认的pip会错误地安装旧版依赖。同样,Git低于2.35会导致openclaw skill install在拉取远程Skill仓库时因--filter=blob:none参数不支持而卡死;Node.js低于18则会让wechat-skill的WebSocket心跳保活机制失效,微信消息延迟高达30秒以上。这些都不是“大概率可用”,而是“必然失败”。
因此,环境准备不是可选项,而是第一道必须跨过的坎。下面是我实测验证过的、在Windows 11、Ubuntu 24.04、macOS Sonoma上均100%成功的最小化配置清单:
| 组件 | 最低版本 | 推荐版本 | 验证命令 | 关键原因 |
|---|---|---|---|---|
| Python | 3.11.0 | 3.11.9 | python --version && python -c "import sys; print(sys.version_info)" | Pydantic v2.7+、httpx v0.27+、asyncio新特性(如TaskGroup)强依赖3.11+ |
| Git | 2.35.0 | 2.43.0 | git --version && git config --global init.defaultBranch main | openclaw skill install需git clone --filter=blob:none加速远程仓库拉取,旧版不支持 |
| Node.js | 18.17.0 | 18.20.2 | node --version && npm --version | wechat-skill依赖ws@8.16.0,该版本要求Node.js >=18.13.0且<20.0.0 |
| pip | 23.3.1 | 24.0.1 | pip --version | 必须支持PEP 660(Editable installs),否则openclaw skill develop无法热加载本地Skill |
注意:不要用系统自带的Python(如Ubuntu的
/usr/bin/python3)。它通常绑定系统更新,版本锁定且权限受限。务必使用pyenv(macOS/Linux)或python.org官网下载的Windows MSI安装包(勾选“Add Python to PATH”)。Node.js同理,禁用Windows Store里的Node.js应用,它版本陈旧且路径混乱。
具体操作步骤(以Windows为例,其他系统逻辑一致,仅命令微调):
- 卸载所有旧版Python:控制面板 → 卸载程序 → 删除所有
Python 3.x条目(包括Anaconda/Miniconda,它们的pip常与系统冲突); - 安装Python 3.11.9:访问 python.org/downloads ,下载
Windows x86-64 executable installer,安装时务必勾选“Add Python to PATH”,并点击“Customize installation” → 勾选“Install for all users”和“Add Python to environment variables”; - 验证Python环境:打开CMD,输入:
python --version # 应输出:Python 3.11.9 pip list | findstr "pip" # 应输出:pip 24.0.1 - 升级pip到最新版(即使显示已安装,也强制升级):
python -m pip install --upgrade pip - 安装Git:访问 git-scm.com/download/win ,下载安装,安装向导中选择“Use Git from Windows Command Prompt”(关键!让CMD能直接用git);
- 安装Node.js:访问 nodejs.org ,下载LTS版本(当前为18.20.2),安装时保持默认选项;
- 终极验证:在CMD中一次性执行以下命令,所有输出必须无报错且版本匹配上表:
python --version && pip --version && git --version && node --version && npm --version
这一步耗时约15分钟,但它省去了后续90%的“无法识别命令”、“模块找不到”、“技能安装失败”类报错。我统计过自己团队近3个月的OpenClaw支持工单,72%的初始安装失败,根源都在环境版本不匹配。比如那个高频报错openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称,99%是因为:① Python没加PATH;② 安装了Python但没重启CMD;③ 用PowerShell而非CMD(OpenClaw CLI在PowerShell中需额外配置ExecutionPolicy)。所以,请把环境验证当成手术前的消毒——看似繁琐,却是安全的前提。
3. 核心安装与初始化:pip install openclaw之后,你真正得到了什么?
执行pip install openclaw命令后,你获得的不是一个“龙虾.exe”程序,而是一套命令行驱动的开发套件(CLI Toolkit)。它包含三个核心可执行模块:openclaw(主命令)、oc(快捷别名)、openclaw-skill(技能管理专用)。很多人卡在这里,以为装完就能openclaw start,结果提示command not found,或者openclaw命令存在但openclaw init报错No module named 'openclaw.cli'。这通常意味着:pip安装成功了,但Python的Scripts目录没被正确加入系统PATH,或者你正在用的终端(如VS Code内置Terminal)没有继承最新的环境变量。
因此,安装后的第一件事,不是急着初始化项目,而是确认CLI是否真正在系统路径中生效。在CMD中执行:
where openclaw如果返回类似C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts\openclaw.exe的路径,说明安装成功;如果返回“信息: 未找到文件”,则必须手动修复PATH。
3.1 修复PATH的两种可靠方案(任选其一)
方案A:永久性修复(推荐)
- 右键“此电脑” → “属性” → “高级系统设置” → “环境变量”;
- 在“系统变量”中找到
Path,点击“编辑”; - 点击“新建”,粘贴以下路径(请根据你的Python实际安装路径调整,
Python311需替换为你安装的版本号):C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts - 点击“确定”保存,关闭所有CMD窗口,重新打开一个新的CMD,再执行
where openclaw验证。
方案B:临时性修复(调试用)
如果不想改系统变量,可在CMD中直接切换到Scripts目录执行:
cd C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts openclaw --version但这仅对当前CMD窗口有效,每次新开窗口都要重复。
提示:
where命令在Windows上等价于Linux/macOS的which。如果你用的是Git Bash,需用which openclaw;如果是PowerShell,则用Get-Command openclaw。不同终端的环境变量继承机制不同,这是初学者最容易忽略的细节。
3.2openclaw init做了什么?一个被严重低估的关键动作
当openclaw命令就绪后,执行:
openclaw init my-first-agent这个命令远不止是创建一个空文件夹。它会:
生成标准项目骨架:在当前目录下创建
my-first-agent/文件夹,并内置以下必需文件:agent.yaml:Agent主配置文件,定义了使用的模型、启用的Skills、工作流逻辑;skills/:空目录,用于存放本地Skill(Python模块);models/:空目录,用于存放本地大模型(如Qwen、Phi-3);.openclaw/:隐藏目录,存储CLI的全局配置、缓存、日志轮转策略。
自动检测并写入环境元数据:
init会扫描当前Python环境,记录python --version、pip list的哈希值,并写入.openclaw/env.json。这使得后续openclaw run能精准复现环境,避免“在我机器上能跑”的协作困境。预置最小化
agent.yaml:内容如下(已精简注释):name: "my-first-agent" description: "A simple agent example" model: provider: "ollama" # 默认使用本地Ollama name: "qwen2:1.5b" # 默认模型名 skills: - name: "echo" # 内置基础技能:原样回显输入 enabled: true workflow: - step: "echo" input: "{{ user_input }}"创建
requirements.txt模板:列出项目依赖,方便后续用pip install -r requirements.txt一键复现。
执行完init,你的项目就具备了运行基础。但此时还不能微信直连——echo技能只能回显文字,没有任何网络通信能力。要接入微信,必须引入wechat-skill,而这正是下一步的核心。
4. 微信直连实战:从扫码登录到消息收发,绕不开的三个技术关卡
“微信直连”是OpenClaw v2026.1.x最重磅的更新,但它绝非“点一下授权就完事”。其背后是三层技术栈的精密咬合:微信网页版协议逆向 + WebSocket长连接保活 + 本地消息路由网关。官方wechat-skill插件已封装了前两层,但第三层——如何把微信消息精准路由给你的Agent、再把Agent响应塞回微信——必须由你亲手配置。这也是为什么很多教程教到“扫码登录成功”就戛然而止,用户却始终收不到回复。
4.1 安装wechat-skill:为什么openclaw skill install比pip install更可靠?
OpenClaw官方Skill仓库托管在GitHub,地址为https://github.com/openclaw-ai/skills。每个Skill(如wechat、mysql、file)都是一个独立的Git子模块。openclaw skill install wechat命令会:
- 从官方仓库拉取
wechat子模块的最新稳定版(tagv2026.1.0); - 将其克隆到项目根目录下的
skills/wechat/; - 自动执行
pip install -e skills/wechat/(可编辑安装),确保Python能实时加载修改; - 在
agent.yaml中追加wechat到skills列表,并写入默认配置段。
而如果你用pip install wechat-skill,会遇到两个致命问题:
- 第一,
pip安装的Skill是静态的,无法随OpenClaw主框架升级而自动更新; - 第二,它不会自动写入
agent.yaml,你需要手动编辑配置,极易出错。
因此,务必使用CLI内置命令:
cd my-first-agent openclaw skill install wechat执行后,检查skills/wechat/目录是否存在,以及agent.yaml末尾是否新增了如下段落:
skills: - name: "wechat" enabled: true config: # 微信配置留空,首次运行时会引导扫码4.2 扫码登录:不是一次性的,而是持续的Session维持
运行openclaw run后,CLI会输出:
[INFO] Starting WeChat skill... [INFO] Please scan the QR code below with your WeChat app: [QR CODE IMAGE] [INFO] Waiting for login... (timeout in 120s)这时,用手机微信“扫一扫”功能扫描二维码。关键点来了:扫码成功后,手机微信不会弹出“登录成功”提示,而是静默跳转到一个空白页。这是微信网页版协议的正常行为,不代表失败。你需要做的,是回到CMD窗口,等待约5-8秒,直到出现:
[SUCCESS] WeChat login successful! Session ID: wxsess_abc123...这个Session ID会被持久化到skills/wechat/session.json,下次启动时自动复用,无需重复扫码。但如果微信客户端退出、或超过7天未使用,Session会过期,此时openclaw run会自动触发重新扫码流程。
注意:微信网页版协议对登录设备有限制。如果你的微信账号已在其他浏览器(如Chrome)登录了网页版,本次扫码会失败,提示“已在其他设备登录”。解决方法:在手机微信中依次点击“我”→“设置”→“账号与安全”→“登录设备管理”,踢掉所有“Web 微信”设备,再重试。
4.3 消息收发链路:从微信到Agent,再从Agent到微信的完整闭环
当Session建立后,消息流是这样工作的:
- 微信端:你给这个微信小号(注意:是个人号,不是公众号)发一条消息,比如“你好”;
- Skill层:
wechat-skill通过WebSocket长连接,实时捕获到这条消息,解析为标准OpenClaw事件对象:{ "event_type": "message", "from_user": "wxid_xyz789", "content": "你好", "timestamp": 1712345678 } - Agent层:OpenClaw引擎接收到事件,根据
agent.yaml中的workflow定义,调用echo技能处理; - 响应层:
echo技能返回{"response": "你好"},引擎将其格式化为微信可识别的消息体; - 回传层:
wechat-skill通过同一WebSocket连接,将响应发送回微信服务器,最终显示在你的手机上。
要验证这个闭环,只需修改agent.yaml中的workflow,让它调用wechat技能本身(实现“收到消息就转发给另一个微信”):
workflow: - step: "wechat" input: "{{ user_input }}" config: to_user: "wxid_abc456" # 替换为目标微信ID然后重启openclaw run,给自己发消息,观察是否被转发。这一步是调试的核心:它证明了从微信入口到Agent逻辑、再到微信出口的全链路畅通。
5. 故障排查:从openclaw : 无法将“openclaw”项识别为 cmdlet到微信消息石沉大海
安装和配置过程中,最常遇到的不是“完全不能用”,而是“部分功能失效”。下面是我整理的Top 5高频故障及其根因分析,每一条都来自真实踩坑记录。
5.1 故障1:openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称
现象:CMD中输入openclaw --version,报错如题。
根因分析:这不是OpenClaw的问题,而是Windows命令解析机制的特性。当CMD找不到openclaw.exe时,它会尝试在当前目录下搜索openclaw.bat、openclaw.cmd等批处理文件,若不存在,则抛出此泛化错误。
排查链路:
- 执行
where openclaw,确认是否返回路径; - 若无返回,检查Python Scripts目录是否在PATH中(见2.1节);
- 若有返回,但
openclaw --version仍报错,极大概率是你在VS Code的集成终端中执行。VS Code终端默认继承父进程环境,但有时会缓存旧PATH。解决方案:关闭所有VS Code窗口,重新打开,或在终端中执行refreshenv(需安装chocolatey); - 终极方案:直接用绝对路径运行,如
C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts\openclaw.exe --version。
5.2 故障2:微信扫码后一直显示“Waiting for login...”,超时退出
现象:二维码扫描后,CMD卡在等待状态,120秒后报错Login timeout。
根因分析:wechat-skill依赖requests库发起HTTP请求获取二维码,再用websockets库建立长连接。超时通常意味着网络层阻断。
排查链路:
- 检查防火墙:Windows Defender防火墙可能阻止
python.exe的出站连接。临时关闭防火墙测试; - 检查代理:如果你公司网络使用HTTP代理,
wechat-skill默认不读取系统代理设置。需在skills/wechat/config.yaml中手动添加:proxy: http: "http://your-proxy:8080" https: "http://your-proxy:8080" - 检查DNS:微信域名
login.weixin.qq.com解析失败。在CMD中执行ping login.weixin.qq.com,若不通,更换DNS为114.114.114.114; - 检查时间同步:微信协议对时间戳敏感,若系统时间误差超过5分钟,扫码必失败。右键任务栏时间 → “调整日期和时间” → 开启“自动设置时间”。
5.3 故障3:微信能登录,但发消息后Agent无响应,日志里只有[INFO] Received message from wxid_xyz,没有后续
现象:登录成功,消息能收到,但Agent不处理,也不回消息。
根因分析:wechat-skill只负责收发,不负责业务逻辑。消息到达后,引擎需根据agent.yaml的workflow调用对应Skill。无响应=Workflow未定义或Skill未启用。
排查链路:
- 检查
agent.yaml中skills列表,确认wechat和你期望调用的Skill(如echo)enabled: true; - 检查
workflow是否为空或语法错误。一个最简可用的workflow是:workflow: - step: "echo" input: "{{ user_input }}" - 查看详细日志:启动时加
--log-level debug参数:
日志中会显示openclaw run --log-level debug[DEBUG] Executing step 'echo' with input '你好',若无此行,说明Workflow未触发。
5.4 故障4:Agent能处理消息,但微信收不到回复,手机端显示“消息已发出,但被对方拒收”
现象:日志显示[INFO] Sending response to wxid_xyz: 你好,但手机没收到。
根因分析:微信个人号对消息频率有限制。wechat-skill默认开启“防刷屏”模式,若1分钟内发送超过5条消息,后续消息会被微信服务器静默丢弃。
解决方案:
- 在
skills/wechat/config.yaml中调整速率限制:rate_limit: messages_per_minute: 10 burst: 3 - 更稳妥的做法:在
workflow中加入delay步骤,强制间隔:workflow: - step: "echo" input: "{{ user_input }}" - step: "delay" config: seconds: 2 - 永久性规避:使用微信小号专用此Agent,避免与其他自动化脚本共用同一账号。
5.5 故障5:部署到NAS后,微信登录成功,但隔夜后Session失效,需每天扫码
现象:在群晖/威联通NAS上部署,首次扫码成功,但第二天再启动,提示Session过期。
根因分析:NAS的cron定时任务或系统休眠机制,会终止后台Python进程,导致wechat-skill的WebSocket连接断开且未优雅关闭,Session文件未被正确刷新。
解决方案:
- 禁用NAS休眠:在控制面板 → 电源计划 → 取消勾选“启用硬盘休眠”;
- 使用
supervisord守护进程(Linux NAS):[program:openclaw] command=/volume1/@appstore/Python311/usr/local/bin/python3.11 /volume1/@appstore/Python311/usr/local/bin/openclaw run --config /volume1/docker/openclaw/agent.yaml autostart=true autorestart=true startretries=3 user=root - 关键配置:在
skills/wechat/config.yaml中启用auto_reconnect: true,并设置session_persistence: true,确保断线后自动重连并恢复Session。
这些故障排查不是“备查手册”,而是我过去三个月在客户现场、线上支持、内部测试中,反复验证过的最小可行诊断路径。它不追求覆盖100%场景,但保证覆盖95%的真实问题。记住,OpenClaw的调试哲学是:“日志即真相”。每一条[DEBUG]级别的日志,都是框架在告诉你“我此刻正在做什么”。学会阅读日志,比死记硬背解决方案重要十倍。
6. 进阶实践:把“微信直连”变成“业务工作流”,从Echo到真实生产力
当你能稳定收发微信消息后,真正的价值才刚开始。OpenClaw的威力不在于“能回消息”,而在于“能调用一切”。下面是一个我在电商公司落地的真实案例:自动处理客户售后申请。整个流程无需人工介入,从微信消息触发,到数据库查询、物流接口调用、结果生成图文消息回传,全程自动化。
6.1 场景拆解:一个售后申请的完整生命周期
客户在微信中发送:
“订单号123456789,商品破损,申请退货。”
我们需要:
- 从文本中提取订单号(正则匹配);
- 查询MySQL数据库,确认订单状态、商品SKU、客户手机号;
- 调用物流API(如顺丰开放平台),生成退货电子运单;
- 将运单号、退货地址、操作指引,组装成富文本消息(含图片)发回微信。
6.2 技能组合:regex-skill+mysql-skill+http-skill+wechat-skill
OpenClaw的精髓在于Skill的原子化。我们不需要写一个巨无霸Python脚本,而是组合四个现成Skill:
regex-skill:内置正则提取,配置pattern: "订单号(\d{9})",输出{"order_id": "123456789"};mysql-skill:连接公司MySQL,执行SELECT * FROM orders WHERE order_id = ?;http-skill:调用顺丰API,POST /v1/waybill/create,传入JSON参数;wechat-skill:将最终结果渲染为图文卡片。
agent.yaml的workflow定义如下(已简化):
workflow: # 步骤1:提取订单号 - step: "regex" input: "{{ user_input }}" config: pattern: "订单号(\d{9})" group_names: ["order_id"] # 步骤2:查询数据库 - step: "mysql" input: "{{ regex.order_id }}" config: query: "SELECT order_status, sku, phone FROM orders WHERE order_id = ?" connection: "mysql://user:pass@192.168.1.100:3306/ecommerce" # 步骤3:调用物流API - step: "http" input: | { "order_id": "{{ mysql.order_id }}", "sku": "{{ mysql.sku }}", "phone": "{{ mysql.phone }}" } config: method: "POST" url: "https://api.sf-express.com/v1/waybill/create" headers: Authorization: "Bearer {{ env.SF_TOKEN }}" timeout: 30 # 步骤4:生成并发送微信图文 - step: "wechat" input: | { "to_user": "{{ user_from }}", "type": "news", "articles": [ { "title": "退货申请已受理", "description": "您的退货运单号:{{ http.waybill_no }},请按以下地址寄回...", "url": "https://example.com/return-guide", "picurl": "https://example.com/return-qrcode.jpg" } ] }6.3 关键技巧:环境变量与安全隔离
http-skill中调用顺丰API需要Token,绝不能硬编码在agent.yaml里。OpenClaw支持.env文件加载环境变量:
- 在项目根目录创建
.env文件:SF_TOKEN=your_actual_sf_token_here MYSQL_PASSWORD=your_mysql_pass - CLI启动时自动读取,
{{ env.SF_TOKEN }}即可在任意Skill配置中引用。
提示:
.env文件应加入.gitignore,避免密钥泄露。生产环境部署时,可改用NAS的环境变量管理功能,或Kubernetes Secret挂载。
这个案例的价值在于,它展示了OpenClaw如何将“微信”从一个聊天入口,升维为企业级业务系统的统一触点。客户不用下载APP、不用记网址、不用学操作,只要在最熟悉的微信里发一句话,背后复杂的跨系统协作就已悄然完成。而这一切,只需要你编写一个YAML文件,安装几个Skill,无需一行新代码。
7. 卸载与清理:为什么pip uninstall openclaw不够,必须手动删除这四个地方
当你要彻底卸载OpenClaw,或想从头开始全新部署时,很多人只执行pip uninstall openclaw,以为万事大吉。结果下次安装时,openclaw init报错Directory already exists,或wechat-skill读取到旧Session导致登录异常。这是因为OpenClaw的“状态”分散在四个物理位置,pip uninstall只清理了Python包,其余三处需手动清除。
7.1 必须清理的四个位置
| 位置 | 路径(Windows示例) | 清理内容 | 不清理的后果 |
|---|---|---|---|
| 1. Python包缓存 | C:\Users\YourName\AppData\Local\pip\Cache\ | 所有openclaw*、wechat-skill*相关缓存文件 | 下次pip install可能复用损坏缓存,导致安装包校验失败 |
| 2. CLI全局配置 | C:\Users\YourName\.openclaw\ | config.json、cache/、logs/ | openclaw run仍读取旧配置,如错误的模型地址、过期Token |
| 3. 项目级数据 | my-first-agent\.openclaw\ | env.json、session.json(若在skills/wechat/下) | openclaw init失败;微信登录复用旧Session,可能被微信封禁 |
| 4. Skill本地副本 | my-first-agent\skills\ | 整个skills/目录 | openclaw skill install会拒绝覆盖,报错Skill 'wechat' already exists |
7.2 安全卸载的标准化流程
停止所有OpenClaw进程:
在CMD中执行taskkill /f /im python.exe(Windows)或pkill -f "openclaw run"(Linux/macOS),确保无残留进程。卸载Python包:
pip uninstall openclaw -y删除全局缓存与配置:
手动进入资源管理器,删除以下两个文件夹:C:\Users\YourName\AppData\Local\pip\Cache\(可只删openclaw*开头的子文件夹)C:\Users\YourName\.openclaw\
清理项目目录:
进入你的项目文件夹(如my-first-agent),执行:# 删除CLI生成的隐藏目录 rmdir /s /q ".openclaw" # 删除所有Skill rmdir /s /q "skills" # (可选)重置agent.yaml为初始状态 del "agent.yaml"终极验证:
重新打开CMD,执行openclaw --version,应报错'openclaw' is not recognized;
然后执行pip install openclaw,再openclaw init clean-test,确认能成功创建全新项目。
注意:
skills/目录下若存放了你自定义开发的Skill(非官方安装的),请先备份再删除。官方Skill可随时用openclaw skill install重新拉取。
这个卸载流程,是我为团队制定的SOP(标准作业程序)。它确保了每次新部署都是“纯净态”,避免了因历史残留导致的不可预测行为。在技术实践中,“彻底”比“快速”更重要——一次干净的卸载,能省去后续数小时的疑难杂症排查。
我在实际操作中发现,最常被遗忘的是C:\Users\YourName\.openclaw\这个全局配置目录。它像一个隐形的幽灵,默默影响着所有OpenClaw项目。