Openclaw的安装设置说难不难说简单也真不简单。如果你只是翻一下它的README可能会觉得“不就拉个镜像跑一下吗”但真正自己上手装一遍才会发现坑全藏在细节里session文件锁死、飞书消息截断、channel选错导致消息收不到、模型API配了半天没反应。这篇文章不打算复述官方文档而是把我在服务器上从零部署Openclaw的真实过程、配置思路和排障记录拆开讲希望能让你少走点弯路。1. 安装前的准备与整体思路1.1 Openclaw到底是个什么项目简单说Openclaw是一个自托管的AI Agent运行框架。你可以把它理解成一个“中枢”它负责接住来自飞书、Teams、Telegram、Discord甚至本地终端里的消息然后把这些消息串成任务交给背后的大模型去处理再把结果发回原来的聊天窗口。它本身不生产智能而是帮你把“大脑”和“手脚”接起来。这个定位决定了它适合谁来用不想把自己团队聊天记录交出去的开发者、手里已经有模型API key想充分利用的人、以及想在公司内部搞一个统一AI助理但不想被某个SaaS平台锁定的团队。它和WorkBuddy这类托管产品相比最大的优势是代码在自己手里模型可以自由选数据链路自己可控。代价就是你得自己完成安装、配置、维护和排障出了问题没有官方客服多数时候得靠自己查日志。所以这不是一个开箱即用的软件但也不是那种需要从零写代码的项目。只要理解了它的结构安装设置就是一个“按步骤配置”的活。1.2 环境要求与服务器选型我建议优先用Linux服务器来跑Openclaw。Ubuntu 20.04、22.04、24.04我都试过Debian系也基本没问题。Windows和macOS也能跑但如果你要在生产环境长期挂着还是Linux最省心不是说Windows跑不了而是排障时很多日志路径、进程管理、权限处理在Linux下都要直观得多。硬件上最低2核4G内存能跑但只能勉强应付一两个并发会话模型响应稍慢一点就会出现各种超时错觉。我自己实际跑到4核8G之后才觉得“舒服”因为框架本身、模型API调用、日志写入这些都要占资源。如果你还想接本地模型比如Ollama内存建议直接上16G不然模型加载完机器就快卡死了。网络这块要重点说。服务器必须要能正常访问你所选的模型API和办公软件的开放平台。比如你用国内模型服务就选国内服务器延迟低还稳定如果你要接入Teams就得确保服务器能稳定连接微软的服务端点。我见过有人贪便宜买了国际线路的低价服务器结果连国内模型API超时严重最后只能换机器重新折腾。1.3 整体安装流程梳理把安装流程拆成三步看思路就清晰了先把运行环境准备好然后把项目或镜像拉下来跑通最后改配置。配置这块又可以拆成三个方向模型配置用哪家模型、什么Key、渠道配置接飞书还是Teams、默认走哪个Channel、运行参数端口、Session目录、日志级别。只要把这三个方向理清楚Openclaw的安装设置就算完成了一大半。2. 核心安装步骤与配置要点2.1 先搞定Docker与基础环境Docker是目前部署Openclaw最舒服的方式。它把运行时依赖全部打包好了省去你在机器上配Node、Python、各种库的麻烦还方便回滚版本。我在Ubuntu上的安装步骤大概是这样的sudo apt update sudo apt install -y ca-certificates curl curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg echo deb [arch$(dpkg --print-architecture) signed-by/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo systemctl enable --now docker装完记得验证一下docker version docker compose version这里有个容易踩的坑很多教程默认你装了docker-compose但实际服务器上可能只装了docker命令没有compose插件。我建议直接用docker-compose-plugin也就是上面的安装命令里带的那部分比单独装一套Python版的docker-compose要省事也不会出现版本兼容问题。还有一个建议不要把生产环境的Openclaw装在桌面Linux上也不要手动启动容器之后不管了。用Docker的restart策略或者systemd来管理它服务器重启之后容器能自动拉起来这才是长期跑服务该有的样子。2.2 拉取Openclaw项目与镜像安装方式主要有两种一种是直接clone源码仓库看它自带的一键安装脚本另一种是直接拉取官方构建好的Docker镜像用docker compose来编排。我个人推荐先clone仓库再看配置文件不要上来就docker compose up。原因很简单Openclaw的具体启动参数、环境变量名称、默认端口在不同版本里可能有变化如果你不了解当前版本长什么样就贸然启动后面配置模型和渠道时会非常被动。先clone下来把配置结构看明白再启动这个时间花得值。参考流程是这样的git clone https://github.com/你的目标仓库.git openclaw cd openclaw cp .env.example .env # 编辑 .env 或配置文件填入你的模型API Key等 docker compose up -d注意仓库地址和具体配置项以你实际拿到的版本为准。我在这里想强调的是启动前一定要先把配置项摸清楚。Openclaw这类框架的配置并不复杂但每个版本可能有一点点差异直接依赖记忆里的命令很容易翻车。2.3 关键目录与基础配置项安装完成后你至少需要关心三个东西配置文件、Session目录和日志输出。配置文件一般是以.env或config.yaml形式存在里面记录了模型Provider、渠道接入参数、监听端口等。Session目录是Openclaw存放会话状态的地方这个目录极其重要后面聊session file locked报错时还会提到它。基础配置项我建议按下面的思路来设置配置项作用建议值监听端口Openclaw对外服务的HTTP端口默认值即可除非被占用数据/Session目录会话持久化位置建议放到Docker volume中日志级别控制日志输出详细程度调试用info稳定后改warn模型Provider指定大模型服务商根据Key来源填写默认Channel指定消息从哪个渠道进入先填cli跑通后再加IM我把日志级别单独拎出来说。很多人第一次启动就遇到“没反应”的问题这时候日志就是唯一的线索。先用info级别跑起来确认一切正常后再改成warn减少日志量这个习惯能省下大量排查时间。3. 模型与渠道配置3.1 大模型接入以配置千问为例Openclaw本身不绑定某个固定模型它通常通过兼容OpenAI接口的方式对接各家模型服务。这就是为什么你可以灵活地使用千问、DeepSeek、智谱、OpenAI以及本地Ollama模型。国内环境优先推荐千问或DeepSeek申请方便、价格相对可控、网络延迟也低。以阿里云百炼上的千问为例配置思路是这样的因为它提供OpenAI兼容模式所以只需要把Base URL指向百炼的兼容端点然后填上API Key和模型名。OPENCLAW_MODEL_PROVIDERopenai OPENCLAW_MODEL_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 OPENCLAW_MODEL_API_KEYsk-你自己的密钥 OPENCLAW_MODEL_NAMEqwen-plus这里有个核心点要搞清楚为什么用OpenAI兼容协议因为绝大多数开源框架的模型调用层都是优先适配OpenAI接口的厂商做一个兼容端点就能直接接入一堆开源项目。你不需要关心它底层是不是OpenAI只要Base URL和Key对得上参数格式是标准的chat/completions就行。如果你用DeepSeek思路完全一样把Base URL换成DeepSeek开放平台对应的地址模型名改成deepseek-chat之类。如果接本地Ollama则不需要外部API KeyBase URL指向你跑Ollama的地址模型名填你下载的本地模型名称。一个最实用的建议不要把API Key直接写死在代码仓库里。用.env文件或者用系统环境变量注入这样既方便不同环境切换也避免不小心把密钥提交到Git仓库里。我见过不少人把自己的Key推到公开仓库过几个小时就被别人盗刷这个代价太大了。3.2 Channel的选择逻辑与切换方法Channel这个词在Openclaw里就是指“消息从哪个聊天工具进来”。一个Openclaw实例可以同时接多个Channel比如同时接飞书和Teams也可以只接一个。选Channel的基本原则其实很简单公司同事用什么你就接什么。不要指望大家为了一个机器人换聊天工具。这跟技术无关纯粹是习惯问题。常见Channel我整理了一个对比Channel适用场景接入难度消息形态终端CLI本地调试、最快验证配置极低纯文本飞书中文团队内部使用中等文本/富文本/卡片Teams国外团队、M365生态较高自适应卡片Telegram个人自动化、海外场景低文本/支持MarkdownDiscord社区机器人、游戏社群低富消息/嵌入关于“怎么选择Channel”这个问题实际操作中会涉及到两个层面一个是全局配置里设置默认Channel另一个是在运行中切换当前会话使用的Channel。如果你刚装好我强烈建议先用终端CLI渠道把整套链路验证通了再接入飞书或Teams。很多人一上来就直奔飞书配置结果模型Key没填对、回调地址没配上消息发不出去一下子面对好几个变量根本不知道哪里出了问题。先用CLI把所有变量都排除一遍再去碰渠道配置会轻松非常多。3.3 接入飞书与Teams的实操细节飞书是中文团队里最常见的接入目标。流程大概是在飞书开放平台创建一个企业自建应用拿到App ID和App Secret然后在应用能力里开启机器人配置事件订阅。Openclaw侧填上这些凭证选择长连接或者回调模式启动后就能收到消息。这里重点说一下模式选择。飞书开放平台支持两种消息接收方式一种是长连接WebSocket一种是回调Webhook。长连接模式对没有公网IP的服务器非常友好因为不需要飞书主动来访问你你主动连上去就行。如果你的机器本来就在内网或者不方便暴露公网端口优先用长连接。回调模式则要求你有一个飞书能访问到的公网地址并且配置好URL验证逻辑。配置Teams会重一些。Teams背后是微软的Bot Framework你需要在Azure门户里注册一个应用给它添加“机器人”能力生成客户端密码然后把Bot的应用ID、密码、租户信息填到Openclaw配置里。整个过程比飞书要繁琐但一旦配好和M365生态结合得很好日历、邮件、Teams消息都能串起来。我个人体验下来飞书在中文团队里的体验是最好的无论是消息延迟还是富文本展示都很顺手。Teams适合已经在重度使用Microsoft 365的组织。Telegram则是玩自动化的首选配置最简单消息格式支持也最灵活。4. 常见问题与排查技巧实录4.1 session file lockedtimeout 60000ms完整排障这个报错是热词里出现频率最高的agent failed before reply: session file locked (timeout 60000ms)。我第一次看到这串日志的时候第一反应是“模型没响应”因为报错出现的位置恰恰是agent回复之前。但实际上这个报错跟模型一点关系都没有问题出在会话锁上。Openclaw在管理会话时会用文件锁来确保同一个会话文件在同一时刻只被一个进程写。如果你启动了多个实例比如开多个容器、多个进程它们抢着写同一个session文件后到的那个就会一直拿不到锁等够60秒就直接报错超时。另一种常见情况是进程异常退出锁文件残留导致后续启动的进程误以为锁还被占着。排查步骤我整理成了标准流程# 1. 看看当前到底起了几个Openclaw进程/容器 ps aux | grep -i openclaw docker ps | grep -i openclaw # 2. 找到Session目录查看是否有残留的锁文件 ls -la /var/lib/openclaw/sessions/ ls -la /root/.openclaw/sessions/ # 具体路径按你的配置 # 3. 确认只有单实例运行若有重复实例先停掉 docker stop 重复的容器ID # 或 kill 掉多余的 openclaw 进程 # 4. 清理残留锁文件 rm -f /var/lib/openclaw/sessions/*.lock这个报错最有迷惑性的地方在于它发生在“发给模型之前”所以查日志很容易被带偏到模型配置方向。实际上你只要抓住“session file locked”这几个字把方向切到多实例问题排查速度会快很多。我后来为了避免再踩这个坑直接在Docker编排里把容器数量限制为1并且用固定的volume挂在同一个session目录再用restart策略保证服务异常退出后能自动拉起但不会拉起第二个实例。4.2 飞书输出容易被截断的解法热词里有“openclaw在飞书输出容易被截断”这个我也遇到过。本来agent在CLI里能输出一大段完整内容但通过飞书发出去就断在中间或者只显示了开头一小段。飞书对普通文本消息有长度限制大约在一万五千字节左右如果模型生成的内容太长或者Openclaw按块发送时某一块超了长度就会出现截断。这和你模型能力没关系是渠道消息格式的限制。我实测下来比较有效的做法有三个在系统提示词里明确输出要求比如“回答尽量精简用列表和短段落组织内容不要在单条消息里输出超长报告”。这能从源头上减少生成长度。调整max_tokens参数限制单次生成的最大长度。这样即使模型想多说也不会生成出超长文本。如果需要发长内容改用飞书富文本或卡片消息类型卡片消息对长度的容忍度更高而且展示上更美观。另外一个偏经验的做法让agent先输出一个摘要然后提供“完整报告另说”的交互方式。比如让它默认回复核心结论用户需要时再说“展开看看”这样既能避开截断问题使用体验也更自然。4.3 其他高频问题速查除了上面两个大坑还有一些零散问题也经常被问到我整理成了一张速查表问题现象可能原因处理办法日志大量报ERROR但agent不回复模型API Key失效或配额不足检查Key、检查账户余额、更换模型名启动时提示端口被占用端口冲突改端口或杀掉占用进程Docker重启后会话全丢Session目录没有挂载volume在compose里把session目录映射为volumeTeams无法连接Bot密码过期或租户信息错误去Azure门户重新生成密码核对租户ID接入本地Ollama响应很慢模型量化/并发参数不合适升级内存或减小并发数飞书收不到消息事件订阅模式配置错检查长连接/回调模式确认应用发布状态同一份消息agent重复回复多个Channel都在监听检查Channel配置关闭无关渠道这里面我想特别强调一下“Docker重启后会话全丢”的问题。很多人以为只要容器重启了数据就在但实际上如果你没有把session目录映射到宿主机或者Docker卷里容器重建后所有会话数据就没了。这就好比你开了很多聊天窗口但换个手机登录之后历史记录全不见了非常难受。正确做法是在compose文件里显式声明volume把你指定过的session目录持久化出来这样无论容器怎么升级重建历史会话都还在。收尾一点个人体会装Openclaw这件事核心不是“跑起来”而是“跑明白了”。Session锁、飞书截断、模型Key失效这些问题单看任何一个都不难但它们往往同时出现最容易让人烦躁。我自己经历过一次三个问题叠加的排查最后发现是一开始没规划好目录和容器数量给自己埋了一堆雷。如果你正准备上手我建议你花点时间把配置文件和目录结构看一遍再启动服务。这样后面无论遇到什么报错你至少知道去哪个文件看、往哪个目录查排查起来的效率会完全不一样。