OpenClaw最近在GitHub趋势榜上出现得挺频繁如果你对AI Agent感兴趣又恰好主力机是Windows那这篇就是你需要的。我花了一个完整的周末把OpenClaw在Windows上从零到一真正跑通包括环境准备、脚本安装、Docker部署、LLM配置和channel接入期间踩了不少Windows特有的坑比如session file locked、端口占用、Python路径混乱这些。这篇文章把整个过程和排错思路全部整理出来给你一条能直接照着走的完整路线省去你自己翻文档试错的时间。先说结论OpenClaw在Windows上是完全可以稳定运行的但前提是环境准备要按对顺序来前半程的耐心决定了后半程会不会崩。我会把每一步为什么要这么做讲清楚不是单纯给你一串命令而是让你明白出问题时该从哪里下手。1. 安装前的清醒认知1.1 OpenClaw到底是什么OpenClaw本质上是一个可自部署的AI Agent框架核心思路是LLM 工具调用 多通道接入。说人话就是你给它一个操作入口它能调用电脑上的工具帮你干活——查资料、读写文件、执行命令、管理笔记、收发消息都可以通过对话来驱动。你可以把它理解成一个能动手干活的AI助理。ChatGPT这类产品是你问它答OpenClaw是你让它做它真的去做。它内部会自己拆解任务、规划步骤、调用工具、检查结果直到把事情办完。比如你可以让它把Obsidian里所有包含TODO的笔记整理成一份清单它会自己去扫描Vault、解析文件、汇总输出整个过程中你只需要在聊天窗口里下达需求。目前OpenClaw支持多种接入渠道包括命令行CLI、Telegram、Discord、Slack、Microsoft Teams还有人把Obsidian接进来当知识库和操作面板用。这意味着它不只是一个后台脚本而是能嵌入你日常使用的工具链里像一个真正的工作搭档。1.2 部署方式怎么选OpenClaw在Windows上主要有三条安装路径我实际都试过各有取舍。部署方式优点缺点适合场景官方脚本一键安装省事、自动处理依赖出错时黑盒难排查大多数人首选Docker容器部署环境隔离、卸载干净需要Docker Desktop和WSL2性能损耗不想污染本机Python环境源码手动运行可调试、可看完整日志需手动装依赖最繁琐开发者、踩坑排障我自己最终的选择是先用脚本安装跑通全流程再用Docker部署了一个备用实例。因为脚本安装能最快验证这个项目适不适合我如果连基本运行都跑不起来再折腾Docker也是白费劲。等你确认它确实有用再考虑要不要用Docker做正式环境的隔离。这里有个很容易忽略的点OpenClaw对Python版本有明确要求不同版本的依赖行为差异很大。如果你本机同时装了多个Python版本脚本安装可能把依赖装进错误的Python环境里后面启动直接报ModuleNotFoundError。这也是为什么我强烈建议在安装前把Python环境梳理干净。1.3 Windows环境的三座山Windows上装OpenClaw最大的障碍不是OpenClaw本身而是Windows环境的三个老大难。第一是Python版本混乱。很多人电脑里既有Python 3.8又装了3.11还可能有Anaconda、PyCharm自带的解释器环境变量PATH里哪个在前哪个在后完全看运气。OpenClaw官方建议Python 3.10及以上实测3.11和3.12都能跑但如果你系统默认指向的是3.8那基本必炸。第二是终端工具的差异化。Windows下至少有三种终端环境CMD、PowerShell、Git Bash它们的语法、环境变量传递、路径处理方式都不一样。官方安装脚本是为bash写的在CMD里执行会直接报错在PowerShell里执行也可能因为执行策略(ExecutionPolicy)被拦下来。这一步就劝退了不少人。第三是Docker Desktop需要WSL2。如果你打算用Docker方式部署Windows必须先启用WSL2子系统并装好Linux发行版否则Docker Desktop起不来。这个流程本身不难但需要重启系统如果你正在开会或者赶工就很烦。我见过很多人在Windows上装OpenClaw失败翻来覆去排查OpenClaw的配置最后发现根源是Python版本不对或者终端用错了。环境层面的问题占了一大半。2. 环境准备先把地基打牢2.1 Python环境的确认与梳理在动手装OpenClaw之前先花十分钟确认Python环境。打开PowerShell或CMD依次执行下面三条命令python --version where python pip --version重点看两件事第一版本是否在3.10以上第二where python返回的路径是否指向你期望的那个Python。如果where python列出了多个路径说明PATH环境变量里有多个Python的注册项后安装的Python容易顶掉前面的。我遇到过一个典型的坑系统装了Visual Studio的Python组件PATH指向了C:\Program Files (x86)\Microsoft Visual Studio\Shared\Python版本是3.7而我自己装的3.11反而没被优先识别。OpenClaw用系统默认Python启动直接全部依赖装到3.7上了跑起来全是语法错误。解决方式很简单在系统环境变量里把3.11的路径及其Scripts子目录调整到Python相关路径的最前面然后新开一个终端窗口让环境变量生效。如果你机器上有Anaconda更建议用conda单独建一个虚拟环境给OpenClaw用彻底隔离依赖冲突conda create -n openclaw python3.11 conda activate openclaw这样做的好处是你之后安装的任何Python包都只在这个虚拟环境里生效不会污染系统Python将来想卸载OpenClaw直接删环境就行。实测下来conda虚拟环境安装OpenClaw的成功率比裸装高很多强烈建议。2.2 Git和Windows TerminalOpenClaw本身通过Git仓库分发而且后续更新也需要Git。Windows下安装Git很简单去官网下载安装包一路Next就行但有两个地方要注意。一个是安装时选择Add Git Bash to PATH这个选项否则后续命令行里找不到git命令。另一个是默认编辑器建议选VS Code方便你后面改OpenClaw的配置文件。装完之后在CMD里执行git --version确认返回版本号。Windows Terminal这个工具值得专门装一下。它是微软官方的现代终端好处是支持多标签页、自定义配色、兼容CMD/PowerShell/Git Bash而且对WSL2支持得很顺滑。OpenClaw跑在后台时日志输出量很大Windows Terminal的多标签功能可以让你一边开着CLI交互界面一边开着日志监控窗口排查问题效率高很多。2.3 VS Code改配置的必备工具OpenClaw的配置文件是JSON或TOML格式虽然用记事本也能改但JSON格式错误时记事本不会给你任何提示保存后OpenClaw直接解析失败。VS Code不仅会在你写错JSON格式时高亮标红还有补全和校验功能。把VS Code设置成Git的默认编辑器、配置好JSON格式校验是我在实践中最省心的组合。还有一点VS Code自带终端你可以在里面直接操作本地项目不需要另外开窗口。2.4 Docker Desktop与WSL2如果你是Docker路线的支持者环境准备阶段就需要把Docker Desktop装好。安装过程本身不难但有个前提Windows必须启用WSL2。启用WSL2的完整路径是控制面板 - 程序 - 启用或关闭Windows功能 - 勾选适用于Linux的Windows子系统和虚拟机平台重启后再在PowerShell里执行wsl --install装好之后在Docker Desktop的设置里把WSL2设为默认后端。然后拉取一个镜像测试docker run hello-world这一步能过说明Docker环境可用。如果卡在不能连Docker daemon多半是Docker Desktop没有真正启动或者WSL发行版没装好。检查系统托盘里Docker鲸鱼图标是否常亮即可。3. 核心安装实操两种方式完整记录3.1 官方脚本一键安装环境就绪后先切换到Git Bash环境因为官方安装脚本是bash脚本在CMD或PowerShell里执行会因语法差异而失败。打开Git Bash执行git clone https://github.com/openclaw/openclaw.git cd openclaw ./install.sh脚本会做的事情包括检查Python版本、创建虚拟环境如果有venv模块的话、用pip安装依赖、下载模型与默认配置文件。这个过程视网络情况可能需要5到20分钟中间会输出大量日志。此时就是把手机放到一边耐心等不要频繁CtrlC。安装完成后脚本会提示你初始化配置文件。默认情况下配置生成在用户目录下的.openclaw/文件夹中文件名通常是config.toml或config.yaml取决于当前版本。你可以在文件管理器里输入路径%USERPROFILE%\.openclaw直接访问。这里有个Windows特有的坑很多教程让你在用户目录执行openclaw init但Windows下如果路径中有中文用户名部分依赖库处理路径会出问题。比如C:\Users\张三\.openclaw某些原生模块就会在读写文件时编码崩溃。我踩过一次中文用户名的坑最终的解决方案是在新用户目录下或直接用英文路径的目录作为工作区。3.2 Docker容器部署如果你选择Docker路线步骤比脚本安装更直观。在PowerShell里拉取官方镜像并启动docker pull openclaw/openclaw:latest docker run -d --name openclaw -p 3000:3000 -v ${HOME}/.openclaw:/root/.openclaw openclaw/openclaw:latest这里有个关键的挂载点-v参数把容器内的配置目录映射到宿主机这样你在Windows里改的配置能直接同步到容器中生效不会因为容器重建而丢失。Docker部署的好处是本机Python环境再乱也不影响容器内部的运行。但要注意容器里默认只有最小运行环境如果你的Agent需要用到某些外部工具比如浏览器自动化、图片处理需要在镜像基础上额外安装或者把宿主机的工具通过挂载方式共享进去。我实际对比过两种方式的开销Docker方式启动速度略慢大概多花3到5秒但稳定性更好尤其适合需要长期跑后台Agent的场景不需要担心Windows系统更新或Python包冲突把它搞挂。脚本安装则胜在轻便改配置、重启服务都很直接适合日常开发和实验。两种方式的取舍还是那句话先脚本跑通逻辑再决定要不要容器化。不要一上来就Docker不然你连配置文件的日志输出路径都不知道在哪排查问题会非常别扭。3.3 安装后的第一轮验证安装完成不等于能用先做一轮最小化验证。在终端执行openclaw --version openclaw --doctor--doctor是OpenClaw自带的环境检查命令会逐项检测配置目录、Python环境、依赖库、网络连通性等。如果输出里有红色或者带PASS以外的状态说明某个环节还有问题先解决再继续。我建议至少确认这几项是正常的配置目录存在、核心依赖库可导入、LLM API key已填入。如果是刚装完就执行大概率会提示你还没有配置LLM这在当前阶段是正常的下面一节就来解决它。4. 配置与channel接入让Agent活起来4.1 配置文件结构拆解OpenClaw的默认配置文件虽然看起来不长但每个字段都对应实际功能。我拆解几个核心段落你就知道改哪里了。配置文件里首先是一个agent的定义段包含name、model provider、prompt模板、工具权限列表等。其中model字段是关键它决定你用的是Claude还是千问还是其他大模型。channels数组决定这个agent可以通过哪些渠道交互。另一个重要段落是llm或providers段里面按provider组织API配置比如Anthropic、OpenAI、阿里云百炼千问。这里填的是你的API key和模型名格式一般是[llm.providers.anthropic] api_key sk-... model claude-sonnet-4-5为了方便你操作建议先用记事本打开配置文件看一眼结构不要盲目修改。改完JSON或TOML后可以用VS Code的格式化功能检查语法是否正确再重启服务加载配置。4.2 接入LLMClaude与千问的实测对比OpenClaw设计上可以对接多种大模型我在Windows上实测过Claude和千问QWen各说优缺点。接入Claude的方式比较直接在配置文件的providers里填上Anthropic的API key和模型名即可。Claude在Agent场景下的工具调用能力很强步骤拆解清晰任务执行的成功率很高但需要订阅制或按量付费。如果你没有Claude订阅接入千问是性价比很高的选择。在阿里云百炼控制台开通模型服务拿到API key后配置里填对应字段模型名填qwen-plus或者更高能力的qwen-max。我实测用qwen-plus跑日常任务整理笔记、写脚本、总结文本完全够用胜在便宜。有人问我接入哪个模型好我的建议是先用手头已有的账号把流程跑通重点验证OpenClaw是否满足你的需求然后再决定是否要付费升级模型。模型是Agent大脑但OpenClaw的框架设计决定了即使换模型生态接入方式和任务处理逻辑都不用大改。这里有一个Windows容易遇到的坑如果你设置的代理环境变量导致API请求转发异常OpenClaw调LLM时会超时或报证书错误。建议在配置文件里仔细检查是否有跟网络相关的代理设置项如果不需要就直接留空避免与本机系统代理产生冲突。4.3 channel怎么选从CLI到消息平台热词里有人问openclaw agent怎么选择channel这个我专门展开说说。channel就是你和Agent对话的通道OpenClaw支持同时启用多个channel配置文件中对应channels数组。第一次接触OpenClaw的人建议只启用CLI channel也就是在终端里直接交互。这样能最快看到效果也最容易排查问题。CLI模式下启动命令是openclaw run你会看到一个交互式的消息界面可以输入指令测试Agent的响应。比如输入你好Agent应该会回复并展示它的思考过程。如果这里能正常对话说明安装、配置、LLM接入三个环节都通过了。CLI跑通之后再考虑把Agent接到日常使用的聊天平台。接入Telegram需要在BotFather那里创建一个bot拿到bot token后填进配置里再指定channels [telegram]。接入Microsoft Teams则需要注册一个应用流程相对繁琐适合团队协作场景。如果你想用Obsidian做知识库OpenClaw也支持相关接入能力但配置项较多建议等基础channel稳定后再尝试。这里有一个容易被忽略的细节channel的启用不是改完配置文件就立刻生效的。你需要重启OpenClaw服务进程有时还要先执行openclaw init重新生成相关的会话状态文件。很多人改完配置发现没变化原因就是没有重启。以我自己为例我最终在Windows上稳定运行的组合是CLI Telegram双channelLLM模型用千问跑日常任务Claude处理复杂脚本生成。OpenClaw作为常驻后台服务跑在系统托盘日志输出到指定文件用VS Code随时查看。5. 常见问题与排查技巧实录5.1session file locked (timeout 60000ms)怎么解决这个报错是热词里出现频率最高的一个全称是agent failed before reply: session file locked (timeout 60000ms)。它表示Agent在尝试读写会话文件时等待锁超时了。出现这个问题的原因一般有两种。第一种是上次OpenClaw进程没有正常退出留下了残留的锁文件导致新进程拿不到锁。第二种是你同时启动了多个OpenClaw实例两个进程在争抢同一个会话文件的读写权。我自己的排查步骤是这样的先确认有没有多个OpenClaw进程在跑。在PowerShell执行Get-Process | Where-Object {$_.ProcessName -like *claw*}把多余的进程结束掉只留一个。删除会话目录下的锁文件。OpenClaw的会话文件通常存放在~/.openclaw/sessions/里面有.lock后缀的文件直接删掉即可。在某些版本里锁文件是隐藏文件需要在文件管理器里开启显示隐藏项目。重启OpenClaw服务openclaw run重新加载会话。如果你用Docker部署锁问题也常见于宿主机和容器之间的挂载目录权限不一致导致容器内进程无法写入、锁文件永远存在。这时候检查挂载目录的读写权限就好。这个问题最烦的地方在于它不影响配置检测所以openclaw --doctor查不出异常只有真正对话时才报错。这个坑我踩得最深当时一度怀疑是配置文件损坏来回删了三次配置最后才发现是两个残留进程在作怪。5.2 端口占用与关闭方法OpenClaw的Web服务默认监听3000端口如果这个端口被其他程序占用服务就起不来。Windows下查看端口占用最直接的方式netstat -ano | findstr :3000拿到最后一列的PID数字后再执行taskkill /PID 这里填PID数字 /F我遇到过两次3000端口被占的情况一次是本地开发调试用的Node服务占着另一次是之前Docker容器没释放端口。确认端口占用是Windows上的常见问题很多时候不用重启电脑用上面的命令强制结束对应进程就行。建议顺手在防火墙里放行3000端口避免外部设备访问不到。5.3 其他Windows经典坑汇总经历了几天的折腾我发现OpenClaw在Windows下的问题很多都有共性。把这些常见问题整理成速查表希望能帮你省下排查时间问题现象根本原因排查方向中文路径导致配置文件读写异常Windows用户名或目录路径含中文换用全英文路径的工作区或迁移用户配置目录CMD/PowerShell执行命令报语法错误官方脚本是bash语法切换到Git Bash或WSL环境执行Python包装错环境PATH优先级错乱用conda创建独立虚拟环境确保where python指向正确版本LLM API调用超时或证书报错本机代理配置干扰检查系统代理和配置文件中相关网络项服务启动即闪退依赖库缺失或版本不兼容用openclaw --doctor一步步定位缺失项Docker容器内的会话锁冲突挂载目录权限不一致检查-v挂载的宿主机目录权限必要时重新授权还有一个经验值得分享Windows上日志查看不如Linux方便可以给OpenClaw设置文件日志输出路径建议用绝对路径并指向一个专门目录比如D:\openclaw\logs。这样每次启动后日志都沉淀在固定位置报错时直接打开最新日志文件搜关键词比在终端里翻历史输出高效太多。关于OpenClaw和WorkBuddy哪个好的问题我插一句。这两个不是同一个定位WorkBuddy偏商业化客服自动化OpenClaw偏个人可自部署的Agent助手你可以自己host、自己掌控数据、自由切换模型。如果你愿意折腾、又希望数据掌握在自己手里OpenClaw明显更合适。最后再分享一个我个人的实操体会在Windows上跑OpenClaw最大的敌人不是OpenClaw本身而是Windows环境里各种历史遗留的杂音。Python版本、终端差异、路径问题、端口占用——每一个单独拿出来都不难解决但它们叠在一起就会让人怀疑人生。所以我的建议是安装之前先把第二章环境准备踏踏实实过一遍后面安装配置大概率就是一次过。等你CLI跑通、模型接入、channel也能对话之后你就会觉得这个折腾是值回票价的。 OpenClaw最近在GitHub趋势榜上出现得挺频繁如果你对AI Agent感兴趣又恰好主力机是Windows那这篇就是你需要的。我花了一个完整的周末把OpenClaw在Windows上从零到一真正跑通包括环境准备、脚本安装、Docker部署、LLM配置和channel接入期间踩了不少Windows特有的坑比如session file locked、端口占用、Python路径混乱这些。这篇文章把整个过程和排错思路全部整理出来给你一条能直接照着走的完整路线省去你自己翻文档试错的时间。先说结论OpenClaw在Windows上是完全可以稳定运行的但前提是环境准备要按对顺序来前半程的耐心决定了后半程会不会崩。我会把每一步为什么要这么做讲清楚不是单纯给你一串命令而是让你明白出问题时该从哪里下手。1. 安装前的清醒认知1.1 OpenClaw到底是什么OpenClaw本质上是一个可自部署的AI Agent框架核心思路是LLM 工具调用 多通道接入。说人话就是你给它一个操作入口它能调用电脑上的工具帮你干活——查资料、读写文件、执行命令、管理笔记、收发消息都可以通过对话来驱动。你可以把它理解成一个能动手干活的AI助理。ChatGPT这类产品是你问它答OpenClaw是你让它做它真的去做。它内部会自己拆解任务、规划步骤、调用工具、检查结果直到把事情办完。比如你可以让它把Obsidian里所有包含TODO的笔记整理成一份清单它会自己去扫描Vault、解析文件、汇总输出整个过程中你只需要在聊天窗口里下达需求。目前OpenClaw支持多种接入渠道包括命令行CLI、Telegram、Discord、Slack、Microsoft Teams还有人把Obsidian接进来当知识库和操作面板用。这意味着它不只是一个后台脚本而是能嵌入你日常使用的工具链里像一个真正的工作搭档。1.2 部署方式怎么选OpenClaw在Windows上主要有三条安装路径我实际都试过各有取舍。部署方式优点缺点适合场景官方脚本一键安装省事、自动处理依赖出错时黑盒难排查大多数人首选Docker容器部署环境隔离、卸载干净需要Docker Desktop和WSL2性能损耗不想污染本机Python环境源码手动运行可调试、可看完整日志需手动装依赖最繁琐开发者、踩坑排障我自己最终的选择是先用脚本安装跑通全流程再用Docker部署了一个备用实例。因为脚本安装能最快验证这个项目适不适合我如果连基本运行都跑不起来再折腾Docker也是白费劲。等你确认它确实有用再考虑要不要用Docker做正式环境的隔离。这里有个很容易忽略的点OpenClaw对Python版本有明确要求不同版本的依赖行为差异很大。如果你本机同时装了多个Python版本脚本安装可能把依赖装进错误的Python环境里后面启动直接报ModuleNotFoundError。这也是为什么我强烈建议在安装前把Python环境梳理干净。1.3 Windows环境的三座山Windows上装OpenClaw最大的障碍不是OpenClaw本身而是Windows环境的三个老大难。第一是Python版本混乱。很多人电脑里既有Python 3.8又装了3.11还可能有Anaconda、PyCharm自带的解释器环境变量PATH里哪个在前哪个在后完全看运气。OpenClaw官方建议Python 3.10及以上实测3.11和3.12都能跑但如果你系统默认指向的是3.8那基本必炸。第二是终端工具的差异化。Windows下至少有三种终端环境CMD、PowerShell、Git Bash它们的语法、环境变量传递、路径处理方式都不一样。官方安装脚本是为bash写的在CMD里执行会直接报错在PowerShell里执行也可能因为执行策略(ExecutionPolicy)被拦下来。这一步就劝退了不少人。第三是Docker Desktop需要WSL2。如果你打算用Docker方式部署Windows必须先启用WSL2子系统并装好Linux发行版否则Docker Desktop起不来。这个流程本身不难但需要重启系统如果你正在开会或者赶工就很烦。我见过很多人在Windows上装OpenClaw失败翻来覆去排查OpenClaw的配置最后发现根源是Python版本不对或者终端用错了。环境层面的问题占了一大半。2. 环境准备先把地基打牢2.1 Python环境的确认与梳理在动手装OpenClaw之前先花十分钟确认Python环境。打开PowerShell或CMD依次执行下面三条命令python --version where python pip --version重点看两件事第一版本是否在3.10以上第二where python返回的路径是否指向你期望的那个Python。如果where python列出了多个路径说明PATH环境变量里有多个Python的注册项后安装的Python容易顶掉前面的。我遇到过一个典型的坑系统装了Visual Studio的Python组件PATH指向了C:\Program Files (x86)\Microsoft Visual Studio\Shared\Python版本是3.7而我自己装的3.11反而没被优先识别。OpenClaw用系统默认Python启动直接全部依赖装到3.7上了跑起来全是语法错误。解决方式很简单在系统环境变量里把3.11的路径及其Scripts子目录调整到Python相关路径的最前面然后新开一个终端窗口让环境变量生效。如果你机器上有Anaconda更建议用conda单独建一个虚拟环境给OpenClaw用彻底隔离依赖冲突conda create -n openclaw python3.11 conda activate openclaw这样做的好处是你之后安装的任何Python包都只在这个虚拟环境里生效不会污染系统Python将来想卸载OpenClaw直接删环境就行。实测下来conda虚拟环境安装OpenClaw的成功率比裸装高很多强烈建议。2.2 Git和Windows TerminalOpenClaw本身通过Git仓库分发而且后续更新也需要Git。Windows下安装Git很简单去官网下载安装包一路Next就行但有两个地方要注意。一个是安装时选择Add Git Bash to PATH这个选项否则后续命令行里找不到git命令。另一个是默认编辑器建议选VS Code方便你后面改OpenClaw的配置文件。装完之后在CMD里执行git --version确认返回版本号。Windows Terminal这个工具值得专门装一下。它是微软官方的现代终端好处是支持多标签页、自定义配色、兼容CMD/PowerShell/Git Bash而且对WSL2支持得很顺滑。OpenClaw跑在后台时日志输出量很大Windows Terminal的多标签功能可以让你一边开着CLI交互界面一边开着日志监控窗口排查问题效率高很多。2.3 VS Code改配置的必备工具OpenClaw的配置文件是JSON或TOML格式虽然用记事本也能改但JSON格式错误时记事本不会给你任何提示保存后OpenClaw直接解析失败。VS Code不仅会在你写错JSON格式时高亮标红还有补全和校验功能。把VS Code设置成Git的默认编辑器、配置好JSON格式校验是我在实践中最省心的组合。还有一点VS Code自带终端你可以在里面直接操作本地项目不需要另外开窗口。2.4 Docker Desktop与WSL2如果你是Docker路线的支持者环境准备阶段就需要把Docker Desktop装好。安装过程本身不难但有个前提Windows必须启用WSL2。启用WSL2的完整路径是控制面板 - 程序 - 启用或关闭Windows功能 - 勾选适用于Linux的Windows子系统和虚拟机平台重启后再在PowerShell里执行wsl --install装好之后在Docker Desktop的设置里把WSL2设为默认后端。然后拉取一个镜像测试docker run hello-world这一步能过说明Docker环境可用。如果卡在不能连Docker daemon多半是Docker Desktop没有真正启动或者WSL发行版没装好。检查系统托盘里Docker鲸鱼图标是否常亮即可。3. 核心安装实操两种方式完整记录3.1 官方脚本一键安装环境就绪后先切换到Git Bash环境因为官方安装脚本是bash脚本在CMD或PowerShell里执行会因语法差异而失败。打开Git Bash执行git clone https://github.com/openclaw/openclaw.git cd openclaw ./install.sh脚本会做的事情包括检查Python版本、创建虚拟环境如果有venv模块的话、用pip安装依赖、下载模型与默认配置文件。这个过程视网络情况可能需要5到20分钟中间会输出大量日志。此时就是把手机放到一边耐心等不要频繁CtrlC。安装完成后脚本会提示你初始化配置文件。默认情况下配置生成在用户目录下的.openclaw/文件夹中文件名通常是config.toml或config.yaml取决于当前版本。你可以在文件管理器里输入路径%USERPROFILE%\.openclaw直接访问。这里有个Windows特有的坑很多教程让你在用户目录执行openclaw init但Windows下如果路径中有中文用户名部分依赖库处理路径会出问题。比如C:\Users\张三\.openclaw某些原生模块就会在读写文件时编码崩溃。我踩过一次中文用户名的坑最终的解决方案是在新用户目录下或直接用英文路径的目录作为工作区。3.2 Docker容器部署如果你选择Docker路线步骤比脚本安装更直观。在PowerShell里拉取官方镜像并启动docker pull openclaw/openclaw:latest docker run -d --name openclaw -p 3000:3000 -v ${HOME}/.openclaw:/root/.openclaw openclaw/openclaw:latest这里有个关键的挂载点-v参数把容器内的配置目录映射到宿主机这样你在Windows里改的配置能直接同步到容器中生效不会因为容器重建而丢失。Docker部署的好处是本机Python环境再乱也不影响容器内部的运行。但要注意容器里默认只有最小运行环境如果你的Agent需要用到某些外部工具比如浏览器自动化、图片处理需要在镜像基础上额外安装或者把宿主机的工具通过挂载方式共享进去。我实际对比过两种方式的开销Docker方式启动速度略慢大概多花3到5秒但稳定性更好尤其适合需要长期跑后台Agent的场景不需要担心Windows系统更新或Python包冲突把它搞挂。脚本安装则胜在轻便改配置、重启服务都很直接适合日常开发和实验。两种方式的取舍还是那句话先脚本跑通逻辑再决定要不要容器化。不要一上来就Docker不然你连配置文件的日志输出路径都不知道在哪排查问题会非常别扭。3.3 安装后的第一轮验证安装完成不等于能用先做一轮最小化验证。在终端执行openclaw --version openclaw --doctor--doctor是OpenClaw自带的环境检查命令会逐项检测配置目录、Python环境、依赖库、网络连通性等。如果输出里有红色或者带PASS以外的状态说明某个环节还有问题先解决再继续。我建议至少确认这几项是正常的配置目录存在、核心依赖库可导入、LLM API key已填入。如果是刚装完就执行大概率会提示你还没有配置LLM这在当前阶段是正常的下面一节就来解决它。4. 配置与channel接入让Agent活起来4.1 配置文件结构拆解OpenClaw的默认配置文件虽然看起来不长但每个字段都对应实际功能。我拆解几个核心段落你就知道改哪里了。配置文件里首先是一个agent的定义段包含name、model provider、prompt模板、工具权限列表等。其中model字段是关键它决定你用的是Claude还是千问还是其他大模型。channels数组决定这个agent可以通过哪些渠道交互。另一个重要段落是llm或providers段里面按provider组织API配置比如Anthropic、OpenAI、阿里云百炼千问。这里填的是你的API key和模型名格式一般是[llm.providers.anthropic] api_key sk-... model claude-sonnet-4-5为了方便你操作建议先用记事本打开配置文件看一眼结构不要盲目修改。改完JSON或TOML后可以用VS Code的格式化功能检查语法是否正确再重启服务加载配置。4.2 接入LLMClaude与千问的实测对比OpenClaw设计上可以对接多种大模型我在Windows上实测过Claude和千问QWen各说优缺点。接入Claude的方式比较直接在配置文件的providers里填上Anthropic的API key和模型名即可。Claude在Agent场景下的工具调用能力很强步骤拆解清晰任务执行的成功率很高但需要订阅制或按量付费。如果你没有Claude订阅接入千问是性价比很高的选择。在阿里云百炼控制台开通模型服务拿到API key后配置里填对应字段模型名填qwen-plus或者更高能力的qwen-max。我实测用qwen-plus跑日常任务整理笔记、写脚本、总结文本完全够用胜在便宜。有人问我接入哪个模型好我的建议是先用手头已有的账号把流程跑通重点验证OpenClaw是否满足你的需求然后再决定是否要付费升级模型。模型是Agent大脑但OpenClaw的框架设计决定了即使换模型生态接入方式和任务处理逻辑都不用大改。这里有一个Windows容易遇到的坑如果你设置的代理环境变量导致API请求转发异常OpenClaw调LLM时会超时或报证书错误。建议在配置文件里仔细检查是否有跟网络相关的代理设置项如果不需要就直接留空避免与本机系统代理产生冲突。4.3 channel怎么选从CLI到消息平台热词里有人问openclaw agent怎么选择channel这个我专门展开说说。channel就是你和Agent对话的通道OpenClaw支持同时启用多个channel配置文件中对应channels数组。第一次接触OpenClaw的人建议只启用CLI channel也就是在终端里直接交互。这样能最快看到效果也最容易排查问题。CLI模式下启动命令是openclaw run你会看到一个交互式的消息界面可以输入指令测试Agent的响应。比如输入你好Agent应该会回复并展示它的思考过程。如果这里能正常对话说明安装、配置、LLM接入三个环节都通过了。CLI跑通之后再考虑把Agent接到日常使用的聊天平台。接入Telegram需要在BotFather那里创建一个bot拿到bot token后填进配置里再指定channels [telegram]。接入Microsoft Teams则需要注册一个应用流程相对繁琐适合团队协作场景。如果你想用Obsidian做知识库OpenClaw也支持相关接入能力但配置项较多建议等基础channel稳定后再尝试。这里有一个容易被忽略的细节channel的启用不是改完配置文件就立刻生效的。你需要重启OpenClaw服务进程有时还要先执行openclaw init重新生成相关的会话状态文件。很多人改完配置发现没变化原因就是没有重启。以我自己为例我最终在Windows上稳定运行的组合是CLI Telegram双channelLLM模型用千问跑日常任务Claude处理复杂脚本生成。OpenClaw作为常驻后台服务跑在系统托盘日志输出到指定文件用VS Code随时查看。5. 常见问题与排查技巧实录5.1session file locked (timeout 60000ms)怎么解决这个报错是热词里出现频率最高的一个全称是agent failed before reply: session file locked (timeout 60000ms)。它表示Agent在尝试读写会话文件时等待锁超时了。出现这个问题的原因一般有两种。第一种是上次OpenClaw进程没有正常退出留下了残留的锁文件导致新进程拿不到锁。第二种是你同时启动了多个OpenClaw实例两个进程在争抢同一个会话文件的读写权。我自己的排查步骤是这样的先确认有没有多个OpenClaw进程在跑。在PowerShell执行Get-Process | Where-Object {$_.ProcessName -like *claw*}把多余的进程结束掉只留一个。删除会话目录下的锁文件。OpenClaw的会话文件通常存放在~/.openclaw/sessions/里面有.lock后缀的文件直接删掉即可。在某些版本里锁文件是隐藏文件需要在文件管理器里开启显示隐藏项目。重启OpenClaw服务openclaw run重新加载会话。如果你用Docker部署锁问题也常见于宿主机和容器之间的挂载目录权限不一致导致容器内进程无法写入、锁文件永远存在。这时候检查挂载目录的读写权限就好。这个问题最烦的地方在于它不影响配置检测所以openclaw --doctor查不出异常只有真正对话时才报错。这个坑我踩得最深当时一度怀疑是配置文件损坏来回删了三次配置最后才发现是两个残留进程在作怪。5.2 端口占用与关闭方法OpenClaw的Web服务默认监听3000端口如果这个端口被其他程序占用服务就起不来。Windows下查看端口占用最直接的方式netstat -ano | findstr :3000拿到最后一列的PID数字后再执行taskkill /PID 这里填PID数字 /F我遇到过两次3000端口被占的情况一次是本地开发调试用的Node服务占着另一次是之前Docker容器没释放端口。确认端口占用是Windows上的常见问题很多时候不用重启电脑用上面的命令强制结束对应进程就行。建议顺手在防火墙里放行3000端口避免外部设备访问不到。5.3 其他Windows经典坑汇总经历了几天的折腾我发现OpenClaw在Windows下的问题很多都有共性。把这些常见问题整理成速查表希望能帮你省下排查时间问题现象根本原因排查方向中文路径导致配置文件读写异常Windows用户名或目录路径含中文换用全英文路径的工作区或迁移用户配置目录CMD/PowerShell执行命令报语法错误官方脚本是bash语法切换到Git Bash或WSL环境执行Python包装错环境PATH优先级错乱用conda创建独立虚拟环境确保where python指向正确版本LLM API调用超时或证书报错本机代理配置干扰检查系统代理和配置文件中相关网络项服务启动即闪退依赖库缺失或版本不兼容用openclaw --doctor一步步定位缺失项Docker容器内的会话锁冲突挂载目录权限不一致检查-v挂载的宿主机目录权限必要时重新授权还有一个经验值得分享Windows上日志查看不如Linux方便可以给OpenClaw设置文件日志输出路径建议用绝对路径并指向一个专门目录比如D:\openclaw\logs。这样每次启动后日志都沉淀在固定位置报错时直接打开最新日志文件搜关键词比在终端里翻历史输出高效太多。关于OpenClaw和WorkBuddy哪个好的问题我插一句。这两个不是同一个定位WorkBuddy偏商业化客服自动化OpenClaw偏个人可自部署的Agent助手你可以自己host、自己掌控数据、自由切换模型。如果你愿意折腾、又希望数据掌握在自己手里OpenClaw明显更合适。最后再分享一个我个人的实操体会在Windows上跑OpenClaw最大的敌人不是OpenClaw本身而是Windows环境里各种历史遗留的杂音。Python版本、终端差异、路径问题、端口占用——每一个单独拿出来都不难解决但它们叠在一起就会让人怀疑人生。所以我的建议是安装之前先把第二章环境准备踏踏实实过一遍后面安装配置大概率就是一次过。等你CLI跑通、模型接入、channel也能对话之后你就会觉得这个折腾是值回票价的。