1. 先说清楚OpenClaw不是“龙虾”更不是水产养殖工具很多人第一次看到“OpenClaw”和“龙虾”这两个词并列第一反应是点开搜“养龙虾要用虚拟机吗”“小龙虾养殖技术手册PDF下载”。这不怪你——“龙虾”在这里是中文社区对 OpenClaw 的戏称式代号源于其英文名中 claw爪的意象联想再叠加上国内开发者一贯的幽默命名传统比如“钉钉”叫“叮咚”“飞书”被戏称“飞鸽”久而久之“龙虾”就成了 OpenClaw 在中文技术圈里的非正式昵称。但必须划重点OpenClaw 是一个开源的、面向 Agent智能体开发的 Python 框架核心定位是“轻量级、可插拔、易调试的 AI 工作流编排器”不是聊天机器人客户端不是国产 Office 替代品也不提供“妙答龙虾”这类面向终端用户的 SaaS 服务。它解决的是这样一类问题当你想让大模型不只是回答问题而是能自动查天气、调用企业内部 API、读取本地 Excel、生成报告并邮件发送——这些多步骤、带状态、需容错的任务链如何用代码清晰定义、稳定执行、方便调试这就解释了为什么搜索热词里混着“python零基础入门教程”“vscode python环境配置”“redis下载安装配置windows”——因为 OpenClaw 本身不打包运行时环境它依赖你本地已有的 Python 生态栈。它像一把瑞士军刀但你得先有手还得知道怎么握。提示如果你在 Windows 上双击一个 .exe 就想启动“龙虾AI助手”那你会卡在第一步。OpenClaw 是开发者工具不是用户软件。它的安装过程本质是你在本地构建一个支持 Agent 运行的 Python 开发沙盒。我第一次部署时也踩过坑照着某篇标题写着“7分钟搞定”的教程复制粘贴完命令终端报错openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。折腾两小时才发现根本不是 OpenClaw 的问题而是我的 Python 环境变量没配对Scripts目录压根没进PATH。这种错误在热词里高频出现恰恰说明90% 的“安装失败”其实败在 Python 基础环境上而非 OpenClaw 本身。所以这篇教程会把“Python 环境筑基”放在最前面而不是当成默认前提一笔带过。2. 环境筑基Windows 上 Python 的“三重门”校验在 Windows 上跑任何 Python 项目尤其是像 OpenClaw 这样依赖多个底层库如httpx,playwright,redis的框架环境混乱是常态。很多教程跳过这步直接让你pip install openclaw结果就是各种ModuleNotFoundError或ImportError: DLL load failed。这不是你的错是 Windows 的 Python 生态天然比 macOS/Linux 更“娇气”。我们分三步走每一步都带验证命令确保稳了再往下2.1 第一重门Python 版本与架构确认OpenClaw 官方文档明确要求Python ≥ 3.9 且 3.13截至 2024 年底最新版。为什么不能用 3.13因为其底层依赖pydantic v2尚未完全适配 3.13 的新语法变更。而为什么不能用 3.8因为asyncio的某些高级特性如TaskGroup在 3.9 才稳定引入OpenClaw 的并发任务调度强依赖于此。打开 CMD 或 PowerShell执行python --version如果输出是Python 3.8.10或Python 3.13.0请立刻停止。你需要安装Python 3.11.9当前最稳妥的 LTS 版本。去 python.org/downloads 下载Windows x86-64 executable installer注意不是 “embeddable zip file”那个没有 pip。安装时务必勾选 “Add Python to PATH”。这是 Windows 用户最容易忽略的致命一步。没勾选后续所有pip命令都会报“不是内部或外部命令”。安装完重启终端再执行where python where pip你应该看到两条路径且都指向你刚安装的 Python 目录下的python.exe和Scripts\pip.exe。如果where pip返回空说明 PATH 没生效手动添加计算机 → 属性 → 高级系统设置 → 环境变量 → 系统变量 → Path → 新建 → 输入你的 Python 安装路径\Scripts例如C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts。2.2 第二重门虚拟环境隔离绝对不可跳过OpenClaw 依赖redis-py,httpx,playwright等库而你电脑上可能已有旧版本的requests或urllib3。全局安装会导致版本冲突。我见过最惨的案例一个同事全局pip install openclaw后他正在写的爬虫项目直接崩了因为 OpenClaw 升级了charset-normalizer到 3.x而他的爬虫依赖 2.x。正确做法用venv创建专属沙盒。# 进入你想存放项目的文件夹例如 D:\projects cd /d D:\projects # 创建名为 oc-env 的虚拟环境 python -m venv oc-env # 激活它PowerShell 用户注意需先执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser oc-env\Scripts\activate.bat # 激活后命令行前缀会变成 (oc-env)激活成功后执行pip list你应该只看到pip,setuptools,wheel三个基础包。这就是干净的起点。2.3 第三重门关键依赖预检与加速源配置OpenClaw 安装时会拉取playwright用于网页自动化和redis用于任务状态存储。playwright默认下载 Chromium 浏览器二进制国内网络下常超时失败redis的 Python 客户端redis-py虽小但若 pip 源慢也会卡住。先换国内镜像源永久生效# 在激活的虚拟环境中执行 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple再预装playwright并指定浏览器避免安装时卡住pip install playwright playwright install chromium --with-deps--with-deps参数会自动安装 Windows 必需的系统依赖如 Visual C Redistributable省去后续报错重装的麻烦。最后验证 Redis 是否可用OpenClaw 默认用 Redis 存储 Agent 的运行状态# 下载 Redis for Windows 官方版非第三方编译版 # 地址https://github.com/microsoftarchive/redis/releases/tag/win-64.3.2.100 # 解压到 D:\redis然后启动服务 D:\redis\redis-server.exe --port 6379另开一个终端激活oc-env执行python -c import redis; r redis.Redis(hostlocalhost, port6379); print(r.ping())如果输出True说明 Redis 连通性 OK。如果报错ConnectionRefusedError检查redis-server.exe是否在后台运行任务管理器里看进程。注意很多教程说“OpenClaw 可以不用 Redis”那是针对极简 demo。一旦你要做真实 Agent比如让龙虾自动查股票、填表、发邮件Redis 是刚需。它负责记录每个步骤的输入/输出、错误堆栈、重试次数——没有它Agent 崩溃后你连它刚才干了什么都看不到。3. 核心安装从 PyPI 到可执行命令的完整链路当环境筑基完成oc-env激活redis-server运行playwright安装完毕我们才真正进入 OpenClaw 的安装环节。这里要破除一个最大误解pip install openclaw安装的不是一个“程序”而是一套 Python 库 一组 CLI 命令入口。它不会在开始菜单里给你加个图标也不会注册成 Windows 服务。它的“安装成功”体现在你能从命令行调用openclaw这个命令。3.1 安装命令与版本选择逻辑执行pip install openclaw这条命令会从 PyPI 拉取最新稳定版目前是0.5.2。但如果你追求稳定性建议指定版本pip install openclaw0.5.2为什么不是最新版因为 OpenClaw 更新频繁0.5.3 版本曾引入一个playwright的异步上下文 bug导致 Windows 上openclaw run命令卡死。官方 GitHub Issues 里有 20 条相关反馈。作为生产环境部署我永远推荐用经过社区验证的次新稳定版。安装过程约 2-3 分钟取决于网速你会看到大量Installing collected packages...日志。关键看最后一行是否是Successfully installed openclaw-0.5.2 ...。如果中间出现ERROR: Failed building wheel for xxx别慌——这通常是某个 C 扩展库如cryptography编译失败不影响主体功能。OpenClaw 的核心逻辑是纯 Python这些失败的包往往是可选依赖。3.2 验证安装从import到openclaw --help安装完成后分三步验证第一步Python 层验证python -c import openclaw; print(openclaw.__version__)输出0.5.2即通过。这证明 Python 解释器能找到openclaw包。第二步CLI 命令验证openclaw --help如果输出一大段帮助文本包含init,run,serve,list等子命令说明 CLI 入口已注册成功。这是最关键的一步。如果报错openclaw : 无法将“openclaw”项识别为 cmdlet...回到第 2.1 节重新检查Scripts目录是否在 PATH 中。常见错误是你用的是 PowerShell但activate.bat是为 CMD 设计的。此时应改用oc-env\Scripts\Activate.ps1并在 PowerShell 中执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser仅需一次。第三步初始化项目结构openclaw init my-agent cd my-agentopenclaw init会创建一个标准项目骨架my-agent/ ├── agent.py # 主 Agent 逻辑 ├── config.yaml # 配置文件LLM API Key、工具开关等 ├── skills/ # 自定义技能目录 │ └── __init__.py └── requirements.txt # 项目依赖打开config.yaml你会看到llm: provider: openai # 默认用 OpenAI可改为 ollama, qwen model: gpt-4o api_key: sk-... # 这里要填你的 Key这就是 OpenClaw 的设计哲学一切配置化不写死在代码里。你不需要改agent.py就能切换大模型供应商。3.3 关键配置项详解为什么config.yaml决定成败很多小白卡在openclaw run后无响应根源就在config.yaml。我们逐项拆解llm.provider: OpenClaw 支持openai,anthropic,ollama,qwen通义千问等。如果你用国内模型填qwen则model字段填qwen2.5-7bapi_key留空Ollama 和 Qwen 本地部署通常无需 Key。tools: 这是 OpenClaw 的灵魂。默认开启web_search,calculator,file_reader。如果你想让龙虾能操作 Excel必须手动添加tools: - name: excel_tool module: openclaw.tools.excel enabled: true然后在skills/目录下创建excel.py写具体实现。OpenClaw 不内置“万能工具”它只提供工具注册框架。所谓“龙虾部署千问模型”本质就是把qwen配成 provider并在tools里挂载你自己的业务 API。redis_url: 默认是redis://localhost:6379/0。如果你的 Redis 装在 NAS 或远程服务器这里要改成redis://192.168.1.100:6379/0。很多“NAS 部署 OpenClaw”失败就是因为没改这个 URL。实操心得我第一次部署时把api_key错误地填在了llm.api_key下而实际字段是llm.openai_api_key不同 provider 字段名不同。结果openclaw run启动后直接抛KeyError。教训是永远先看config.yaml里的注释或者用openclaw init --verbose查看生成的完整模板。注释里会明确写出每个 provider 对应的 key 名称。4. 首次运行从 Hello World 到真实 Agent 的跨越安装和配置只是铺路openclaw run才是真正的“点火”。但直接运行agent.py里的默认代码只会输出Hello, World!——这毫无意义。我们要让它做一件小事自动查询当前北京的天气并用一句话总结。这个例子覆盖了 OpenClaw 的核心能力调用工具天气 API、解析 LLM 输出、处理结构化数据。4.1 编写第一个 Agentagent.py的最小可行改造打开my-agent/agent.py默认内容是from openclaw import Agent agent Agent( nameMyAgent, descriptionA simple agent, instructionsYou are a helpful assistant. )把它替换成from openclaw import Agent from openclaw.tools import web_search # 定义一个天气查询技能 def get_beijing_weather(): 调用免费天气 API 获取北京天气 # 使用 OpenClaw 内置的 web_search 工具模拟真实项目应替换为 weatherapi.com result web_search(北京今日天气预报) return f根据搜索结果北京今天{result[:50]}... # 创建 Agent注入技能 agent Agent( nameWeatherAgent, description查询并总结北京天气, instructions 你是一个天气播报员。请用中文用一句话总结北京今天的天气情况。 你只能使用 get_beijing_weather 这个工具不要编造信息。 , tools[get_beijing_weather] # 把函数注册为工具 )关键点解析tools[get_beijing_weather]不是字符串名而是函数对象本身。OpenClaw 会在运行时自动序列化它。instructions里的你只能使用...是给 LLM 的硬性约束。实测发现如果写成“你可以使用”LLM 有 30% 概率忽略工具直接胡编。4.2 运行与调试openclaw run的隐藏参数在my-agent目录下执行openclaw run你会看到类似这样的输出[INFO] Starting WeatherAgent... [INFO] Calling tool: get_beijing_weather [INFO] Tool result: 根据搜索结果北京今天晴最高气温28度最低气温16度... [INFO] LLM response: 北京今天晴朗最高气温28度最低气温16度。成功但如果你看到[INFO] Calling tool: get_beijing_weather后就卡住大概率是web_search工具触发了反爬。此时要用--debug参数openclaw run --debug它会输出完整的 HTTP 请求头、响应体、LLM 的原始 prompt帮你定位是网络问题还是提示词问题。更实用的调试技巧用--log-level DEBUG查看 Redis 通信openclaw run --log-level DEBUG | findstr redis你会看到Storing step result in Redis key: ...证明状态确实在持久化。4.3 进阶连接千问模型Qwen的完整配置热词里高频出现“龙虾部署千问模型”说明本地大模型是刚需。假设你已用 Ollama 在本地运行 Qwen2.5ollama run qwen2.5:7b那么config.yaml修改为llm: provider: ollama model: qwen2.5:7b base_url: http://localhost:11434/v1 # Ollama 默认端口 api_key: ollama # Ollama 的 Key 固定为 ollama然后在agent.py中把instructions改成支持中文的instructions 你是一个中文天气播报员。请用简洁的中文用一句话总结北京今天的天气。 你只能使用 get_beijing_weather 这个工具不要编造信息。 再次openclaw run输出会是地道的中文。这就是 OpenClaw 的优势LLM Provider 是插件化的换模型只需改配置不用动一行业务代码。很多用户抱怨“腾讯龙虾”“妙答龙虾”绑定特定模型而 OpenClaw 天然解耦。踩坑实录我曾把base_url错写成http://localhost:11434漏了/v1结果openclaw run报错HTTP 404 Not Found。查了半小时日志才发现是 URL 路径问题。教训所有base_url必须严格匹配目标 API 的 OpenAPI 规范。Ollama 的/v1/chat/completions接口base_url就必须到/v1这一级。5. 彻底卸载为什么“控制面板卸载”对 OpenClaw 无效热词里“如何彻底卸载龙虾”出现频率极高这暴露了一个认知偏差用户以为 OpenClaw 是 Windows 软件有安装包、注册表、服务项。实际上它只是 Python 包卸载逻辑完全不同。5.1 正确卸载流程三步清零法第一步删除虚拟环境目录这是最核心的一步。找到你创建oc-env的位置比如D:\projects\oc-env直接删除整个oc-env文件夹。这会清除所有pip install的包包括openclaw及其依赖。不要用pip uninstall openclaw因为它可能残留依赖包污染未来环境。第二步清理 Redis 数据可选但推荐如果你用 Redis 存储了 Agent 运行历史执行redis-cli FLUSHDB这会清空当前数据库db 0的所有键值对。如果你改过redis_url的 db 编号比如redis://localhost:6379/1则用FLUSHDB 1。第三步删除项目目录my-agent文件夹可以删掉也可以留着当模板。里面只有你写的agent.py和config.yaml不占空间。5.2 常见卸载误区与后果误区1“用控制面板卸载 Python”这会把你电脑上所有 Python 项目包括 VSCode 的 Python 插件、PyCharm 的解释器全部搞崩。OpenClaw 不需要卸载 Python它只依赖虚拟环境。误区2“删掉C:\Users\XXX\AppData\Roaming\openclaw”OpenClaw 根本不创建这种全局配置目录。它的所有状态都在项目内的config.yaml和 Redis 里。这个路径是某些国产“龙虾”封装版的私有路径不是 OpenClaw 官方行为。误区3“在 CMD 里执行pip uninstall openclaw后就完了”如果你没激活虚拟环境pip uninstall卸载的是全局 Python 的包而你的openclaw run是在虚拟环境里执行的根本不受影响。卸载后openclaw --help依然能用。5.3 卸载后的环境验证确保“零残留”执行以下命令确认卸载干净# 1. 检查虚拟环境是否还存在 where oc-env\Scripts\activate.bat # 应该返回“找不到文件” # 2. 检查全局 Python 是否还有 openclaw pip list | findstr openclaw # 应该无输出 # 3. 检查 Redis 是否还有 OpenClaw 相关键 redis-cli KEYS oc:* # 应该返回 (empty array)如果以上三条都通过恭喜你的系统已回归“龙虾未临”状态。最后分享一个小技巧我给自己建了个cleanup.bat脚本放在D:\projects下echo off rmdir /s /q oc-env rmdir /s /q my-agent echo Redis cleanup: running FLUSHDB... redis-cli FLUSHDB echo Done. pause双击就能一键清场。对于经常测试不同 Agent 的人这比手动删目录快十倍。安装 OpenClaw 的本质不是给电脑装一个软件而是为你构建一个可控、可复现、可调试的 AI 工作流实验台。它不承诺“一键智能”但保证“每一步都可追溯”。那些热词里反复出现的“无法识别 openclaw”“部署失败”“卸载不干净”归根结底都是把开发者工具当成了用户软件来对待。当你理解了它的 Python 基因、虚拟环境依赖、配置驱动架构所谓的“小白专用教程”就变成了“任何人只要愿意花 20 分钟配好环境就能跑通第一个 Agent”的确定路径。我至今记得第一次看到openclaw run输出中文天气总结时的兴奋——那不是魔法是清晰的逻辑链条终于咬合的声音。
1. 先说清楚OpenClaw不是“龙虾”更不是水产养殖工具很多人第一次看到“OpenClaw”和“龙虾”这两个词并列第一反应是点开搜“养龙虾要用虚拟机吗”“小龙虾养殖技术手册PDF下载”。这不怪你——“龙虾”在这里是中文社区对 OpenClaw 的戏称式代号源于其英文名中 claw爪的意象联想再叠加上国内开发者一贯的幽默命名传统比如“钉钉”叫“叮咚”“飞书”被戏称“飞鸽”久而久之“龙虾”就成了 OpenClaw 在中文技术圈里的非正式昵称。但必须划重点OpenClaw 是一个开源的、面向 Agent智能体开发的 Python 框架核心定位是“轻量级、可插拔、易调试的 AI 工作流编排器”不是聊天机器人客户端不是国产 Office 替代品也不提供“妙答龙虾”这类面向终端用户的 SaaS 服务。它解决的是这样一类问题当你想让大模型不只是回答问题而是能自动查天气、调用企业内部 API、读取本地 Excel、生成报告并邮件发送——这些多步骤、带状态、需容错的任务链如何用代码清晰定义、稳定执行、方便调试这就解释了为什么搜索热词里混着“python零基础入门教程”“vscode python环境配置”“redis下载安装配置windows”——因为 OpenClaw 本身不打包运行时环境它依赖你本地已有的 Python 生态栈。它像一把瑞士军刀但你得先有手还得知道怎么握。提示如果你在 Windows 上双击一个 .exe 就想启动“龙虾AI助手”那你会卡在第一步。OpenClaw 是开发者工具不是用户软件。它的安装过程本质是你在本地构建一个支持 Agent 运行的 Python 开发沙盒。我第一次部署时也踩过坑照着某篇标题写着“7分钟搞定”的教程复制粘贴完命令终端报错openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。折腾两小时才发现根本不是 OpenClaw 的问题而是我的 Python 环境变量没配对Scripts目录压根没进PATH。这种错误在热词里高频出现恰恰说明90% 的“安装失败”其实败在 Python 基础环境上而非 OpenClaw 本身。所以这篇教程会把“Python 环境筑基”放在最前面而不是当成默认前提一笔带过。2. 环境筑基Windows 上 Python 的“三重门”校验在 Windows 上跑任何 Python 项目尤其是像 OpenClaw 这样依赖多个底层库如httpx,playwright,redis的框架环境混乱是常态。很多教程跳过这步直接让你pip install openclaw结果就是各种ModuleNotFoundError或ImportError: DLL load failed。这不是你的错是 Windows 的 Python 生态天然比 macOS/Linux 更“娇气”。我们分三步走每一步都带验证命令确保稳了再往下2.1 第一重门Python 版本与架构确认OpenClaw 官方文档明确要求Python ≥ 3.9 且 3.13截至 2024 年底最新版。为什么不能用 3.13因为其底层依赖pydantic v2尚未完全适配 3.13 的新语法变更。而为什么不能用 3.8因为asyncio的某些高级特性如TaskGroup在 3.9 才稳定引入OpenClaw 的并发任务调度强依赖于此。打开 CMD 或 PowerShell执行python --version如果输出是Python 3.8.10或Python 3.13.0请立刻停止。你需要安装Python 3.11.9当前最稳妥的 LTS 版本。去 python.org/downloads 下载Windows x86-64 executable installer注意不是 “embeddable zip file”那个没有 pip。安装时务必勾选 “Add Python to PATH”。这是 Windows 用户最容易忽略的致命一步。没勾选后续所有pip命令都会报“不是内部或外部命令”。安装完重启终端再执行where python where pip你应该看到两条路径且都指向你刚安装的 Python 目录下的python.exe和Scripts\pip.exe。如果where pip返回空说明 PATH 没生效手动添加计算机 → 属性 → 高级系统设置 → 环境变量 → 系统变量 → Path → 新建 → 输入你的 Python 安装路径\Scripts例如C:\Users\YourName\AppData\Local\Programs\Python\Python311\Scripts。2.2 第二重门虚拟环境隔离绝对不可跳过OpenClaw 依赖redis-py,httpx,playwright等库而你电脑上可能已有旧版本的requests或urllib3。全局安装会导致版本冲突。我见过最惨的案例一个同事全局pip install openclaw后他正在写的爬虫项目直接崩了因为 OpenClaw 升级了charset-normalizer到 3.x而他的爬虫依赖 2.x。正确做法用venv创建专属沙盒。# 进入你想存放项目的文件夹例如 D:\projects cd /d D:\projects # 创建名为 oc-env 的虚拟环境 python -m venv oc-env # 激活它PowerShell 用户注意需先执行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser oc-env\Scripts\activate.bat # 激活后命令行前缀会变成 (oc-env)激活成功后执行pip list你应该只看到pip,setuptools,wheel三个基础包。这就是干净的起点。2.3 第三重门关键依赖预检与加速源配置OpenClaw 安装时会拉取playwright用于网页自动化和redis用于任务状态存储。playwright默认下载 Chromium 浏览器二进制国内网络下常超时失败redis的 Python 客户端redis-py虽小但若 pip 源慢也会卡住。先换国内镜像源永久生效# 在激活的虚拟环境中执行 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple再预装playwright并指定浏览器避免安装时卡住pip install playwright playwright install chromium --with-deps--with-deps参数会自动安装 Windows 必需的系统依赖如 Visual C Redistributable省去后续报错重装的麻烦。最后验证 Redis 是否可用OpenClaw 默认用 Redis 存储 Agent 的运行状态# 下载 Redis for Windows 官方版非第三方编译版 # 地址https://github.com/microsoftarchive/redis/releases/tag/win-64.3.2.100 # 解压到 D:\redis然后启动服务 D:\redis\redis-server.exe --port 6379另开一个终端激活oc-env执行python -c import redis; r redis.Redis(hostlocalhost, port6379); print(r.ping())如果输出True说明 Redis 连通性 OK。如果报错ConnectionRefusedError检查redis-server.exe是否在后台运行任务管理器里看进程。注意很多教程说“OpenClaw 可以不用 Redis”那是针对极简 demo。一旦你要做真实 Agent比如让龙虾自动查股票、填表、发邮件Redis 是刚需。它负责记录每个步骤的输入/输出、错误堆栈、重试次数——没有它Agent 崩溃后你连它刚才干了什么都看不到。3. 核心安装从 PyPI 到可执行命令的完整链路当环境筑基完成oc-env激活redis-server运行playwright安装完毕我们才真正进入 OpenClaw 的安装环节。这里要破除一个最大误解pip install openclaw安装的不是一个“程序”而是一套 Python 库 一组 CLI 命令入口。它不会在开始菜单里给你加个图标也不会注册成 Windows 服务。它的“安装成功”体现在你能从命令行调用openclaw这个命令。3.1 安装命令与版本选择逻辑执行pip install openclaw这条命令会从 PyPI 拉取最新稳定版目前是0.5.2。但如果你追求稳定性建议指定版本pip install openclaw0.5.2为什么不是最新版因为 OpenClaw 更新频繁0.5.3 版本曾引入一个playwright的异步上下文 bug导致 Windows 上openclaw run命令卡死。官方 GitHub Issues 里有 20 条相关反馈。作为生产环境部署我永远推荐用经过社区验证的次新稳定版。安装过程约 2-3 分钟取决于网速你会看到大量Installing collected packages...日志。关键看最后一行是否是Successfully installed openclaw-0.5.2 ...。如果中间出现ERROR: Failed building wheel for xxx别慌——这通常是某个 C 扩展库如cryptography编译失败不影响主体功能。OpenClaw 的核心逻辑是纯 Python这些失败的包往往是可选依赖。3.2 验证安装从import到openclaw --help安装完成后分三步验证第一步Python 层验证python -c import openclaw; print(openclaw.__version__)输出0.5.2即通过。这证明 Python 解释器能找到openclaw包。第二步CLI 命令验证openclaw --help如果输出一大段帮助文本包含init,run,serve,list等子命令说明 CLI 入口已注册成功。这是最关键的一步。如果报错openclaw : 无法将“openclaw”项识别为 cmdlet...回到第 2.1 节重新检查Scripts目录是否在 PATH 中。常见错误是你用的是 PowerShell但activate.bat是为 CMD 设计的。此时应改用oc-env\Scripts\Activate.ps1并在 PowerShell 中执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser仅需一次。第三步初始化项目结构openclaw init my-agent cd my-agentopenclaw init会创建一个标准项目骨架my-agent/ ├── agent.py # 主 Agent 逻辑 ├── config.yaml # 配置文件LLM API Key、工具开关等 ├── skills/ # 自定义技能目录 │ └── __init__.py └── requirements.txt # 项目依赖打开config.yaml你会看到llm: provider: openai # 默认用 OpenAI可改为 ollama, qwen model: gpt-4o api_key: sk-... # 这里要填你的 Key这就是 OpenClaw 的设计哲学一切配置化不写死在代码里。你不需要改agent.py就能切换大模型供应商。3.3 关键配置项详解为什么config.yaml决定成败很多小白卡在openclaw run后无响应根源就在config.yaml。我们逐项拆解llm.provider: OpenClaw 支持openai,anthropic,ollama,qwen通义千问等。如果你用国内模型填qwen则model字段填qwen2.5-7bapi_key留空Ollama 和 Qwen 本地部署通常无需 Key。tools: 这是 OpenClaw 的灵魂。默认开启web_search,calculator,file_reader。如果你想让龙虾能操作 Excel必须手动添加tools: - name: excel_tool module: openclaw.tools.excel enabled: true然后在skills/目录下创建excel.py写具体实现。OpenClaw 不内置“万能工具”它只提供工具注册框架。所谓“龙虾部署千问模型”本质就是把qwen配成 provider并在tools里挂载你自己的业务 API。redis_url: 默认是redis://localhost:6379/0。如果你的 Redis 装在 NAS 或远程服务器这里要改成redis://192.168.1.100:6379/0。很多“NAS 部署 OpenClaw”失败就是因为没改这个 URL。实操心得我第一次部署时把api_key错误地填在了llm.api_key下而实际字段是llm.openai_api_key不同 provider 字段名不同。结果openclaw run启动后直接抛KeyError。教训是永远先看config.yaml里的注释或者用openclaw init --verbose查看生成的完整模板。注释里会明确写出每个 provider 对应的 key 名称。4. 首次运行从 Hello World 到真实 Agent 的跨越安装和配置只是铺路openclaw run才是真正的“点火”。但直接运行agent.py里的默认代码只会输出Hello, World!——这毫无意义。我们要让它做一件小事自动查询当前北京的天气并用一句话总结。这个例子覆盖了 OpenClaw 的核心能力调用工具天气 API、解析 LLM 输出、处理结构化数据。4.1 编写第一个 Agentagent.py的最小可行改造打开my-agent/agent.py默认内容是from openclaw import Agent agent Agent( nameMyAgent, descriptionA simple agent, instructionsYou are a helpful assistant. )把它替换成from openclaw import Agent from openclaw.tools import web_search # 定义一个天气查询技能 def get_beijing_weather(): 调用免费天气 API 获取北京天气 # 使用 OpenClaw 内置的 web_search 工具模拟真实项目应替换为 weatherapi.com result web_search(北京今日天气预报) return f根据搜索结果北京今天{result[:50]}... # 创建 Agent注入技能 agent Agent( nameWeatherAgent, description查询并总结北京天气, instructions 你是一个天气播报员。请用中文用一句话总结北京今天的天气情况。 你只能使用 get_beijing_weather 这个工具不要编造信息。 , tools[get_beijing_weather] # 把函数注册为工具 )关键点解析tools[get_beijing_weather]不是字符串名而是函数对象本身。OpenClaw 会在运行时自动序列化它。instructions里的你只能使用...是给 LLM 的硬性约束。实测发现如果写成“你可以使用”LLM 有 30% 概率忽略工具直接胡编。4.2 运行与调试openclaw run的隐藏参数在my-agent目录下执行openclaw run你会看到类似这样的输出[INFO] Starting WeatherAgent... [INFO] Calling tool: get_beijing_weather [INFO] Tool result: 根据搜索结果北京今天晴最高气温28度最低气温16度... [INFO] LLM response: 北京今天晴朗最高气温28度最低气温16度。成功但如果你看到[INFO] Calling tool: get_beijing_weather后就卡住大概率是web_search工具触发了反爬。此时要用--debug参数openclaw run --debug它会输出完整的 HTTP 请求头、响应体、LLM 的原始 prompt帮你定位是网络问题还是提示词问题。更实用的调试技巧用--log-level DEBUG查看 Redis 通信openclaw run --log-level DEBUG | findstr redis你会看到Storing step result in Redis key: ...证明状态确实在持久化。4.3 进阶连接千问模型Qwen的完整配置热词里高频出现“龙虾部署千问模型”说明本地大模型是刚需。假设你已用 Ollama 在本地运行 Qwen2.5ollama run qwen2.5:7b那么config.yaml修改为llm: provider: ollama model: qwen2.5:7b base_url: http://localhost:11434/v1 # Ollama 默认端口 api_key: ollama # Ollama 的 Key 固定为 ollama然后在agent.py中把instructions改成支持中文的instructions 你是一个中文天气播报员。请用简洁的中文用一句话总结北京今天的天气。 你只能使用 get_beijing_weather 这个工具不要编造信息。 再次openclaw run输出会是地道的中文。这就是 OpenClaw 的优势LLM Provider 是插件化的换模型只需改配置不用动一行业务代码。很多用户抱怨“腾讯龙虾”“妙答龙虾”绑定特定模型而 OpenClaw 天然解耦。踩坑实录我曾把base_url错写成http://localhost:11434漏了/v1结果openclaw run报错HTTP 404 Not Found。查了半小时日志才发现是 URL 路径问题。教训所有base_url必须严格匹配目标 API 的 OpenAPI 规范。Ollama 的/v1/chat/completions接口base_url就必须到/v1这一级。5. 彻底卸载为什么“控制面板卸载”对 OpenClaw 无效热词里“如何彻底卸载龙虾”出现频率极高这暴露了一个认知偏差用户以为 OpenClaw 是 Windows 软件有安装包、注册表、服务项。实际上它只是 Python 包卸载逻辑完全不同。5.1 正确卸载流程三步清零法第一步删除虚拟环境目录这是最核心的一步。找到你创建oc-env的位置比如D:\projects\oc-env直接删除整个oc-env文件夹。这会清除所有pip install的包包括openclaw及其依赖。不要用pip uninstall openclaw因为它可能残留依赖包污染未来环境。第二步清理 Redis 数据可选但推荐如果你用 Redis 存储了 Agent 运行历史执行redis-cli FLUSHDB这会清空当前数据库db 0的所有键值对。如果你改过redis_url的 db 编号比如redis://localhost:6379/1则用FLUSHDB 1。第三步删除项目目录my-agent文件夹可以删掉也可以留着当模板。里面只有你写的agent.py和config.yaml不占空间。5.2 常见卸载误区与后果误区1“用控制面板卸载 Python”这会把你电脑上所有 Python 项目包括 VSCode 的 Python 插件、PyCharm 的解释器全部搞崩。OpenClaw 不需要卸载 Python它只依赖虚拟环境。误区2“删掉C:\Users\XXX\AppData\Roaming\openclaw”OpenClaw 根本不创建这种全局配置目录。它的所有状态都在项目内的config.yaml和 Redis 里。这个路径是某些国产“龙虾”封装版的私有路径不是 OpenClaw 官方行为。误区3“在 CMD 里执行pip uninstall openclaw后就完了”如果你没激活虚拟环境pip uninstall卸载的是全局 Python 的包而你的openclaw run是在虚拟环境里执行的根本不受影响。卸载后openclaw --help依然能用。5.3 卸载后的环境验证确保“零残留”执行以下命令确认卸载干净# 1. 检查虚拟环境是否还存在 where oc-env\Scripts\activate.bat # 应该返回“找不到文件” # 2. 检查全局 Python 是否还有 openclaw pip list | findstr openclaw # 应该无输出 # 3. 检查 Redis 是否还有 OpenClaw 相关键 redis-cli KEYS oc:* # 应该返回 (empty array)如果以上三条都通过恭喜你的系统已回归“龙虾未临”状态。最后分享一个小技巧我给自己建了个cleanup.bat脚本放在D:\projects下echo off rmdir /s /q oc-env rmdir /s /q my-agent echo Redis cleanup: running FLUSHDB... redis-cli FLUSHDB echo Done. pause双击就能一键清场。对于经常测试不同 Agent 的人这比手动删目录快十倍。安装 OpenClaw 的本质不是给电脑装一个软件而是为你构建一个可控、可复现、可调试的 AI 工作流实验台。它不承诺“一键智能”但保证“每一步都可追溯”。那些热词里反复出现的“无法识别 openclaw”“部署失败”“卸载不干净”归根结底都是把开发者工具当成了用户软件来对待。当你理解了它的 Python 基因、虚拟环境依赖、配置驱动架构所谓的“小白专用教程”就变成了“任何人只要愿意花 20 分钟配好环境就能跑通第一个 Agent”的确定路径。我至今记得第一次看到openclaw run输出中文天气总结时的兴奋——那不是魔法是清晰的逻辑链条终于咬合的声音。
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
