最近我把 OpenClaw 的源码从头到尾过了一遍连带把 issue 区、部署脚本和几个官方连接器的实现都翻了。这个项目最近在 agent 圈子里讨论度不低但大多数讨论都停留在“怎么装”“怎么配置”的层面真正讲清楚它内部是怎么组织的、每个模块为什么这么设计的内容很少。这篇文章我直接按源码架构来拆从入口、会话、代理循环到连接器、持久化、锁机制一条线讲到底读完你应该能自己定位问题、动手改扩展甚至能把它当成一个 agent 框架的参考样板来用。先说 OpenClaw 是什么。它是一个面向个人电脑场景的开源 AI 代理运行时核心思路是让大模型驱动的 agent 不只能聊天还能真正操作电脑上的工具读写文件、执行命令、操作浏览器同时把 Slack、Microsoft Teams、OBSIDIAN 这类外部渠道接进来让 agent 能通过 IM 对话被调用。它不是又一个 chatbot 脚手架而是一个把“会话管理、工具调用、渠道接入、权限控制”全部串起来的完整 runtime。官方文档对架构讲得比较空真正的设计意图全在代码里下面我就按源码的模块界线一点一点展开。1. 整体架构设计OpenClaw 到底在解决什么问题1.1 不是“模型封装”而是一套 agent 运行时很多人第一次看 OpenClaw 源码会有点懵因为它的目录结构不像常见的 LLM SDK没有大段大段的模型调用封装反而更像一个消息系统加一个任务调度的合体。这其实是它最核心的设计判断agent 应用真正难的不是调模型而是把模型放到一个有边界的运行环境里让它能安全地调用工具、稳定地记住上下文、可靠地被外部渠道触发。# 源码根目录的核心结构简化示意 openclaw/ ├── core/ # 核心运行时入口、生命周期、会话 ├── agents/ # 代理逻辑决策循环、工具选择、回复生成 ├── tools/ # 内置工具集文件、命令、浏览器、笔记 ├── channels/ # 连接器Slack、Teams、CLI、OBSIDIAN 等 ├── memory/ # 会话持久化、上下文管理 ├── config/ # 配置解析、环境变量、权限策略 └── server/ # HTTP/本地服务层这套分层有一个很明确的依赖方向channels只负责收发消息不直接碰模型agents只负责“想和做”不关心消息从哪来tools是最底层的能力单元可以被任何上层模块调用memory和config是横切关注点把“状态”和“策略”从业务代码里抽出来。理解了这个依赖方向再看代码就不会迷路。从源码的入口函数能明显看到它的启动顺序先解析配置再初始化存储然后注册工具最后挂载连接器。这个顺序不是随便写的——配置决定了后面所有模块的行为参数存储必须先就绪才能恢复会话工具注册必须在连接器启动之前完成否则外部消息进来时 agent 已经处于“有嘴但没手”的状态。源码里把这个初始化流程放在一个bootstrap函数里集中处理目的就是为了让启动路径只有一条避免不同部署方式各自初始化导致状态不一致。很多 agent 项目死在“demo 能跑、生产不能用”根源就是把配置、会话、工具调用全揉在一起。OpenClaw 源码给我的第一个启发就是agent 框架的本质是“运行时”你要先定义好边界再谈智能。1.2 六大核心抽象一切皆可替换读完整份源码我提炼出六个核心抽象OpenClaw 的整个架构都是围绕它们转的抽象对应源码模块职责典型实现Agentagents/决策循环、生成回复、选择工具Claude/GPT 驱动的 ReAct 风格循环Tooltools/一个可被模型调用的能力单元文件读写、命令执行、网页搜索Channelchannels/与外部世界的消息出入口CLI、Slack、Teams、OBSIDIANSessionmemory/一次对话的完整状态容器会话 ID、消息历史、元数据Storememory/会话的持久化介质本地 JSON 文件存储Authorizerconfig/工具调用的审批策略自动放行、人工审批、白名单每个抽象都对应一个基类或者协议接口自定义实现只需要满足接口约束然后通过配置注册进去。举几个源码里实际体现出来的扩展点工具模块只需要实现execute和schema两个方法就能被 agent 自动发现通道模块只需要实现send和on_event两个回调就能接入新的 IM 平台存储模块只需要满足“按 session_id 读、写、锁”三个操作就能替换成 Redis 或数据库后端。这种“一切皆可替换”的设计让 OpenClaw 的定位很清晰它不绑定任何单一模型厂商也不绑定任何单一渠道。你在源码里看不到写死的供应商 SDK 调用取而代之的是统一的model接口层。实际部署中你可以自由切后端模型连接器这块也能只启用自己需要的渠道其他全部禁用减少无谓的资源占用。2. 核心模块拆解从启动到一次对话的完整链路2.1 入口与生命周期管理一条启动路径保证状态一致我用伪代码还原一下源码里的启动主流程方便对照你自己的部署日志定位问题# 源码启动逻辑的伪代码还原 def main(): config load_config() # 1. 读取配置环境变量 配置文件 默认值 store init_store(config) # 2. 初始化会话存储 tools register_tools(config) # 3. 注册全部工具到工具注册表 agent create_agent(config) # 4. 创建代理实例绑定模型后端 server init_server(config) # 5. 初始化本地服务/CLI/端口监听 for ch in config.channels: # 6. 挂载每个启用的连接器 channel load_channel(ch) channel.attach(agent, store) agent.start() # 7. 启动消息处理循环注意第 3 步和第 6 步的前后关系工具注册一定发生在连接器挂载之前。这样设计的原因很实际——当 Slack 里第一条消息到达时agent 必须已经知道“自己有哪些工具可用”才能在决策循环里给出靠谱的计划。如果你在部署时发现“能收到消息但 agent 一直说没有可用工具”大概率就是工具注册环节出了问题而不是模型的问题。生命周期管理还有一个很容易被忽略的细节正常退出和异常退出是两条不同的路径。源码里对SIGINT和SIGTERM做了优雅退出处理核心动作是“释放会话锁 刷新存储缓冲”。曾经有一个常见问题就是直接kill -9导致会话文件没来得及释放锁重启后其他请求被卡住这个后面我会在问题排查部分详细展开。2.2 会话与状态管理一次对话的“文件柜”是怎么设计的OpenClaw 的会话管理是源码里最值得读的部分因为很多 agent 框架根本不重视这一层。它把每个会话建模成一个独立的“状态容器”里面包含消息历史、当前上下文摘要、会话元数据创建时间、关联渠道、最后活跃时间。源码里这个模型用数据类定义得很规整字段不多但覆盖了对话恢复所需的全部信息。# 会话模型的核心字段源码简化示意 dataclass class Session: id: str # 全局唯一会话标识 channel: str # 来自哪个渠道cli/slack/teams... messages: list[Message] # 完整消息历史 context: str | None # 压缩后的长程上下文摘要 created_at: datetime updated_at: datetime locked: bool # 文件锁状态标记这里的设计精髓是“按渠道隔离会话”。同一个用户在 Slack 里的对话和 CLI 里的对话是两套会话互不干扰但同一个渠道内系统会通过channel user_id的组合自动复用或创建会话。这样你在手机上通过 Teams 聊到一半换到电脑上用 CLI 继续两边不会串上下文这在实际使用中非常影响体验源码里这种“每个渠道一条独立记忆线”的思路值得借鉴。2.3 代理循环与工具调用agent 是怎么“想”和“做”的代理循环是 OpenClaw 源码中“智能”浓度最高的模块。它的机制并不神秘本质是一个带工具调用的多步推理循环看历史、决定动作、执行工具、观察结果、再决定下一步。源码里这个循环写得非常克制没有花哨的规划器而是把控制流交给模型自身靠“结构化输出”约束模型回复格式。# 代理循环的伪代码还原 def run_agent_turn(session): history build_prompt(session) response model.generate(history, toolstool_schemas) if response.has_tool_call(): result execute_tool(response.tool_call) # 实际执行工具 session.add_tool_result(result) return run_agent_turn(session) # 循环直到生成最终回复 else: session.add_message(response.text) return response.text这个循环包含两个关键设计。第一是“模型只负责决策执行永远在沙箱里”。模型返回的是一个结构化的工具调用意图工具名 参数真正的执行动作发生在本地受控环境不允许模型直接执行任意代码。第二是“工具执行结果必须回填会话”每次工具调用的结果都会作为新消息追加到会话历史里模型下一次推理能看到上次执行的真实反馈。这看起来简单但实现上很容易踩坑——如果工具结果不回填或者回填格式不一致模型会陷入“自说自话”的幻觉循环。还有一个细节值得提工具调用的参数校验。源码在把参数传给实际函数之前会先按工具的 JSON Schema 做一次严格校验不合法直接报错返回给模型。这个设计避免了很多“模型以为传了整数实际传了字符串”的经典翻车现场。我自己在扩展自定义工具时就因为忽略了 Schema 定义被卡了半天后来才发现工具总是失败不是模型的问题是我的参数类型定义写错了。2.4 连接器层如何把 Slack、Teams、CLI 统一成一套接口连接器层是我认为 OpenClaw 架构中最具工程借鉴价值的部分。每个外部渠道的使用方式千差万别——Slack 有 Socket Mode、Teams 有 Bot Framework、OBSIDIAN 有本地插件接口、CLI 就是标准输入输出——但源码里把它们全部收敛成了一个通道接口send方法和on_event回调。# 连接器的统一接口源码简化为伪代码 class Channel: name: str async def send(self, target: str, content: str): ... async def on_event(self, event): ...实际接入一个新渠道时你只需要实现这两件事把渠道的“收到消息”转换成统一事件对象调用 agent 处理把 agent 的回复通过渠道的 API 发回去。其余的事情——会话创建、上下文管理、工具调用——全部由核心运行时接管连接器完全不需要关心。这种设计带来一个很直接的好处渠道之间是完全解耦的可以独立启停。你可以只开 CLI 做本地调试不上任何外部渠道也可以同时挂 Slack 和 Teams系统会给每个渠道分配独立的消息监听循环。在源码里每个连接器跑在独立的任务中互不阻塞一个渠道抛异常不会拖垮整个进程。我在部署时发现 Teams 连接器因为网络原因连不上CLI 和 Slack 照常工作日志里只有 Teams 的报错这种故障隔离在 agent 常驻进程里非常关键。3. 关键机制实现细节持久化、配置与权限3.1 文件存储与锁机制为什么会话文件会被锁住OpenClaw 默认的会话持久化是本地文件存储每个会话对应一个 JSON 文件。源码里用fcntlLinux 下的文件锁来保证同一个会话同一时刻只能被一个请求处理。这个锁的本质是防止并发写坏会话文件如果两个请求同时往同一个 session 文件里写消息轻则丢消息重则整个文件损坏。# 会话文件的实际存放结构 ~/.openclaw/ └── sessions/ ├── slack_user_123.json.lock # 锁文件 └── slack_user_123.json # 会话数据锁机制本身不算复杂但它在实际运行中对应着一个最常被搜索的报错agent failed before reply: session file locked (timeout 60000ms)。这个报错的含义非常直白——有另一个请求持有锁超过 60 秒当前请求等不到锁被释放就超时了。常见触发场景有三个你同时开了两个 CLI 窗口操作同一个会话某个任务中模型或工具执行卡死、锁没释放异常退出后锁文件残留没有清理。遇到这个报错第一步别急着重启进程先看有没有其他活跃请求再查锁文件是否残留最后再考虑重启。盲目重启不但解决不了问题还可能让正在执行的工具任务被中断。3.2 配置体系的优先级与权限控制OpenClaw 的配置解析有一个明确的优先级链环境变量 配置文件 内置默认值。源码里对每个配置项都定义了默认值所以你即使完全不做配置也能启动只是功能受限。这个“零配置可启动”的思路对新手很友好但也容易埋坑——如果你配错了环境变量但默认值还能顶上服务看起来正常实际上某些能力是静默失效的。权限控制是 OpenClaw 源码里一个容易被忽略但极其重要的模块。它的核心问题是agent 要操作你的电脑凭什么能让它安全地干源码的策略是给工具打标安全工具自动放行危险工具需要审批。文件读取、网页搜索属于自动放行执行任意 shell 命令、修改关键配置属于需要审批。审批请求会通过当前渠道发给用户用户确认后授权执行。这套机制的本质是把“模型不可信”作为默认前提权限策略独立于模型模型只能决定“想做什么”不能决定“什么能做”。3.3 上下文管理模型记忆是怎么被压缩的上下文长度是 agent 应用最现实的瓶颈OpenClaw 源码里处理这个问题的方式可以用两个字概括压缩。当会话历史超过配置的窗口阈值时系统会触发一次“上下文摘要”把早期消息浓缩成一段摘要文本作为新的上下文基座替代原始消息。# 上下文压缩策略源码逻辑伪代码 if session.total_tokens max_context_tokens: summary summarize(session.messages[:-keep_last]) # 压缩旧消息 session.context summary # 保存摘要 session.messages [system_prompt] session.messages[-keep_last:]这个策略里最有意思的是“保留最近 N 条完整消息”的设计。它假设最近的消息包含当前任务最相关的信息而早期消息可以容忍信息损失。实际使用中这个策略很有效但也有代价压缩后模型对早期细节的记忆会变模糊比如你跟 agent 在五轮之前约定过一个细节摘要压缩后它可能就“忘”了。这时候你可以显式地把重要约定写进系统提示词或者让上下文更长这是个需要根据场景取舍的参数。4. 部署、运行与常见问题排查4.1 部署形态与 Ubuntu 安装要点源码仓库里提供了完整的部署脚本支持 Docker 和本机直接运行两种方式。对大多数场景我建议直接本机跑因为 agent 需要访问本地文件系统和命令容器化反而要处理额外的权限映射。Ubuntu 上的安装步骤大致是准备 Python 环境、克隆仓库、安装依赖、初始化配置、启动服务。启动后它会拉起一个本地监听服务同时启动你配置好的渠道连接器。部署时有一个关键点OpenClaw 的本地服务默认是本地绑定不暴露到公网。如果你希望从其他设备访问需要自己用反向代理做转发但此时务必把鉴权开好否则 agent 的操作权限就等同于这台机器的操作权限这个风险比想象中大得多。源码中有一整套审批机制但如果你部署的服务被公网直接访问相当于审批机制的外部防线彻底失效了。4.2 连接器接入实战Microsoft Teams 与 OBSIDIAN接入 Microsoft Teams 时需要先创建 Bot 服务拿到 Bot 的 App ID 和密码然后在 OpenClaw 配置里启用 Teams 连接器把凭证填进去再配置消息的接收路径。这里最容易出错的是 Teams Bot 的权限范围如果没配好消息接收权限agent 能发消息但收不到消息很迷惑。排查这类问题有个技巧看连接器启动日志里有没有成功建立连接的标志如果连接器压根没起来问题一定在凭证或网络层先别去怀疑核心代码。OBSIDIAN 的接入思路就很不一样。它走的是本地插件通道不需要公网配置核心是让 agent 能读写 OBSIDIAN 的 Vault 目录。源码里对应的工具就是一组笔记读写函数权限上相当于给 agent 开放了本地知识库的读写能力。实际应用中我会建议把 OBSIDIAN 工具和审批策略配合使用——写入类操作可以放行删除类操作一定要审批不然模型一旦误判把整个知识库删了连后悔的机会都没有。4.3 高频问题速查表部署 Agent 前先存一份问题现象根因方向排查与解决启动报错缺依赖环境版本不匹配先看 Python 版本用官方 requirements 重建虚拟环境消息进来但 agent 不回复模型配置缺失或凭证无效检查模型后端配置用 CLI 渠道测试裸对话回复到一半卡死工具调用等待外部资源看日志里卡在哪个工具检查网络与文件句柄session file locked报错会话锁未释放或并发冲突查活跃进程、清理锁文件、避免多入口操作同一会话Teams 能发不能收Bot 权限配置错误检查 Teams 应用的消息接收权限和通道配置记忆“变笨”上下文被压缩调整 max_context_tokens 或把关键约定写入系统提示词还有一个隐藏问题值得单独提多实例并发。如果你用进程管理器同时跑了两个 OpenClaw 实例它们会争抢同一个会话目录。文件锁在这种情况下能保护文件不损坏但会把另一个实例的请求全部阻塞到超时。所以务必确保同一时刻只有一个实例在操作同一个数据目录。这个“单实例原则”在官方文档里没有重点强调但我实际部署中吃过两次亏版本升级时新旧进程重叠运行整个会话层完全不可用排了半天才发现是两个实例在抢锁。5. 从源码里学到的工程经验5.1 三个值得直接借鉴的设计第一个是“工具注册表 Schema 自描述”。OpenClaw 里每个工具都自带 JSON Schema 描述自己的参数结构模型通过这个 Schema 学习怎么调用工具框架通过这个 Schema 校验参数。这套设计让新增一个工具几乎零成本同时天然支持模型能力的动态扩展比硬编码参数映射优雅太多。第二个是“渠道事件标准化”。不管消息来自 Slack 还是本地 CLI进入核心运行时之前都会先被转换成统一事件格式。这让核心逻辑可以完全脱离渠道差异agent 根本不需要知道自己是在跟 Slack 用户说话还是跟终端用户说话。这种事件标准化思想在做任何多端产品时都值得照搬。第三个是“配置和权限外置”。模型、工具、渠道的核心代码里没有任何一处硬编码的权限判断所有安全边界都在配置层定义。这个设计让“模型不可信”真正落到了架构层面而不是靠开发者的自觉。5.2 作者留给我们的坑与教训源码在锁机制上吃过不少苦头否则不会有 60 秒超时这种防御机制。这给我的教训是状态持久化一定要考虑并发哪怕你预判并发量很低文件锁和原子写入也是必需品。另一个明显的教训是默认配置虽然“零配置可启动”但会让很多人忽略权限配置导致 agent 实际上处于“裸奔”状态开发者以为默认已经安全了实际默认值为了易用性必然牺牲部分安全性。所以如果你要基于 OpenClaw 做生产部署权限配置应当是第一优先级的审查项而不是功能调通之后再看。代理循环里那个“简单循环 工具回填”的模式也值得多说一句。很多人以为 agent 智能来自复杂的规划算法但 OpenClaw 用极简的实现证明了只要工具足够丰富、工具结果回填足够规范一个简单的循环就能产生非常强的应用效果。与其去追花哨的规划器不如先把手里的工具链打磨好。这是我在这个项目里收获最大的一条经验。最后分享一个我自己调试时的技巧给 OpenClaw 加自定义工具时先用 CLI 渠道跑通再接入外部渠道。CLI 渠道的日志最完整、没有网络变量所有问题和工具调用过程都清晰可见。等 CLI 下确认逻辑没问题再去启用 Teams 或 Slack这样能把“工具逻辑问题”和“渠道接入问题”分开处理排查效率能高出一大截。这套“先本地打通、再外联扩展”的调试顺序我后来用在了所有 agent 相关的项目里比什么都调好再联调要省力得多。