最近把 OpenClaw 在 Windows 原生环境里完整跑通了一遍从源码拉取到网关连通中间踩了不少坑。网上搜 OpenClaw 的教程要么默认你有 Docker要么思路不完整实际照着做总会卡在某一步。这篇把我自己的实操过程整理成一份避坑版指南目标是让你在一台干净的中文 Windows 机器上不用装虚拟机、不用开 WSL、不用碰 Docker Desktop直接把 OpenClaw 跑起来并且把本机网关和外部通道比如 Microsoft Teams真正连通。先说清楚 OpenClaw 是什么免得你装完还不知道自己在干什么。它是一个开源的个人 AI 代理网关负责接收来自不同渠道的请求把请求交给配置好的大模型去理解和规划再调用本地工具文件操作、Obsidian 笔记、命令行执行动作最后把结果原路返回。一句话概括它像一个本地的前台所有聊天、办公、自动化入口都先经过它再由它调度后面的模型和工具。为什么非要强调“Windows 原生”因为很多同类项目要么只支持 Linux/macOS要么推荐你用 Docker 隔离环境。直接在 Windows 里装最大的痛点是环境变量、虚拟环境、进程常驻、端口占用这些细节。这篇文章会把安装、配置、连通、排错完整走一遍适合有一点点命令行基础、想把 AI 接入本地工作流的人。1. 环境盘点与准备工作1.1 OpenClaw 在 Windows 上的依赖清单动手之前先摸清家底。OpenClaw 核心是 Python 写的所以 Python 环境是必须的。另外它用 Git 做版本管理部分扩展通道会依赖 Node.js但不是硬性要求。我的建议是不管用不用得上先把 Python 和 Git 装好Node 可以等到某个连接器明确报错再补。我使用的版本组合Windows 11 专业版23H2 以上系统版本不要太老Python 3.11.93.10 也行但 3.12 我实测会遇到个别依赖编译问题Git 2.45.0 以上Node.js 20 LTS可选用于 Obsidian 相关扩展如果你的系统是 Windows 10理论上也能跑但务必确保系统补丁更新到较新版本。OpenClaw 用了一些很新的异步 I/O 库老版本系统的 TLS 协议支持不够会和模型 API 建立连接时握手失败。还有一个容易被忽略的问题整个项目路径千万不要带空格和中文。我最早把项目放在D:\Program Files\OpenClaw结果很多 Python 包在解析路径时直接炸掉。建议统一用类似D:\dev\openclaw这样的纯英文无空格目录。1.2 安装 Python 并解决 PATH 的坑从 Python 官网下载 3.11.9 安装包双击安装记住一定要勾选Add python.exe to PATH。这一步勾选后下面很多命令才能直接用。装完打开新终端输入python --version如果你看到的是 Microsoft Store 自动跳转或者弹出一个“应用执行别名”的提示说明你机器上 的python命令被商店的占位程序劫持了。解决方法是进入 Windows 设置 → 应用 → 高级应用设置 → 应用执行别名把python.exe和python3.exe两个开关关掉。然后重新打开终端再执行python --version。如果你的机器已经装了多个 Python 版本建议用py -3.11来指定版本py -3.11 --version后面创建虚拟环境时也用py -3.11 -m venv避免把 Python 3.9 的旧环境带进来。检查 pippython -m pip --version如果 pip 版本太老先升级python -m pip install --upgrade pipPowerShell 用户注意执行外部脚本时如果报“禁止运行脚本”你需要先放开执行策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这步不改后面激活虚拟环境的activate.ps1会直接报错。1.3 安装 Git 和 Node可选但建议装Git 用于拉取 OpenClaw 源码。去 Git 官网下载安装包一路默认即可。注意安装界面里有一个“调整 PATH 环境变量”的选项保持默认的 “Git from the command line and also from 3rd-party software” 就行。装完验证git --versionNode.js 不是核心依赖但如果你计划让 OpenClaw 联动 Obsidian 插件或某些 Node 写的连接器建议直接装 20 LTS。装完验证node --version npm --version装这些的先后顺序没有严格要求但建议每装完一个就开一个新的终端窗口因为环境变量只在新窗口才会刷新。旧终端里继续输入命令大概率还是找不到刚装的工具。2. 安装 OpenClaw 核心组件2.1 获取源码与目录规划OpenClaw 建议通过源码方式安装不用 pip 直接装一个包因为它的配置模板和连接器都放在仓库里。先创建一个干净的目录mkdir D:\dev\openclaw cd D:\dev\openclaw从官方仓库克隆代码git clone https://github.com/openclaw/openclaw.git .注意仓库地址以官方实际为准。如果你访问 GitHub 比较慢也可以直接在浏览器下载 zip 包解压到当前目录。zip 方式同样能跑只是后续更新需要手动重新下载。拉完代码后先看一眼目录结构至少应该看到requirements.txt、config.yaml.example、src或openclaw核心包、channels连接器目录。如果目录是空的检查是否 clone 失败常见原因是网络问题导致的半成品目录用git status看看有没有报错。2.2 创建虚拟环境并安装依赖千万不要直接使用全局 Python 环境装 OpenClaw因为它的依赖版本和其他项目很容易冲突。在项目根目录创建虚拟环境python -m venv .venv创建完成后激活虚拟环境。CMD 用户执行.venv\Scripts\activate.batPowerShell 用户执行.venv\Scripts\Activate.ps1激活成功的标志是命令行提示符前面出现(.venv)。如果 PowerShell 报执行策略回到前面设置RemoteSigned。接下来升级 pip 并配置国内镜像源。这一步非常建议做尤其是依赖安装经常超时的用户python -m pip install --upgrade pip pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple然后安装项目依赖pip install -r requirements.txt这里有几个常见报错先给你提前预警提示Microsoft Visual C 14.0 or greater is required说明某个依赖需要本地编译。解决办法是安装 Visual Studio Build Tools安装时勾选“使用 C 的桌面开发”重新打开终端再装。提示某个包找不到先确认镜像源配置成功再试着单独安装那个包比如pip install pydantic。提示 Python 版本过新如果你的 Python 是 3.12某些 RUST 扩展可能没有预编译的 wheel。最稳妥的方案是回退到 3.11.9。依赖装完验证核心模块能导入python -c import openclaw; print(openclaw.__version__)如果你看到版本号说明核心安装成功。2.3 初始化配置与环境变量OpenClaw 自带初始化命令用于生成默认配置文件和密钥文件。在虚拟环境激活状态下执行openclaw init这个命令会在当前用户目录或OPENCLAW_HOME指向的目录下生成config.yaml和.env。如果提示找不到openclaw命令先检查虚拟环境里有没有装入口脚本pip show openclaw没有的话尝试python -m openclaw init。初始化过程中可能要求你填写模型 API Key也可以后面再改。建议先随便填一个占位符后续在配置文件里统一替换。Windows 下为了让 OpenClaw 的会话数据不散落在系统盘的用户文件夹建议手动指定OPENCLAW_HOME。在项目根目录建一个data文件夹然后设置用户环境变量[Environment]::SetEnvironmentVariable(OPENCLAW_HOME, D:\dev\openclaw\data, User)CMD 用户可以用setx OPENCLAW_HOME D:\dev\openclaw\data。设置完后关掉当前终端重新开一个。验证echo %OPENCLAW_HOME%后续所有会话、日志、锁文件都会集中在这个目录排查问题时非常方便。3. 配置网关与通道连通3.1 理解 OpenClaw 的“网关”到底在干什么很多第一次接触 OpenClaw 的人会被“网关”这个词吓到以为要配很复杂的网络设备。实际上这里的网关指的是应用层的消息路由中枢不是防火墙或路由器。你可以把它想象成公司前台Microsoft Teams 发来的消息、Obsidian 里的命令、命令行里的提问全部先到这个前台前台根据内容判断应该交给哪个大模型去理解再调用相应的本地工具去执行执行完的结果由前台整理原路返回到对应的入口。理解这个架构非常重要因为后面排错基本都是围绕“请求进来 → 路由处理 → 模型回复 → 结果返回”这条链路去排查。任何一环断开你会看到不同的报错。OpenClaw 的配置核心在config.yaml。这个文件通常包含三块llm模型后端、channels消息通道、tools本地工具。下面我逐个说。3.2 配置模型后端LLM Provider先配置模型确保网关有一双能“思考”的眼睛。打开config.yaml找到llm部分。使用兼容 OpenAI 接口的模型配置如下示例llm: provider: openai_compatible model: gpt-4o-mini api_key: ${OPENAI_API_KEY} base_url: https://api.openai.com/v1 temperature: 0.7 max_tokens: 4096这里的${OPENAI_API_KEY}是从.env文件读取的不要直接把密钥硬编码到config.yaml因为配置文件你可能要分享或备份。在项目根目录的.env里写入OPENAI_API_KEYsk-xxxxxxxxxxxxxxxx如果你用的是本地模型比如 Ollamabase_url改成http://localhost:11434/v1model改成你这个 Ollama 里实际拉取的模型名llm: provider: openai_compatible model: llama3.1 api_key: ollama base_url: http://localhost:11434/v1配置本地模型的好处是调试阶段不花钱也避免网络波动问题。但注意本地模型的意图理解能力相比商业模型还是弱一些如果你要接 Teams 或复杂工具调用建议先用云端模型把链路跑通再换本地模型优化成本。为什么用openai_compatible而不是直接写死某一家因为这个接口协议最通用几乎所有主流模型服务都兼容换模型时只需要改base_url和model不用改其他逻辑。3.3 接入 Microsoft Teams 通道这是标题里“网关连通”的典型场景。接入 Teams 意味着你可以在 Teams 聊天里直接给机器人发消息机器人会调用 OpenClaw执行模型和工具链然后把结果回发到 Teams 对话里。配置分为两部分一侧是 Azure 里的 Bot 应用另一侧是 OpenClaw 的channels.teams配置。首先在 Azure 门户注册一个 Bot拿到应用 ID 和密码也叫 Client Secret。然后在 Bot 配置里设置 messaging endpoint这个地址必须是一个外网可访问的 HTTPS 地址指向你的 OpenClaw 消息接收接口通常是/api/messages。本地开发阶段最方便的方式是使用一个开发隧道工具把你的本地 8765 端口暴露成一个临时 HTTPS 域名。这里不展开具体的工具名你自己找一个稳定的就行。隧道工具启动后把生成的https://xxxx地址填到 Azure Bot 的 messaging endpoint 中。然后在 OpenClaw 的config.yaml里启用 Teamschannels: teams: enabled: true app_id: ${TEAMS_APP_ID} app_password: ${TEAMS_APP_PASSWORD} tenant_id: ${TEAMS_TENANT_ID}在.env里补充TEAMS_APP_ID00000000-0000-0000-0000-000000000000 TEAMS_APP_PASSWORDyour_bot_password TEAMS_TENANT_IDxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxtenant_id不是必填项但如果你用企业账号建议填上避免登录冲突。这个通道配置完必须先启动 OpenClaw再启动隧道工具然后才能在 Teams 里发消息测试。顺序反了Azure 验证回调地址时会失败。有一个很实用的验证技巧隧道工具会打印所有 HTTP 请求日志。你在 Teams 里给机器人发一条消息如果隧道日志出现来自微软服务器的 POST 请求说明回调地址通了如果没有问题出在 Azure 配置或消息端点而不是 OpenClaw 本身。3.4 接入 Obsidian 笔记工具如果你和我一样用 Obsidian 管理笔记那 OpenClaw 与 Obsidian 的联动会非常爽。配置成功后你可以让 AI 直接读取指定 vault 里的笔记或者按你的要求整理、归档、新建笔记。在config.yaml里添加tools: obsidian: enabled: true vault_path: D:\Obsidian\MyVault allow_read: true allow_write: true allow_delete: falseallow_delete强烈建议保持false除非你真的想体会“一句话让 AI 删掉整个笔记库”的刺激。AI 虽然有意图识别但误触的概率远比你想象的要高。如果你希望 Obsidian 能主动把笔记内容作为上下文发送给 OpenClaw而不是等着 AI 去读取通常还需要在 Obsidian 里安装对应的社区插件并启用本地 WebSocket。插件会在本地开一个端口OpenClaw 监听这个端口上的事件。这个扩展不是必要的最基础的基于路径读取可以先跑通。3.5 启用本地命令行测试通道在配置所有外部通道之前先确保本地 CLI 通道是可用的。OpenClaw 通常自带一个交互式终端运行openclaw chat这个命令会进入一个类似聊天界面的交互模式。你输入ping如果返回pong说明核心服务正常。再输入一句 “你好”如果模型配置正确你应该能看到回复。这一步非常关键它能把“模块安装问题”和“外部通道问题”彻底隔离开。CLI 能通再去折腾 Teams、Obsidian 才有意义。4. 启动服务与网关连通测试4.1 启动前的自检在正式启动前强烈建议先跑一下自检命令openclaw doctor这个命令会检查 Python 版本、依赖完整性、端口占用、配置合法性。如果某项失败按提示修正。常见的失败项Python 版本过高或过低.env里缺少关键 Key端口被其他程序占用config.yaml里某个字段拼写错误如果你的版本没有doctor命令也可以手动检查配置python -c from openclaw.config import load_config; load_config(config.yaml); print(config ok)配置加载成功后再启动。4.2 前台启动与后台运行最直接的方式是前台启动所有日志直接打印在终端里openclaw start启动成功后你会看到类似这样的日志[gateway] listening on http://127.0.0.1:8765 [channel:cli] ready [channel:teams] connected [agent] default agent loaded看到listening字样说明网关已经跑起来了。此时不要关闭这个终端可以另开一个终端做测试。如果你需要长期运行Windows 下不建议直接最小化终端因为容易被误关。我推荐用计划任务或者服务工具把 OpenClaw 注册成 Windows 服务。更简单的方案是写一个start_openclaw.bat开机启动时自动运行echo off chcp 65001 nul cd /d D:\dev\openclaw call .venv\Scripts\activate.bat set PYTHONUTF81 set PYTHONIOENCODINGutf-8 openclaw start把快捷方式丢进启动文件夹即可。注意.bat文件本身编码要存成 ANSI 或 UTF-8 with BOM不然中文注释会乱码。4.3 网关连通测试三连服务启动后按下面三步逐步验证第一步验证网关本身是否存活curl http://127.0.0.1:8765/v1/health在另一个终端执行如果返回{status:ok}说明网关进程正常。第二步验证 CLI 通道是否工作在启动终端里按交互模式输入ping或者用openclaw exec ping第三步验证模型链路是否通openclaw exec 用一句话回答11等于几如果模型返回正常说明 LLM Provider 配置正确。如果这里报超时或认证失败问题一定在模型配置或网络访问不要在通道配置上浪费时间。4.4 打通 Teams 回调和消息响应前面说过用隧道工具把本地端口暴露到公网。假设隧道工具给你分配了https://abc123.ngrok.io你需要把这个完整地址加上/api/messages填到 Azure Bot 的 messaging endpoint 中https://abc123.ngrok.io/api/messages然后在 OpenClaw 配置里确认端口确实是 8765隧道工具的本地转发目标也是http://127.0.0.1:8765。重启 OpenClaw让配置生效openclaw restart到 Teams 里给机器人发一条 “hello”。正常情况下几秒内你会收到回复。如果没收到回复按这个顺序排查隧道工具日志有没有来自微软的 POST 请求。没有说明 Azure 回调地址无效或未保存。隧道工具日志有请求但 OpenClaw 没有响应。说明 OpenClaw 处理异常查看 OpenClaw 终端日志是否有报错。OpenClaw 有报错但不确定原因。先禁用 Teams 通道用 CLI 再测一次模型链路确认模型没问题后再单独排查 Teams 配置字段。4.5 session file locked 错误的深度排查这条错误在热词里很常见症状是agent failed before reply: session file locked (timeout 60000ms)出现原因很直接一个会话文件被某个进程锁住了OpenClaw 尝试等待最长 60 秒超时后直接失败。最常见触发场景你之前启动过 OpenClaw但没正常退出进程变成了僵尸进程。你同时开了两个窗口分别执行openclaw start两个进程争抢同一个会话文件。OpenClaw 异常崩溃.lock文件没来得及清理。解决办法第一步结束所有 OpenClaw 进程taskkill /IM openclaw.exe /F如果进程名不是这个先查tasklist | findstr openclaw拿到 PID 后强制结束taskkill /PID PID /F第二步删除锁文件。锁文件通常在OPENCLAW_HOME下的sessions目录里扩展名为.lock。直接进入目录删除所有.lock文件cd D:\dev\openclaw\data\sessions del /Q *.lock第三步重新启动 OpenClaw。这次只开一个窗口不要重复启动。如果你需要后台运行用服务方式不要手动挂多个终端。还有一个隐藏问题Windows Defender 实时保护可能会在 OpenClaw 读写会话文件时临时占用文件句柄导致类似锁异常。如果你反复删除锁文件后仍然报锁可以把D:\dev\openclaw\data目录加入 Defender 排除项Add-MpPreference -ExclusionPath D:\dev\openclaw\data这条命令需要管理员权限的 PowerShell 执行。排除目录比关闭整个防护要安全得多。5. Windows 特有的坑与常用排查5.1 端口被占用一条命令找到凶手启动 OpenClaw 时如果看到ERROR: Address already in use说明默认端口已经被占用。先查谁占用了端口netstat -ano | findstr :8765输出结果的最后一列是 PID例如TCP 127.0.0.1:8765 0.0.0.0:0 LISTENING 12345继续查看这个 PID 是什么程序tasklist /FI PID eq 12345如果确认是无用进程直接结束taskkill /PID 12345 /F如果你并不想结束别的程序也可以让 OpenClaw 换一个端口。在config.yaml里找到网关监听端口配置改成比如8866然后重新启动即可。换端口后隧道工具的本地转发目标也要同步修改否则公网回调会失败。5.2 终端闪退、中文乱码和编码问题Windows 的老毛病就是默认代码页和 UTF-8 不匹配。OpenClaw 的日志大量使用 UTF-8 中文在默认 CMD 窗口里经常显示成乱码或者直接让脚本闪退。我个人最推荐的方式是使用 Windows Terminal 而不是旧版 CMD 或 PowerShell ISE。Windows Terminal 对 UTF-8 的支持好得多。然后把系统默认编码切到 UTF-8设置 → 时间和语言 → 语言和区域 → 管理语言设置 → 更改系统区域设置 → 勾选“Beta: 使用 Unicode UTF-8 提供全球语言支持”。重启系统后很多乱码问题会直接消失。如果你不想改系统区域可以每次手动执行chcp 65001或者在启动 bat 里加上chcp 65001 nul。另外设置两个环境变量让 Python 强制使用 UTF-8setx PYTHONUTF8 1 setx PYTHONIOENCODING utf-8设置完记得重开终端。这两个变量能解决绝大多数 Python 脚本在 Windows 下输出中文报错的问题。至于“闪退”最常见的场景是双击.py文件或者直接在文件管理器里点击某个脚本。Python 执行完或出错后窗口会瞬间关闭什么都看不到。以后所有 OpenClaw 相关命令都在终端里手动执行不要双击脚本。必须双击的场景用cmd /k保持窗口cmd /k D:\dev\openclaw\.venv\Scripts\openclaw.exe start5.3 pip 安装失败、镜像源不生效怎么办依赖安装失败十次有七八次是网络问题还有两三次是缺少编译工具。网络问题的解法是配置国内镜像源前面已经提到。但有时候你明明配置了镜像源还是从默认源下载原因可能是你在项目里用了Pipfile或poetry.lock它们会覆盖全局 pip 配置。我的建议是统一用requirements.txt并且把镜像源写到requirements.txt注释里提醒自己。如果某个包从镜像源找不到再单独指定源安装pip install 包名 -i https://pypi.tuna.tsinghua.edu.cn/simple如果报错信息里出现error: Microsoft Visual C 14.0 is required说明某个依赖需要本地编译。去安装 Visual Studio Build Tools工作负载勾选“使用 C 的桌面开发”装完后不用重启 Visual Studio重新打开终端重试 pip。还有一种情况某些包只发布了特定 Python 版本的 wheel你用的是 Python 3.12找不到对应 wheel 就会尝试源码编译。如果编译又失败最快的办法是换 Python 3.11 重装环境。我在 3.12 上折腾了一个晚上换 3.11 后二十分钟搞定。有时候“降级”反而是最省事的方案。5.4 路径带空格、权限不足、Defender 误杀这三个问题可以放一起说因为都是 Windows 特有的低级坑。第一路径带空格。不仅是安装目录临时目录和用户账户名也可能带空格。如果你的 Windows 用户名是中文或带空格比如C:\Users\张三OpenClaw 的某些子进程会找不到正确路径。这个时候建议把OPENCLAW_HOME指向一个纯英文路径比如D:\dev\openclaw\data把临时文件也导向英文路径setx TMP D:\dev\openclaw\tmp setx TEMP D:\dev\openclaw\tmp第二权限不足。OpenClaw 首次启动要写配置、会话、日志如果安装在C:\Program Files下普通权限会有各种写入失败。解决办法不是“用管理员运行”而是把项目放在你完全控制的用户目录或 D 盘自有目录比如D:\dev\openclaw。之后的启动也不需要管理员权限。第三Defender 误杀。OpenClaw 能够执行本地命令、写文件、和外部平台通信这种行为的可执行文件很容易被安全软件判为可疑。如果你发现某个 .exe 或 .py 被隔离去 Windows 安全中心 → 保护历史记录里恢复然后把这个项目目录加入排除项Add-MpPreference -ExclusionPath D:\dev\openclaw不要直接关闭实时保护那样更危险。只排除这一个目录就够了。5.5 日志排查技巧看日志比瞎猜快十倍OpenClaw 运行时的日志集中在OPENCLAW_HOME下的logs目录。遇到问题不要瞎猜先看日志。Windows 下查看最新日志可以用openclaw logs -f或者手动打开日志文件notepad D:\dev\openclaw\data\logs\openclaw.log日志级别也可以调。在config.yaml里加logging: level: debug然后重启。debug 日志会输出最详细的链路信息包括收到的消息内容、调用模型时的请求参数、工具执行的返回值。官网文档里不会给你的排错经验基本都在 debug 日志里写着。排查问题有个固定套路先看网关日志确认请求是否进来再看 agent 日志确认模型是否返回最后看通道日志确认结果是否回发。哪一段断了就集中看哪一段。6. 实测体验与进阶玩法从零到完全跑通我这边大概花了半天。装环境和依赖大概 1 小时配置模型和本地通道 30 分钟Teams 回调调试反而花了最长时间原因是对 Azure 机器人配置不熟悉。跑起来之后OpenClaw 在 Windows 下的稳定度还算可以连续运行 48 小时没有出现内存持续上涨的情况占用内存大约五百多MB不含本地模型。会话锁问题通过规范单实例启动后根除了。如果你现在打算上手我给你的建议是第一次配置千万不要直接上 Teams。先本地 CLI 跑通再配置一个最简单的外部通道最后再碰 Teams。否则你将面对 Azure、端口转发、网关日志、模型超时四个问题叠加在一起根本不知道是哪里出了毛病。走出这一步之后后续玩法其实很丰富。比如说给你自己的 Obsidian 做一个“每日整理”的定时任务让 OpenClaw 每天自动把散乱的笔记归类也可以把 Teams 当远程入口在手机上让 AI 帮你查数据、生成日报还可以把本地命令工具暴露给模型实现“说一句话跑一个脚本”。我个人实际使用中最大的体会是Windows 原生部署没有想象的那么难但必须一条链路一条链路去验证别想着一步到位。把准备工作做足把日志当朋友大部分坑都是纸老虎。如果你也在 Windows 上折腾 OpenClaw遇到标题里提到的那些报错不妨按上面这些步骤逐项检查大概率十分钟内能解决。