OpenClaw 这个名字最近在折腾本地 AI Agent 的圈子里出现频率相当高。而我今天想聊的是它的底层仓库 pi-mono 里一个看起来不起眼、实际上几乎每天都要用的模块pi-web-ui。很多人部署完 OpenClaw 后第一件事就是打开浏览器访问那个聊天管理界面但很少有人说得清楚这个界面在整套架构里到底扮演什么角色它和 gateway、channel、session 这些概念之间是什么关系。这篇文章是“解密 pi-mono 架构”系列的第一篇我打算把 pi-web-ui 从功能定位、通信机制、部署方式到常见坑点完整拆一遍。如果你正准备在 Windows 或 Linux 上部署 OpenClaw或者已经在用但经常遇到 session 文件锁死、飞书输出被截断这类问题这篇应该能帮你省不少时间。1. 先把 OpenClaw 和 pi-mono 的底细摸清楚1.1 OpenClaw 到底是什么OpenClaw 是一个可本地部署的个人 AI Agent 框架。和那些只能在云端网页里聊天的产品不同它把 Agent 的“脑子”和“手脚”都放在你自己的机器上你可以给它配置各种大模型 API也可以让它通过工具和技能去操作文件、查日历、跑命令再把它接驳到 Telegram、Discord、飞书、Teams、Web 界面等多个入口。这里有个容易混淆的地方OpenClaw 不是一个单一程序而是一整套服务组合。你在官方文档里看到的各种安装命令本质上是在拉起一个包含多个进程/模块的系统。这也是为什么有人会问“openclaw 和某某产品哪个好”——因为 OpenClaw 更像一个可以自己组装的工作台而不是开箱即用的单一应用。1.2 pi-mono 仓库长什么样pi-mono 是 OpenClaw 的 monorepo单仓多包工程整个“pi 家族”的代码基本都收在这个仓库里。用 monorepo 而不是多个独立仓库好处很明显共享的协议定义、类型声明、工具库可以在所有模块之间直接复用不用发一堆私有 npm 包同时不同模块之间的接口变更可以同步进行避免版本不同步导致的“接口地狱”。从目录结构看pi-mono 大致分为三类libs系列是被复用的核心库比如 pi-core核心数据模型与协议、pi-gateway网关、pi-channel通道抽象、pi-memory记忆存储、pi-agentAgent 循环逻辑apps系列是可运行的应用比如 pi-web-ui网页界面、pi-cloud-ui云端界面、pi-cli命令行工具services系列是可选配套服务比如消息服务、媒体服务等。这种分层方式很像后端常见的“核心库 适配器 应用壳”结构。你平时操作的是 apps 层但真正决定行为逻辑的是 libs 层。1.3 pi-web-ui 在这个家族里的位置pi-web-ui 就是那个浏览器里打开的聊天界面。注意它不是一个独立的后台管理系统而是整套框架里的一种“通道”呈现形式。什么叫通道后面我会详细展开这里先给你一个直觉Web UI 和 Telegram bot、飞书 bot 在架构上的地位是平级的它们都负责把用户的消息送进 Agent再把 Agent 的回答送回用户面前。区别在于pi-web-ui 是官方默认提供、和你本机环境贴合最紧的那一个所以它常常被当作 OpenClaw 的“主界面”来用。搞清楚这一点很多困惑就迎刃而解了为什么改某个配置但是网页里没生效因为你改的可能是 gateway 的配置而 pi-web-ui 只是负责展示和转发它本身不产生业务决策。2. pi-web-ui 的设计思路与运行机制2.1 通道模型UI 只是通往 Agent 的众多入口之一要理解 pi-web-ui必须先理解 OpenClaw 的通道Channel模型。在 pi-mono 里Chanel 是一个核心抽象它定义了一组统一的接口接收消息、发送消息、处理会话事件。任何平台只要实现了这组接口就能成为 Agent 的一个入口。这意味着什么意味着你可以同时开着 Web 界面、给飞书机器人发消息、在 Telegram 里继续同一个对话。底层 Agent 逻辑完全共享只是消息的“进出口”不同。通道层做的事情本质上是协议转换把各个平台千奇百怪的消息格式统一转换成 pi-core 内部的消息协议再把 Agent 的回答转换成对应平台能渲染的格式。这个设计和微服务里的 BFFBackend for Frontend模式有点像你不想让核心业务关心飞书和 Discord 的消息格式差异那就抽一层适配层每个平台一个适配器各自负责各自平台的“方言”。pi-web-ui 本质上就是浏览器这个“平台”的适配器只不过因为它跑在本地、没有第三方平台限制所以能做得更丰富比如流式渲染、会话列表、配置面板。2.2 前后端通信为什么是 WebSocket 打主力你在 pi-web-ui 里敲一句话回答是一个字一个字蹦出来的。这种流式体验背后通信方式起决定性作用。pi-web-ui 和 gateway 之间的主力通信协议是 WebSocket而不是普通的 HTTP 请求。原因很直接大模型输出的 token 是流式生成的如果用 HTTP 轮询要么频繁请求造成浪费要么回答延迟高、体验差。WebSocket 是全双工长连接服务器可以随时把新生成的 token 推给浏览器零额外握手开销。尤其当你用 deepseek、千问这类模型输出可能持续几十秒长连接的优势就非常明显了。除了实时消息pi-web-ui 也会用少量 REST 接口做一些管理类操作比如拉取会话列表、读取配置、获取技能列表。这类操作对实时性要求不高用传统的请求-响应模型反而更简单、更易调试。所以你可以把 pi-web-ui 的通信策略记成一句话聊天走 WebSocket管理走 REST。2.3 会话与会话文件状态到底存在哪里每个对话背后都有一个会话Session。在 pi-mono 里会话是 Agent 记忆和组织消息的基本单位。默认情况下会话状态以文件形式存储。你在数据目录里能看到一堆后缀为.session的文件每个文件对应一个会话里面记录着该会话的上下文、消息历史、元数据。文件存储的好处是简单、零依赖适合个人单机部署。但代价就是并发控制变麻烦。多个进程比如你同时跑了 CLI 和 Web UI或者开了多个后台任务同时读写同一个会话文件时就可能出现冲突。为了规避冲突实现里通常会给会话文件加锁写入前先获取锁写完后释放。如果某个进程持有锁的时间过长或者因为异常退出没有释放锁其他等待的请求就会一直阻塞直到超时。这也直接引出了那个在社区里高频出现的问题agent failed before reply: session file locked (timeout 60000ms)。你看到 60000ms就是等待锁的超时阈值。后面第 5 部分我会专门讲这个问题的排查思路。2.4 Agent 调度与消息路由链路当你在 pi-web-ui 里发出一条消息完整链路大致是这样的浏览器把消息通过 WebSocket 发给 pi-web-ui 服务端pi-web-ui 服务端作为通道把消息标准化后交给 gatewaygateway 根据会话 ID 找到对应的会话状态决定由哪个 Agent 实例来处理Agent 调用大模型 API并在循环中调用工具/技能生成回答回答以流式事件的形式原路返回gateway → pi-web-ui → WebSocket → 浏览器渲染。这条链路里最容易被忽略的是第 3 步Agent 怎么选择。很多人以为“我装了 OpenClaw它就是一个 Agent”实际上一个 OpenClaw 进程里可以跑多个 Agent 实例每个实例可以绑定不同模型、不同技能、不同通道。gateway 根据消息来源的通道、会话的归属决定把消息路由给哪个 Agent。这也是“openclaw agent 怎么选择 channel”这个热搜词的来源——你需要在配置里明确指定某个 Agent 监听哪些通道否则消息可能不会按你预期的方式被处理。3. 部署与接入实操含配置要点3.1 在 Windows 与 Linux 上把 OpenClaw 跑起来先说明一点OpenClaw 的部署方式一直在快速迭代不同版本、不同安装途径的具体命令会有差异。我这里讲的是通用思路和我的实操经验。我见过最多的情况是从 Microsoft Store 或 Windows 的安装器装的就是热词里那个 “openclaw windowshub 安装” 对应的场景。这种方式的好处是环境依赖帮你处理好了装完基本就能跑。但问题也在于“黑盒”——你想自定义数据目录、改监听端口、配模型时得先找到它的实际安装位置和配置目录。Linux 上部署则更直接。如果你用 Docker一条docker compose up就能把核心服务拉起来如果你是手动部署需要确保 Node.js 版本满足要求项目对 Node 版本有要求太老或太新都可能出现依赖安装失败。我个人喜欢手动部署因为排查问题方便日志都在终端里不会被容器吞掉。装完之后第一次启动会在日志里打印访问地址和临时 Token。这个 Token 很重要等会儿说。3.2 启动 pi-web-ui端口、Token 与本地访问pi-web-ui 默认监听在3123端口。启动成功后浏览器打开http://localhost:3123就能看到界面。首次进入时界面会要求你输入一个连接 Token——这个 Token 要么在启动日志里要么在配置文件里。它的作用是防止你这个本地服务被同一网络里的其他人随意连上。这里有个实操要点如果你只是本机用保持默认配置就好但如果你想从局域网另一台电脑访问比如你在台式机上跑 OpenClaw想在笔记本上操作你需要把监听地址改成0.0.0.0而不是默认的127.0.0.1否则外部访问不了把防火墙放行3123端口保管好 Token不要随手贴到群里。我遇到过不少人卡在“局域网打不开”这个问题上九成都是监听地址没改。别问我是怎么知道的。3.3 配置千问等模型作为 Agent 后端OpenClaw 本身不内置模型它需要你配置大模型 API。国内用户常问的“openclaw 配置千问”其实就是给 Agent 指定一个千问的模型端点和密钥。以千问为例操作逻辑是这样的在模型的 provider 配置里选择 OpenAI 兼容模式因为 DashScope 提供了 OpenAI 兼容的 HTTP 接口。你需要填三个东西Base URL指向 DashScope 的兼容模式地址API Key在阿里云百炼控制台申请模型名称比如qwen-max、qwen-plus具体以你开通的模型为准。填完之后在 pi-web-ui 里新建会话Agent 的回复就会走千问。注意如果你配置了多个模型 provider要在 Agent 配置里指定默认用哪个否则 gateway 会按自己的优先级去选结果可能不是你预期的那一个。3.4 接入 Teams、飞书等外部通道接入外部平台本质上是“新增通道”。以 Teams 为例你需要在微软那边注册一个机器人应用拿到 Bot ID 和密码然后在 OpenClaw 的通道配置里填进去。飞书也是类似逻辑创建飞书机器人、拿 App ID 和 App Secret、配置事件订阅地址最后在 OpenClaw 里启用飞书通道。这里提醒一句外部通道的消息格式限制很多。飞书的普通文本消息有长度上限Teams 的消息也有自己的一套长度和卡片规则。很多人测试时发现“openclaw 在飞书输出容易被截断”根因往往不在 OpenClaw 而在通道适配层没有处理分段发送。这个我放在第 5 部分细说。4. 关键配置项与调优参数4.1 环境变量与配置文件速查不同版本的 OpenClaw 配置方式略有差异有的用环境变量有的用 JSON 配置文件有的两者都支持。我习惯用环境变量管密钥、用配置文件管业务逻辑。下面这张表是我经常用到的配置项具体名字以你安装的那个版本的文档为准配置项示例作用备注OPENCLAW_PORT/ 配置里的 portpi-web-ui 监听端口默认 3123监听地址 bind address是否允许外部访问本机用 127.0.0.1局域网用 0.0.0.0Token / 连接密钥访问 pi-web-ui 的凭证首次启动日志里有模型 providerbase URL / api key / model指定 Agent 使用的大模型千问、DeepSeek 等均可会话存储类型file / redis / postgres单机默认 file会话锁超时时间控制等待锁的最长时间默认 60000ms4.2 会话并发与锁机制调优如果你只是单机自用并发量不大默认的 file 会话存储完全够用。但你一旦同时开了多个入口Web UI CLI 飞书或者在一个界面上开了多个会话、让 Agent 跑耗时的工具调用会话文件的锁冲突概率就会明显上升。调优方向有三个把会话存储从 file 换成 Redis 或 Postgres。这样“锁”就不再依赖本地文件系统而是由 Redis 的原子操作或数据库行锁来保证能支撑多进程并发调大锁超时时间。如果你的 Agent 经常执行耗时很长的任务比如调用外部工具等响应默认 60 秒可能不够。但这是治标不治本降低并发冲突面的最朴素手段同一时间只让一个入口操作同一个会话。很多人其实是“两个窗口同时跟同一个 Agent 聊天”属于自己制造锁竞争。我个人建议把这三件事都做一遍换存储、调超时、规范使用习惯。只做其中任何一件问题都可能反复。4.3 输出安全与消息拆分策略接入飞书、Teams 这类外部通道时输出截断的本质是通道限制。通用解法是在通道适配层加一个“消息拆分器”把 Agent 返回的长文本按通道允许的长度切分成多段逐段发送。切分时要注意边界不要在代码块中间切。飞书和 Teams 对 Markdown 代码块有自己的渲染逻辑从中间切断会导致后半段格式错乱尽量在段落边界切保证语义完整如果通道支持卡片/富文本优先用卡片承载长内容比纯文本的限额更宽。这个策略说起来简单但很多初学者不知道去哪里改。在 pi-mono 里每个通道的发送逻辑在对应的 channel 实现里你找发送消息的函数在里面加分段逻辑即可。动手前先备份一份文件改错了能回滚。5. 常见问题与排查实录5.1 session file locked timeout 60000ms 的完整排查思路这是社区里最热的一条报错。完整报错通常长这样agent failed before reply: session file locked (timeout 60000ms)。先说结论这不是模型的问题也不是网络问题是会话文件被锁住了系统等锁等了 60 秒没等到于是抛错。下面是我在实际排查时的固定流程第一步确认是不是有多个 OpenClaw 进程同时在跑。用 Windows 的任务管理器或者 Linux 的ps aux | grep openclaw看一下。如果存在多个进程先停掉多余的。这一步能解决八成的问题。第二步看会话目录下有没有残留的锁文件。有些意外退出比如强制关机、进程被杀不会触发锁释放会留下一个“僵尸锁”。找到对应该会话的锁文件手动删掉再启动服务。第三步如果问题频繁出现说明你的使用模式触发了并发写。要么换 Redis/Postgres 存储要么调大超时时间要么老老实实不要同时用多个入口操作同一个会话。第四步也是我想强调的这类问题不要只靠“重启大法”。重启能清掉僵尸锁但如果根因是并发设计问题重启之后还会犯。花点时间把存储层升级一下是值得的。5.2 飞书输出截断根因不是模型而是通道限制“openclaw 在飞书输出容易被截断”这个现象我调试过好几次。一开始我也以为是模型输出长度把上下文撑爆了后来看日志发现是飞书通道对单条消息的长度限制比 Web UI 通道严格得多。排查思路是这样如果同样一段长回答在 pi-web-ui 里完整显示、在飞书里被截断那问题就不在 Agent而在飞书通道的发送逻辑。解决方案就是我之前说的消息拆分。另外飞书机器人还可以考虑用“富文本卡片”来代替纯文本消息卡片的容量限制更宽松而且展示效果好很多。5.3 Agent 怎么选择 Channel路由优先级与粘性会话关于“agent 怎么选择 channel”我讲一个最简单的理解方式OpenClaw 的 gateway 在路由消息时会先看这条消息来自哪个通道再看这个通道被分配给了哪个 Agent。如果你只有一个 Agent、所有通道都挂在它名下那你根本不用操心路由问题。但如果你配了多个 Agent比如一个用千问处理日常对话一个用代码模型专门写脚本你就需要显式配置哪些通道归哪个 Agent。配置不当时常见症状是“我在飞书发消息Agent 不理我”或者“回答的模型不是我以为的那个”。我的建议是前期只配一个 Agent、把所有通道都给它跑通之后再拆。一上来就搞多 Agent 分流排查问题的复杂度会翻好几倍。5.4 几个容易踩的坑最后补几个我踩过、周围人也反复踩的坑改了配置不重启。OpenClaw 很多配置是启动时读取的改完不重启等于没改。你对着配置文件怀疑人生之前先重启一次服务日志里找线索。遇到问题第一反应应该是看日志而不是到处问人。OpenClaw 日志里会打印完整的错误栈绝大多数问题自己就能定位Web UI 设置了外部访问后Token 不要泄露。这东西等于你 Agent 的钥匙拿到的人可以直接跟你的 Agent 对话、让它执行工具不要把数据目录放在同步盘里。有人把 OpenClaw 数据目录放在云同步文件夹里结果两边机器同时读写会话文件锁冲突比谁都频繁。我个人在实际操作中的体会是pi-web-ui 表面上看只是个聊天窗口但它的架构位置非常典型一头连着浏览器的实时交互一头连着 gateway 的消息路由还要处理会话状态、认证、通道适配这些杂活。把它拆明白你在 pi-mono 里再去看其他模块就会顺很多。下一篇我打算顺着这条链路往上游走拆一下 pi-gateway 的消息路由和会话管理那是整套系统真正的中枢。