1. 为什么值得装一个OpenClaw坦白说我自己把OpenClaw装了一遍又一遍从Windows到Linux到Docker前前后后折腾了不下十次。每次重装并不是因为它难装而是因为它值得装。这个项目解决的是一个非常真实的问题你手里明明有飞书、Teams、Telegram好几个渠道又有一堆不同模型千问、DeepSeek、本地Ollama结果每个渠道配一个聊天机器人每套配置互相独立上下文还得靠人工同步整个状态就是“混乱”。OpenClaw本质上是把多个IM渠道和多个模型后端统一管理起来的Agent运行容器。你在一处配置好渠道和模型就能把同一个Agent暴露给不同入口所有会话上下文统一处理不会因为换了一个聊天窗口就“失忆”。它对个人开发者和中小团队特别友好不需要像大厂那套Agent平台一样搞复杂的微服务编排装好、配好、跑起来立刻能用。这篇教程的内容全部来自我自己实操过程中的记录包括Windows下怎么装、Linux下怎么处理Python版本问题、飞书和Teams怎么接、千问怎么设置成默认模型以及那些一搜一大片但没人讲清楚的报错比如agent failed before reply: session file locked这个坑我自己被它卡了两个小时。我会尽量把每一步为什么这么做也写清楚不光是“照着敲命令”而是让你知道这条命令到底在干嘛改这个配置影响的是什么。适合谁来参考想在本地快速跑起一个多渠道Agent的人、想让飞书或Teams里有个能连续对话的智能助手的人、以及用Docker搞部署但被网络和目录挂载折腾到头疼的人。不管你之前有没有玩过Agent只要会打开终端、能照着粘贴命令这篇教程就能帮你走完全程。2. 动手安装前的准备工作2.1 系统与基础环境要求先确认自己的环境省得到后面装到一半才发现基础条件不对。OpenClaw对操作系统本身不挑Windows 10/11、Ubuntu 20.04以上、macOS都能跑但有几个硬性依赖绕不开Python 3.10到3.12、Git、以及能正常联网的终端环境。我自己的实测经验Python版本这东西相当重要3.9以下装依赖会直接报语法错误3.13以上又会碰到部分依赖包没适配的情况。3.11最稳后面所有命令我都默认你用的是3.11。如果你机器上已经有Anaconda或者Miniconda用conda建一个干净的环境最靠谱能把各种依赖冲突直接挡在外面如果你不熟conda直接装官方Python也行但尽量别用系统自带的旧版本。项目最低要求推荐配置说明操作系统Windows 10 / Ubuntu 20.04Windows 11 / Ubuntu 22.04影响不大新版更省心Python3.103.113.13以下版本都要注意兼容性Git任意较新版本Git for Windows 2.40Windows下记得装Git Bash内存4GB8GB以上同时跑模型推理时内存越宽裕越好网络能访问GitHub和模型API国内建议配镜像加速后面细说2.2 先把Python和Git这件小事打牢很多人栽在奇怪的问题上根源其实是Git没装好。我说几个安装时的关键点你照着选就行。Windows下装Git全程下一步也可以但有两个地方要手动确认第一个是“Adjusting your PATH environment”这一步一定要选“Git from the command line and also from 3rd-party software”不然终端里敲git会提示找不到命令第二个是行尾转换那里建议选“Checkout as-is, commit as-is”避免后面对OpenClaw拉取的代码做无意义的换行符变动。Python这边如果你是Windows去官网下载安装包后记得在第一个界面的最下面勾上“Add Python to PATH”这一步不勾后面终端里输入python就是一堆报错。安装完验证一下python --version pip --version git --version这三个都能输出版本号基础环境就算过关了。我自己见过太多人卡在“为什么装好了却不能用”九成情况就是PATH没配对。2.3 网络与镜像国内机器的重要一步环境满足之后还有个隐性的坎就是网络。OpenClaw的代码仓库、依赖包列表、以及模型API调用全都要访问外网如果你的网络环境不稳定pip安装时就会反复超时。我这边实测下来最稳妥的做法是给包管理器配国内镜像源两个关键位置一是pip源可以用清华或阿里的镜像速度提升非常明显。我习惯在用户目录下放一个pip.iniWindows或者~/.pip/pip.confLinux内容是[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn二是如果走conda环境把conda的channel也换成国内镜像具体就是在.condarc里指向清华的conda源。这一步不解决后面pip install一个依赖等上十分钟然后报一个网络错误心态很容易崩。至于GitHub仓库的拉取操作如果经常连不上或者速度慢可以考虑把官方仓库的地址转成第三方加速镜像但这里的底层逻辑都一样——确保你执行git clone时能够顺利拿到全部代码。具体用什么地址按你实际网络情况来挑就行原则就是“快并且完整”。3. Windows环境下的完整安装流程3.1 拉取源码与创建虚拟环境环境准备好之后第一步是把OpenClaw的源码拉到本地。找一个你觉得合适的目录然后执行git clone https://github.com/xxxx/openclaw.git cd openclaw如果仓库地址已经变动以官方文档为准这个不重要重要的是你进入了源码目录后续所有命令都在这个目录下执行。接下来创建虚拟环境。我之前图省事直接往全局环境里装结果跟其他项目的依赖打架后来再也不敢这么干了。强烈建议用condaconda create -n openclaw python3.11 -y conda activate openclaw如果你没装conda用Python自带的venv也行python -m venv .venv .venv\Scripts\activate虚拟环境的意义就相当于给每个项目圈一块独立地盘OpenClaw需要的依赖不会污染你其他的工作环境其他项目的包也不会反过来干扰它。这一点在Windows上格外重要因为系统自带的Python环境和乱七八糟的全局包很容易出问题。3.2 安装依赖这一步的完整命令进入虚拟环境后开始装依赖。OpenClaw的依赖项不算少包括Agent框架自身、各种channel的SDK飞书SDK、Teams SDK等、模型接入的客户端库一次性装全比较省事pip install -r requirements.txt如果你想用可编辑模式安装方便后期改源码调试可以执行pip install -e .这两个命令本质上都会把依赖装齐区别在于-e模式会让项目以“开发模式”运行你改代码后不用重新安装。普通使用的话pip install -e .是我个人更推荐的方式因为以后升级或者改配置更灵活。装的过程中如果看到某个包在编译时报错比如visual studio C build tools required别慌先确认两件事一是Python版本是不是3.11二是pip是不是最新版。Windows上编译一些扩展包需要C构建工具通常执行下面的命令就能补上python -m pip install --upgrade pip pip install --upgrade setuptools wheel我遇到过最典型的场景是装pydantic-core这种带Rust扩展的包没有构建工具时直接报错。你可以不折腾本机编译直接去官网下对应版本的预编译wheel包然后指定本地路径安装。不过多数情况下把setuptools和wheel升到最新就能解决问题。3.3 初始化、配置模型与启动依赖装完以后执行初始化命令来生成配置目录和默认配置openclaw init这一步会创建类似~/.openclaw/的目录里面放着主配置文件、会话文件、日志等。第一次运行可能还会让你选择默认模型服务商你可以先跳过等后面配好千问再回来填。然后编辑配置文件重点看几个位置model.provider和model.api_key。如果你要用千问作为默认模型就把provider填成dashscopeapi_key填你自己的千问API Key。这里我多说一句国内网络环境下千问的接口延迟低、稳定而且key便宜作为OpenClaw的默认模型相当合适这也是我在实际项目里选择它的原因。配置完成后启动openclaw start正常启动后终端会打印出Agent已接管的渠道列表同时给出一个本地控制台地址。浏览器打开那个地址能看到所有接入渠道的状态、模型调用记录以及之前提到的channel切换操作面板。我第一次启动时就看到它已经自动把飞书Bot连接起来了那种“什么都没干就成了”的感觉确实很舒服。如果你想测试模型回话是否正常在启动状态下直接在任意已接入的渠道里发一条消息如果回复正常说明整条链路已经通了。当前面的anyway都检查无误整个Windows环境下的安装就算完成了剩下的就是接入具体渠道和调优。4. Linux与Docker部署方案4.1 Linux下最稳妥的装法Linux装OpenClaw的步骤整体跟Windows一样但有几个细节不一样主要卡在Python版本上。很多Linux发行版默认的Python不是3.11。Ubuntu 20.04默认是3.8直接跑pip install -r requirements.txt大概率会因为版本过老而失败。所以第一步是装Python 3.11sudo apt update sudo apt install software-properties-common sudo add-apt-repository ppa:deadsnakes/ppa sudo apt install python3.11 python3.11-venv python3.11-dev装完后创建虚拟环境python3.11 -m venv .venv source .venv/bin/activate pip install -r requirements.txtLinux下还有一个优势是systemd如果你想让OpenClaw开机自启、后台常驻可以写一个service文件[Unit] DescriptionOpenClaw Agent Afternetwork.target [Service] User你的用户名 WorkingDirectory/path/to/openclaw ExecStart/path/to/openclaw/.venv/bin/openclaw start Restartalways [Install] WantedBymulti-user.target然后用systemctl enable openclaw.service开启自启。我自己的服务器就是这么跑的重启之后不需要手动登录Agent会自动上线。如果你是放在家里的NAS或者云服务器上长期跑这个配置能省掉你非常多的维护精力。4.2 用Docker装省心但要留意网络与目录Docker Desktop是Windows和macOS用户比较喜欢的方式Linux上直接装Docker引擎也一样。Docker方案最明显的优势是环境隔离不依赖本机Python版本、不污染系统环境尤其是你机器上还有别的项目在跑的时候互不干扰是硬需求。OpenClaw官方提供了一个镜像在源码仓库的docker/目录下有Dockerfile和compose示例。自己构建的话进入项目目录执行docker build -t openclaw .然后用docker run起容器主要注意两个参数一是把配置目录挂载出来避免容器重建后配置丢失二是把控制台端口映射出来docker run -d \ --name openclaw \ -v ~/.openclaw:/root/.openclaw \ -p 8080:8080 \ openclaw端口号以你配置文件里的实际设置为准不一定是8080。用docker-compose up -d的话写法也差不多把volumes和ports配置好即可。Docker方案的坑我也替你们踩过。第一个是宿主机和容器之间的网络模式问题如果你的Agent需要主动访问宿主机的某个服务比如本地的Ollama或其他模型API容器内访问localhost是访问不到宿主机的需要加上--networkhost或者把API地址改成宿主机局域网IP。第二个是卷挂载权限Linux下把~/.openclaw挂进去后容器内没有写权限可能需要--user指定容器用户或者把宿主机目录的owner调整一下。不过整体来说Docker方式一旦跑通后续升级、迁移、换机器都非常省事其他环境配置都固化了只要把镜像拉下来就能用。4.3 一键部署脚本的实际定位热词里提到了“本地一键部署”。所谓一键部署其实就是官方或社区把前面所有步骤封装成一个shell脚本或bat文件自动完成克隆、建环境、装依赖、初始化、启动这些动作。我自己也写过类似的东西本质上是git clone 仓库地址 cd openclaw python -m venv .venv source .venv/bin/activate pip install -r requirements.txt openclaw init openclaw start脚本能帮你节省大量输入命令的时间但有一个前提你得心里有数脚本没法帮你解决所有环境差异。比如Python版本不对、Git未安装、网络连不上这些它都只能报错。所以我的建议是你可以用一键脚本作为起步手段但前面那些基础环境该装的还是得装不然脚本报错了你反而不知道怎么排查。5. 接入飞书、Teams和千问的真实操作5.1 让飞书变成Agent的对话窗口把OpenClaw接到飞书是我个人觉得投入产出比最高的一个操作。飞书在团队协作场景里普及率很高让Agent直接在飞书群里回答问题整个团队都能用不用专门教大家用什么新工具。需要做的准备在飞书开放平台创建一个企业自建应用开启机器人能力拿到App ID和App Secret然后在事件订阅里配置请求地址也就是OpenClaw暴露出来的回调地址。这几个参数拿到后填进OpenClaw的配置文件里channels: feishu: app_id: cli_xxxxxxxx app_secret: xxxxxxxx encrypt_key: verification_token: 填完重启openclaw start让它重新读取渠道配置。然后在飞书里找到这个机器人直接发消息能回就说明通了。实操中有个麻烦点飞书的事件订阅回调地址必须是公网可访问的HTTPS地址如果你是在本地跑OpenClaw飞书服务器是访问不到你本机的。这种情况有两个解法一是把OpenClaw部署到有公网IP的服务器上然后配置HTTPS二是用内网穿透工具把本地地址暴露出去再把那个公网地址填到飞书后台。我个人更推荐前者稳定天然后者只适合临时测试。5.2 接入Microsoft Teams需要哪些参数Teams的接入方式跟飞书有些相似也需要你在微软Azure门户里注册一个应用App registration然后配置机器人能力。需要准备四个关键参数Tenant ID、Client ID、Client Secret和Bot的Bot ID。拿到后填进配置channels: teams: tenant_id: xxxxxxxx-xxxx-xxxx client_id: xxxxxxxx-xxxx-xxxx client_secret: xxxxxxxx bot_id: xxxxxxxx-xxxx-xxxxTeams这里最容易出问题的地方是Client Secret和Bot ID混用。很多人填配置时把两个ID搞反了结果一直报认证失败。记住一个简单的区分方法Bot ID是你在Teams Bot注册页面看到的那个GUIDClient ID是Azure应用注册页面生成的另一个GUID两者不是同一个东西。另外Teams对消息卡片的支持跟飞书不太一样有时候Agent发过来的长内容会在Teams里被折叠或者格式错乱。这是我后面要说的飞书输出截断问题的同类场景基本上都是通过调整Agent的回复长度和截断逻辑来解决。5.3 把千问配成默认模型后端千问接入是几乎每个国内用户都会做的一步。原因很简单国内访问快价格便宜中文效果好。配置方法也直接打开主配置文件找到模型那一节model: provider: dashscope api_key: sk-xxxxxxxxxxxxxxxx model: qwen-max base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 temperature: 0.7 max_tokens: 2048这里有一个点要特别注意base_url不是必须的OpenClaw的dashscopeprovider默认会指向官方地址但如果你用的是兼容模式比如某些第三方中转就需要显式指定。qwen-max和qwen-plus是两种不同的档次max能力更强、价格更高plus性价比好适合日常问答。如果你只是自己用qwen-plus足够了如果是给团队做知识库问答建议直接用qwen-max准确率确实更好。配完跑一下openclaw start然后在飞书里随便发一句话看看是不是立即回复。关于temperature这个参数我习惯设0.7既能保证一定多样性又不会太放飞自我。6. 常见问题与避坑实录6.1 session file locked这个报错怎么解“agent failed before reply: session file locked (timeout 60000ms)”这个报错搜索热度非常高说明遇到的人不少。这个报错的本质是OpenClaw为每个会话维护一个上下文文件当两个进程同时尝试写入同一个会话文件时就会触发文件锁等待60秒还没拿到锁就超时了。为什么会同时有两个进程访问同一个会话文件最常见的场景是上一次启动没有正常退出进程还占用着锁文件或者你开了多个终端重复执行了openclaw start又或者是Agent在回调过程中因为网络延迟导致重试请求打到了同一个会话上。解决办法分两步第一步杀掉残留进程。Windows下打开任务管理器找到所有python进程并结束掉注意别误杀自己其他项目Linux下用ps aux | grep openclaw找到进程然后kill掉。第二步删除锁文件路径一般在配置目录下的session.lock文件删掉后重新启动# Linux/macOS rm -f ~/.openclaw/session.lockWindows下则是删掉C:\Users\你的用户名\.openclaw\session.lock。这一步做完九成情况都恢复正常。如果反复出现同样的报错我建议你在配置里把锁等待时间调大或者检查是不是有脚本在周期性地调用Agent接口导致锁竞争长期存在。6.2 飞书输出被截断的解决办法飞书渠道的输出被截断是热搜词里另一个高频问题。通常在Agent生成很长回复时飞书的消息卡片有长度限制超出的内容会被静默切掉看起来就像“话只说了一半”。要解决这个先看是不是模型生成的文本确实太长。如果max_tokens设得比较大比如2048或更高一篇长文生成下来很可能超过飞书的限制。我自己的处理方式是把默认的max_tokens调到1000到1500之间同时让Agent的习惯设定里明确“回答尽量简洁分点输出”。如果调低max_tokens还不够更彻底的办法是让Agent学会分段输出或者自主判断内容过长时拆成多条消息发送。OpenClaw的消息处理机制本身支持分片发送关键是在配置里打开相应的长消息分段选项然后在prompt里提醒Agent注意输出长度。我亲测下来最简洁有效的方式就一句话“回答控制在200字以内必要时输出简短列表”比改一堆参数都管用。6.3 启动失败的几个高频原因启动失败的原因五花八门但见的最多的就几类。第一是端口被占用控制台端口或者Webhook回调端口被别的程序占了启动日志会直接报address already in use。这时改配置文件里的端口即可不需要反复重启试。第二是API Key无效或过期。如果启动时提示模型服务商连接失败或者启动成功但Agent一回复就报错优先检查API Key的状态、余额和权限。千问的key在平台控制台能查到期时间有些免费额度到期后key会失效这个很低级但很常见。第三是依赖不完整。症状是启动时某个module找不到或者某个类导入失败。解决办法是重新执行一遍pip install -r requirements.txt再看看是不是有版本冲突干脆重建一个全新的虚拟环境再装一次。第四是配置文件语法错误。YAML对缩进非常敏感差一个空格都可能导致配置解析失败。我自己就干过这种事复制粘贴示例配置时缩进乱了OpenClaw直接报yaml.parser.ParserError。这时候不要慌把配置文件里的缩进统一改成两空格重新运行openclaw start。问题现象常见原因排查步骤启动报端口被占其他程序占用端口netstat -ano查看端口对应PID结束进程或改配置Agent回一句就断API Key无效/余额不足到模型平台控制台核查key状态找不到某个模块依赖没装全重新执行pip install -r requirements.txt配置解析报错YAML缩进错误用IDE打开配置文件检查缩进统一为两空格7. 几句选型与扩展建议7.1 OpenClaw和WorkBuddy怎么选不少人在搜索里对比OpenClaw和WorkBuddy这两款工具确实定位相似但侧重点有明显区别。WorkBuddy更像一个“调度中枢”擅长把一个任务拆解成多个步骤分派给不同子Agent去执行适合流程编排比较重的场景。OpenClaw则更偏向“统一接入层”把不同聊天渠道像飞书、Teams全接进来统一管理模型上下文适合你对多入口、消息连续性要求比较高的场景。如果你只是想让一个会聊天的Agent出现在飞书和Teams里OpenClaw上手更快配置也更直观如果你要构建的是一个多Agent协作的工作流比如同时调聚合搜索、文档总结、报表生成多个专门AgentWorkBuddy的编排能力可能会让你更顺心。从我的个人经验来看两者并不是对立关系先跑通OpenClaw的渠道接入再在你的Agent内部逻辑里做一些任务拆解已经能覆盖绝大多数需求了。7.2 还能往什么方向玩装好OpenClaw、接上飞书和千问之后整个系统的基础能力已经立住了后续扩展的方向可以很多。我建议从这几个方向里挑一个最贴合实际场景的开始玩一是把Agent从“问答机器人”进化成“任务执行器”比如接入你的本地命令行工具让它能自动查日志、跑脚本、做定时巡检再通过飞书把结果推给你们团队。二是把多个模型并起来配置里加一个主模型和备用模型让主模型抽风时自动切换日常容错会明显提升。三是把会话数据导出来攒一批真实问答记录后用这部分数据去做效果评测或者微调。我给团队内部做过一个“销售数据日报”的场景就是用OpenClaw接上飞书群每天早上定时触发一个Agent任务让它读数据库的昨日销售数据、跟上周做对比、用千问生成一段简洁的分析然后自动发到群里。整个链路就是靠渠道接入、模型配置和定时任务三个能力组合出来的难度不大但实用价值很高。OpenClaw装好只是第一步真正让它发挥价值的还是你往里面填的Agent定义、业务逻辑和使用场景。装的过程里遇到奇奇怪怪的问题很正常冷静下来按“先看日志、再查配置、最后重建环境”这个顺序排查大多数坑都能在几分钟内解决。希望这份从实际安装中打磨出来的教程能帮你少走一些弯路。