1. 先建立目录地图OpenClaw 仓库目录结构到底长什么样OpenClaw 是一个本地优先、多渠道、可调用工具、可扩展技能、带安全隔离机制的个人 AI 助手系统。很多人第一次 clone 下来看到根目录几十个文件夹第一反应是懵的——src、extensions、skills、packages、apps、ui、docs、security、test、qa、scripts、config、deploy全堆在一起不知道从哪下手。我试过直接打开src里某个文件逐行读结果看了半小时还在猜这个模块在整个系统里处于什么位置。后来才明白读这种工程规模的项目第一步不是钻代码而是先画一张目录地图知道每个目录大概负责什么再顺着主链路往里走。这篇文章解决三件事第一把 OpenClaw 根目录逐层拆开说清src、extensions、skills、packages、apps、ui各自职责第二给出可复制的目录树注释和关键配置文件片段第三结合 TaoToken 统一 Key/API 通道把接入后的连通性验证步骤跑通让你不只是看懂结构还能实际发出一次请求。适合谁看正在读 OpenClaw 源码但找不到入口的开发者想把 OpenClaw 接到统一模型通道上的工程同学以及需要一份「目录职责速查表」方便后续按模块推进的读者。先给结论OpenClaw 的仓库结构可以分成六类内容。核心运行时代码在src扩展与插件在extensions和packages技能和能力模板在skills应用端和界面在apps和ui工程支持在config、deploy、scripts、docs质量与安全在test、qa、security。根目录还有openclaw.mjs、package.json、pnpm-workspace.yaml、多个tsconfig文件和构建配置说明它是以 Node / TypeScript / pnpm workspace 为核心组织方式的项目。这张地图的价值在于后面无论你分析 CLI、Gateway、Channel、Agent、Tools、Skills 还是 Sandbox都能先定位到对应目录不会迷路。下面按目录逐个拆。1.1 src核心运行时代码src是后续源码解析最重要的目录。它下面包含agents、channels、chat、cli、commands、config、cron、daemon等子目录。可以先用一张注释树理解src/ ├─ cli/ # 命令行入口openclaw 命令从这里进入 ├─ commands/ # 具体命令实现如 agent、gateway、onboard ├─ daemon/ # Gateway 后台运行相关逻辑 ├─ config/ # 配置加载与解析对应 openclaw.json ├─ agents/ # Agent 相关逻辑消息如何被处理 ├─ channels/ # 渠道接入外部消息平台如何进来 ├─ chat/ # 对话处理相关逻辑 ├─ cron/ # 定时任务相关逻辑 └─ ... # 其他运行时模块src的地位类似整个项目的「大脑和神经系统」。你后面会反复回到这里找答案openclaw命令如何解析Gateway 如何启动用户消息如何进入 Agentsession 如何创建和保存模型如何被调用工具和技能如何加入上下文读src不建议按字母顺序而是按主链路走先看cli/commands找到命令入口再看daemon/ gateway 相关代码理解常驻服务然后看config理解配置加载接着看agents/chat理解消息处理再看channels理解外部接入最后才看 tools、skills、sessions、cron 等扩展能力。链路可以概括为CLI → Gateway → Config / Session → Agent → Model / Tools / Skills → Response。1.2 extensions 与 packages插件与共享基础层extensions是 OpenClaw 很有特点的目录里面包含很多扩展项例如active-memory、admin-http-rpc、alibaba、amazon-bedrock、anthropic、azure-speech、browser等。它说明 OpenClaw 的很多能力不是硬编码在核心运行时里而是通过 extension 组织。大致分几类模型提供商扩展anthropic、amazon-bedrock、alibaba、byteplus 等、语音或多媒体扩展azure-speech 等、工具或系统能力扩展browser、active-memory、admin-http-rpc 等。src和extensions的关系可以这样理解src定义核心运行机制说明模型调用需要经过什么抽象接口extensions提供可插拔能力负责实现 Anthropic 怎么调、Amazon Bedrock 怎么调、浏览器工具怎么用、语音服务怎么接。核心框架保持稳定具体能力以插件形式接入这也是它支持很多模型、渠道和工具的原因。packages目录包含memory-host-sdk、plugin-package-contract、plugin-sdk、sdk等子目录偏向「可复用包」和「接口契约」。packages/sdk面向调用 OpenClaw 能力的 SDKpackages/plugin-sdk是插件开发相关 SDKpackages/plugin-package-contract是插件包的结构或协议约束packages/memory-host-sdk是记忆宿主相关的 SDK 或接口。初学者不用一开始深入它的意义是当你在src或extensions里看到引用的 SDK、类型、接口时回到packages找公共抽象定义。1.3 skills 与 apps、ui技能库、多端应用和控制界面skills是另一个重点目录包含很多内置技能例如1password、apple-notes、apple-reminders、bear-notes、blogwatcher、canvas、coding-agent、diagram-maker、discord、gh-issues等。它体现的是OpenClaw 不只是调用工具还可以通过技能文件获得特定任务能力。Tool 让 Agent 能做某个动作Skill 告诉 Agent 如何完成某类任务。比如apple-notes可能和 Apple Notes 工作流有关coding-agent可能和代码任务有关diagram-maker可能和图表生成有关gh-issues可能和 GitHub issue 处理有关。skills和extensions容易混淆区分方式extensions更偏程序能力扩展通常包含 TypeScript 代码、服务接入、模型接入、工具实现skills更偏 Agent 使用层能力通常告诉 Agent 如何完成某类任务、如何使用某些工具、如何遵守某些流程。browser extension 提供浏览器能力web research skill 告诉 Agent 如何用浏览器做网页调研。extension 更像底层能力skill 更像上层使用方法。apps目录下有android、ios、macos、macos-mlx-tts、shared/OpenClawKit、swabble等子目录说明 OpenClaw 不只面向命令行或浏览器还包含移动端、桌面端和共享应用组件。apps/android是 Android 节点或移动端相关代码apps/ios是 iOS 节点或移动端相关代码apps/macos是 macOS 桌面端或菜单栏应用相关代码apps/macos-mlx-tts是 macOS 上与本地语音合成相关的能力apps/shared/OpenClawKit是多端共享的基础库或组件。apps不建议一开始深入建议先看src理解 Gateway 和 Agent再看extensions/skills理解能力扩展最后看apps理解端侧如何接入 Gateway。ui目录包含public、src、index.html、package.json、vite.config.ts、vitest.config.ts等文件是一个使用 Vite 组织构建的前端项目大概率对应 Control UI。Gateway 负责后端控制平面ui负责把 Gateway 状态、会话、配置、工具或 Canvas 等内容可视化展示。注意构建链路是分开的pnpm gateway:watch不会自动重建dist/control-ui修改ui/后需要重新执行pnpm ui:build或使用pnpm ui:dev。1.4 docs、security、test、qa、config、deploy、scripts 与根目录关键文件docs目录非常重要适合辅助源码阅读。它包含.generated、.i18n、announcements、assets、automation、channels、cli、concepts、debug、diagnostics、gateway、install、nodes等子目录覆盖安装、CLI、Gateway、Channel、节点、调试、诊断、概念解释、自动化和源码模块一一对应。读 CLI 源码前先看docs/cli读 Gateway 源码前先看docs/gateway读 Channel 源码前先看docs/channels读 Nodes 源码前先看docs/nodes遇到问题看docs/debug和docs/diagnostics。security目录包含opengrep和README.md保存 OpenClaw 发布的 OpenGrep 安全规则包以及验证和运行这些规则的支持工具。它的意义有三层项目本身需要安全扫描规则防止代码层面风险回归Agent 工具调用需要安全边界避免模型滥用高风险能力外部消息入口可能带来 prompt injection、恶意链接、恶意指令等风险。后续讲 Sandbox、安全模型、DM pairing、工具权限时可以把security作为辅助材料。config、deploy、scripts通常不是最吸引人的地方但对工程运行很重要。config是项目默认配置、模板配置或环境相关配置deploy是部署相关内容例如容器、云平台或服务部署文件scripts是开发、构建、检查、生成、发布等脚本。想知道默认配置从哪来就看config想知道如何部署就看deploy想知道pnpm某个命令背后跑了什么就看scripts和package.json。test和qa同时存在test更可能保存自动化测试代码qa更可能保存质量检查、验收、测试场景或项目质量保障相关内容。测试用例非常有价值它通常告诉你某个模块应该如何被调用、输入输出是什么、异常情况如何处理、作者认为哪些行为必须保持稳定。看 CLI 找 CLI 相关测试看 Gateway 找 Gateway 相关测试看 Channel 找 Channel 或 adapter 相关测试看 Skills 找 skills 加载或解析相关测试。根目录关键文件也值得关注README.md是项目定位和快速使用入口package.json是脚本、依赖、bin 命令、构建流程入口openclaw.mjs是 CLI 运行入口之一pnpm-workspace.yaml说明 workspace 如何组织tsconfig*.json说明 TypeScript 编译边界Dockerfile/docker-compose.yml说明容器化运行方式SECURITY.md说明安全报告和安全策略AGENTS.md/CLAUDE.md是面向 Agent 或代码助手的项目说明。一张简化目录地图openclaw/ ├─ src/ # 核心运行时代码 │ ├─ cli/ # CLI 命令入口 │ ├─ commands/ # 具体命令实现 │ ├─ agents/ # Agent 相关逻辑 │ ├─ channels/ # 渠道接入逻辑 │ ├─ chat/ # 对话处理逻辑 │ ├─ config/ # 配置加载逻辑 │ ├─ daemon/ # Gateway / daemon 相关逻辑 │ └─ cron/ # 定时任务相关逻辑 ├─ extensions/ # 插件、模型、工具、平台扩展 ├─ packages/ # SDK、插件契约、共享包 ├─ skills/ # 内置技能库 ├─ apps/ # Android / iOS / macOS 等端侧应用 ├─ ui/ # Control UI / 前端界面 ├─ docs/ # 官方文档 ├─ security/ # 安全规则和安全工具 ├─ test/ # 自动化测试 ├─ qa/ # 质量保障相关内容 ├─ config/ # 配置模板或默认配置 ├─ deploy/ # 部署相关内容 └─ scripts/ # 工程脚本建议的阅读顺序第一阶段入口和主链路package.json→openclaw.mjs→src/cli→src/commands→src/daemon第二阶段核心运行机制src/config→src/agents→src/chat→src/channels第三阶段能力扩展extensions→packages→skills第四阶段安全和工程化security→test/qa→docs/debug/docs/diagnostics第五阶段前端和多端ui→apps。逻辑是先知道命令怎么进来再知道 Gateway 怎么运行再知道 Agent 怎么处理消息再知道工具、技能和扩展怎么增强能力最后看 UI、移动端和安全细节。2. TaoToken 前置统一 Key/API 通道在 OpenClaw 里的位置OpenClaw 的extensions目录里有一堆模型提供商扩展anthropic、amazon-bedrock、alibaba、byteplus 各占一个。如果你每个提供商都单独配 Key、单独管 Base URL很快就会乱这个 Key 放哪个环境变量、那个 Base URL 写哪个配置文件、换模型时改哪一行。TaoToken 在这里的角色是统一 Key/API 通道——用一个 Key、一个 Base URL把模型调用收敛到一条通道上OpenClaw 侧只需要按 OpenAI 兼容格式配置即可。为什么放在「前置」这一节讲因为后面第三节的可复制配置、第四节的连通性验证都依赖你先拿到 Key 和 Base URL。这一步不复杂但顺序不能反。先明确三个东西项目值说明Base URLhttps://taotoken.net/apiOpenAI 兼容接口地址不加 UTMAPI Key在控制台创建形如sk-...只显示一次Model ID按需选择填到配置里的模型标识获取 Key 的入口在控制台创建后复制保存。文档入口可以对照接口说明和参数。如果你后面要长期跑编码类 Agent 任务可以了解 Coding Plan如果只是想先验证模型能不能通用模型对话页面直接试最快。这里要强调一点TaoToken 是统一 API 通道不是让你替换掉 OpenClaw 的编辑器或运行时。OpenClaw 的src、extensions、skills该怎么跑还怎么跑TaoToken 只负责模型调用这一段。理解这一点后面配置才不会拧巴。具体操作顺序打开控制台登录后进入 API Keys 页面。创建一个新 Key命名建议带用途比如openclaw-dev方便后面区分。复制 Key粘贴到你的环境变量或配置文件里。注意只显示一次丢了就重建。记下 Base URLhttps://taotoken.net/api。选一个 Model ID先记下来配置时要用。如果你习惯用环境变量管理可以这样export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你更想把配置写进项目里OpenClaw 侧通常读openclaw.json或环境变量两种方式都行。关键是 Key 不要硬编码进会提交到 Git 的文件用.env或本地配置.gitignore里排除掉。踩过的坑提醒一句有人把 Key 写进openclaw.json然后直接 commit结果 Key 泄露。正确做法是配置文件里引用环境变量或者把本地配置文件加进.gitignore。另外 Base URL 末尾不要多加/v1之类的路径按文档给的https://taotoken.net/api填多写反而容易 404。拿到这三件套之后就可以进入下一节的配置环节了。3. 可复制配置OpenClaw 侧接入 TaoToken 的完整片段这一节给可直接复制的配置片段。OpenClaw 是 pnpm workspace 项目配置读取路径和字段名以仓库实际为准下面给的是通用可用的写法你按自己仓库版本微调字段名即可。核心是三件套Base URL、API Key、Model ID。先看 JSON 形式适合写进openclaw.json或类似的配置文件{ models: { default: your-model-id, providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, models: { your-model-id: { id: your-model-id, contextWindow: 128000 } } } } } }注意apiKey用的是${TAOTOKEN_API_KEY}占位实际运行时从环境变量读避免明文写进文件。baseUrl就是https://taotoken.net/api不要加 UTM 参数也不要多加路径。your-model-id换成你在控制台选的 Model ID。如果你更习惯 TOML 形式可以这样[models] default your-model-id [models.providers.taotoken] type openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} [models.providers.taotoken.models.your-model-id] id your-model-id context_window 128000环境变量文件.envTAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 类工具链配置通常落在settings.json或~/.claude/settings.json写法类似{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key } }这里要提醒不同工具的环境变量名不一样Claude Code 用ANTHROPIC_BASE_URL/ANTHROPIC_API_KEYOpenAI 兼容客户端常用OPENAI_BASE_URL/OPENAI_API_KEY。你按实际工具选对应的变量名值都指向 TaoToken 的 Base URL 和你的 Key。如果你用 Codex 类工具配置可能落在auth.json三件套同样要写全{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: your-model-id }Cline MCP 场景下配置通常写在 MCP 的 settings 里同样是 Base URL Key Model ID 三件套缺一不可。CC Switch 这类切换工具也是同理切换的是通道配置不是替换运行时。配置写完检查三件事Base URL 是不是https://taotoken.net/apiKey 是不是从环境变量读的Model ID 是不是和控制台选的一致。这三件套对齐了连通性验证基本不会出问题。4. 验证请求从命令行到 OpenClaw 主链路的连通性检查配置写完不能只看文件要实际发一次请求。这一节给从简单到完整的验证步骤先确认通道通再确认 OpenClaw 能调。第一步用 curl 直接打 TaoToken 的接口确认 Key 和 Base URL 没问题curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: your-model-id, messages: [ {role: user, content: 只回复两个字通了} ] }预期返回是一个 JSONchoices[0].message.content里能看到模型回复。如果这一步就报 401说明 Key 不对或没读到环境变量如果报 404多半是 Base URL 写错了检查是不是多加了路径。第二步用 OpenAI 兼容客户端验证确认 SDK 层也能通import os from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelyour-model-id, messages[{role: user, content: 回复通道正常}], ) print(resp.choices[0].message.content)这一步能通说明你的 Key、Base URL、Model ID 三件套在标准客户端下没问题。第三步回到 OpenClaw 主链路。按第一节的目录地图命令入口在src/cli和src/commandsGateway 在src/daemon配置加载在src/config。你可以先启动 Gateway再通过 CLI 发一条消息# 启动 Gateway具体命令以仓库 package.json scripts 为准 pnpm gateway:watch # 另开终端通过 CLI 发消息 openclaw agent --message Hello如果配置正确你会看到 Agent 返回模型响应。这个过程走的就是第一节说的链路CLI → Gateway → Config / Session → Agent → Model / Tools / Skills → Response。模型调用这一段现在指向的是 TaoToken 通道。第四步验证 Control UI。如果你改了ui/记得先pnpm ui:build或pnpm ui:dev因为pnpm gateway:watch不会自动重建dist/control-ui。构建后在浏览器打开控制界面看会话和配置是否正常展示。成功结果长什么样curl 返回带choices的 JSONPython 脚本打印出模型回复OpenClaw CLI 返回 Agent 响应Control UI 能看到会话记录。四个都通说明从通道到 OpenClaw 主链路全部打通。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最常见的几类报错集中在这里。逐个对照排查。401 Unauthorized。这是最高频的。原因通常是 Key 没读到、Key 写错、或者环境变量没导出。排查顺序先echo $TAOTOKEN_API_KEY看环境变量有没有值再看配置文件里是不是用了${TAOTOKEN_API_KEY}占位但环境变量没设最后确认 Key 没有多余空格或换行。如果 Key 是从控制台复制的注意别把前后空格带进去。local proxy failed / connection refused。这类报错通常和本地网络或代理配置有关。检查你的 Base URL 是不是写成了http://localhost:xxxx之类的本地地址确认https://taotoken.net/api拼写正确如果你本地有网络工具确认它没有拦截这个域名。注意不要配置任何非官方的转发方式直接用文档给的 Base URL。reading choices 报错 / choices 字段为空。这通常是响应结构不符合预期。原因可能是 Model ID 写错服务端返回了错误结构或者 Base URL 多加了/v1导致路径不对。排查先用 curl 单独打一次看返回的 JSON 顶层有没有choices如果没有看error字段说了什么。Model ID 一定要和控制台选的一致。OAuth 相关报错。如果你用的是 Claude Code 类工具它可能默认走 OAuth 登录流程。当你配置了ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY后应该走 Key 认证而不是 OAuth。如果还报 OAuth 错检查是不是有旧的登录态缓存清掉后重新用 Key 配置。Codex 类工具的auth.json也要确认三件套写全缺 Model ID 也会报认证类错误。配置不生效。改了配置文件但行为没变常见原因是配置文件路径不对OpenClaw 读的是另一个位置或者进程没重启Gateway 还挂着旧配置。排查确认配置文件路径和仓库文档一致重启 Gateway用pnpm脚本确认命令背后读的是哪个配置。UI 改了没变化。这是构建链路问题不是配置问题。pnpm gateway:watch不会自动重建dist/control-ui你需要单独跑pnpm ui:build或pnpm ui:dev。这一点在第一节讲ui目录时提过容易忘。对照排查时建议按「先 curl、再 SDK、再 OpenClaw」的顺序定位。curl 通了说明通道没问题问题在 OpenClaw 配置curl 不通说明 Key 或 Base URL 有问题。这样能快速缩小范围。6. 接入之后把目录地图和通道配置串起来用回到第一节的目录地图现在你应该能把「读源码」和「跑通调用」两件事串起来了。src/cli和src/commands是命令入口你输入的openclaw agent --message Hello从这里进入src/daemon是 Gateway 常驻逻辑src/config负责加载你写的openclaw.jsonsrc/agents和src/chat处理消息模型调用这一段通过extensions里的提供商扩展或统一通道配置指向 TaoToken 的 Base URL。后续按模块推进时可以这样配合读 CLI 源码前先看docs/cli读 Gateway 前先看docs/gateway读 Channel 前先看docs/channels遇到问题看docs/debug和docs/diagnostics。测试目录test和qa用来确认模块的预期行为。security目录在你分析 Sandbox、工具权限、DM pairing 时作为辅助材料。如果你要长期跑编码类 Agent 任务可以了解 Coding Plan如果只是验证模型模型对话页面最快接入和排障过程中需要查接口细节接入文档和 API Keys 页面放在手边。最后给一个实用技巧把 Base URL、Key、Model ID 三件套写进一个本地.env所有工具都从这个文件读换工具时只改变量名不改值。这样无论你后面切 Claude Code、Codex、Cline MCP 还是 CC Switch通道配置都是一份不会出现「这个工具通了那个工具 401」的情况。目录地图帮你定位代码统一通道帮你收敛配置两件事分开管读源码和跑调用都不会互相干扰。