OpenClaw 作为开源的个人 AI 助手，v2026.2.26 版本采用 Monorepo（单体仓库）架构，目录结构和配置体系较旧版大幅重构。本文将从环境准备、源码结构解析、配置文件说明、调试配置到问题排查，完整覆盖本地开发全流程，帮你快速跑通 OpenClaw 网关服务并实现源码级调试。

一、环境前置准备

1. 核心依赖安装

OpenClaw v2026.2.26 基于 Node.js 开发，需先安装以下基础工具：

• Node.js：推荐 v18+ LTS 版本（官网下载），安装后验证：

  node -v && npm -v
  

• pnpm：Monorepo 项目依赖管理工具，全局安装：

  npm install -g pnpm
  

• Git for Windows：提供 Bash 环境（解决 Shell 脚本执行问题），官网下载，安装时勾选：
  • Use Git and optional Unix tools from the Command Prompt
  • Use UTF-8 encoding for all text files

2. VS Code 环境配置（可选但推荐）

安装以下插件提升开发效率：

• ESLint：代码规范检查
• Prettier：代码格式化
• TypeScript Debugger：TS 源码调试
• GitLens：Git 版本管理

二、源码拉取与目录结构解析

1. 克隆源码（或解压本地源码包）

# 克隆官方仓库（或直接解压本地源码到以下目录）
git clone https://github.com/OpenClaw/OpenClaw.git D:\code\node\openclaw
# 进入源码根目录
cd D:\code\node\openclaw

2. v2026.2.26 核心源码目录结构（Monorepo 架构）

该版本采用「车轮式架构」，src/ 为核心引擎，packages/ 为公共依赖，extensions/ 为扩展插件，所有模块通过 scripts/ 脚本统一编排，完整目录说明如下：

目录/文件	核心作用	关键细节
src/	核心运行时引擎	网关、智能体、CLI 核心逻辑，调试重点关注此目录 ├─ gateway/：网关服务（通信枢纽、认证、端口管理） ├─ agent/：AI 智能体（对话、任务调度、技能执行） ├─ cli/：命令行解析（gateway/tokens 等指令） ├─ security/：安全认证（令牌校验、权限控制） ├─ state/：状态管理（配置/令牌读取） └─ entry.ts：CLI 总入口
packages/	公共复用包	可独立发布的工具模块（配置校验、日志、API 客户端），其他模块通过 workspace:* 依赖
extensions/	渠道扩展插件	飞书、企业微信等社区贡献的聊天渠道适配器
skills/	内置技能	AI 可执行的官方技能（代码生成、文件操作、定时任务）
scripts/	构建/启动脚本	├─ run-node.mjs：网关/CLI 启动入口（核心文件） ├─ bundle-a2ui.sh：前端 UI 打包脚本 └─ 其他：构建、配置迁移、静态资源拷贝脚本
ui/	前端界面	仪表盘、Control UI 的静态资源和前端代码
dist/	构建输出	TS 编译后的 JS 代码 + sourceMap（调试必备）
.env.example	环境变量示例	可复制为 .env 自定义端口、日志级别等
pnpm-workspace.yaml	Monorepo 配置	定义子包目录（packages/、apps/），实现多包管理

三、解决 Windows 构建脚本兼容问题

v2026.2.26 构建脚本依赖 Bash 环境，Windows 原生终端会提示 bash 未识别，需配置 VS Code 集成终端为 Git Bash：

1. 配置 VS Code 终端为 Git Bash

1. 打开 VS Code → 快捷键 Ctrl+, 打开设置 → 点击右上角 {} 打开 settings.json；
2. 添加以下配置（适配 Git 默认安装路径，自定义路径需修改）：

   {
     "terminal.integrated.defaultProfile.windows": "Git Bash",
     "terminal.integrated.profiles.windows": {
       "Git Bash": {
         "path": "C:\\Program Files\\Git\\bin\\bash.exe",
         "args": ["--login", "-i"],
         "icon": "terminal-bash"
       }
     },
     "terminal.integrated.encoding": "utf8"
   }
   

3. 重启 VS Code，按 Ctrl+Shift+`` 打开终端，提示符显示 MINGW64` 即配置成功。

2. 安装依赖并执行源码构建

# 安装项目所有依赖（Monorepo 多包）
pnpm install
# 编译 TS 源码并生成 sourceMap（调试必备）
pnpm run build

若安装缓慢，可切换淘宝镜像：

pnpm config set registry https://registry.npmmirror.com

若提示 bundle-a2ui.sh 权限不足，执行：

chmod +x scripts/bundle-a2ui.sh

四、配置文件体系详解与网关启动

1. 配置文件路径与核心说明

v2026.2.26 取消源码内独立 config 目录，所有配置持久化到用户目录，按环境隔离存储，核心路径与文件如下：

路径	环境	核心文件	作用说明
C:\Users\nixgn\.openclaw	正式环境	state.json	网关端口、运行状态、令牌关联配置
		tokens.json	认证令牌（网关启动必备，含 gateway/device 等令牌）
		openclaw.json	全局核心配置（默认模型、聊天渠道、日志级别、工作区路径）
		logs/	网关、智能体、渠道运行日志（排查问题核心）
		credentials/	第三方服务凭证（OpenAI API 密钥、飞书机器人配置）
C:\Users\nixgn\.openclaw-dev	开发环境	同正式环境	隔离配置，不影响正式环境数据（启动时加 --dev 触发）

关键说明：

• tokens.json 中的 gateway 令牌是网关启动的核心认证凭证，缺失会提示 unauthorized: gateway token missing；
  
• openclaw.json 可自定义网关端口（默认 18789）、默认 AI 模型（如 gpt-4o）、日志级别（trace/info/warn）等。

2. 初始化配置与令牌生成

首次启动需生成网关认证令牌，确保配置文件完整：

# 交互式初始化配置（生成 openclaw.json/state.json）
node scripts/run-node.mjs onboard
# 生成并绑定网关令牌（写入 tokens.json）
node scripts/run-node.mjs tokens link --scope gateway

3. 启动网关服务

# 正式环境启动网关（读取 C:\Users\nixgn\.openclaw 配置）
node scripts/run-node.mjs gateway
# 开发环境启动（读取 C:\Users\nixgn\.openclaw-dev 配置）
node scripts/run-node.mjs --dev gateway

若提示 gateway token missing，需检查 tokens.json 是否生成，或启动时指定令牌：

node scripts/run-node.mjs gateway --token 你的令牌值（以 clw_ 开头）

五、VS Code 源码调试配置（简化版）

1. 简化版 launch.json 配置（核心可用）

你简化后的配置保留了调试核心要素，足够满足基础调试需求，完整配置如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Debug OpenClaw Gateway",
            "program": "${workspaceFolder}/scripts/run-node.mjs",
            "args": [
                "gateway"
            ],
            "cwd": "${workspaceFolder}"
        }
    ]
}

简化配置说明

• 保留了调试核心三要素：指定启动入口 program、启动参数 args、工作目录 cwd，满足网关基础调试；
• 省略的 env/sourceMaps 等配置，可根据需要补充（如下方「可选增强配置」）。

可选增强配置（按需添加）

若调试时遇到断点未命中、配置读取异常，可补充以下配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Debug OpenClaw Gateway",
            "program": "${workspaceFolder}/scripts/run-node.mjs",
            "args": ["gateway"],
            "cwd": "${workspaceFolder}",
            // 可选：指定配置文件目录，避免读取路径错误
            "env": {
                "OPENCLAW_STATE_DIR": "C:\\Users\\nixgn\\.openclaw"
            },
            // 可选：启用 sourceMap，调试 TS 源码（需先执行 pnpm run build）
            "sourceMaps": true,
            "resolveSourceMapLocations": [
                "${workspaceFolder}/**",
                "!${workspaceFolder}/node_modules/**"
            ],
            // 可选：跳过第三方依赖，只调试自己的源码
            "skipFiles": [
                "<node_internals>/**",
                "${workspaceFolder}/node_modules/**"
            ]
        }
    ]
}

2. 关键断点设置

结合源码目录结构，在以下核心文件添加断点（点击行号左侧），精准定位问题：

文件路径（源码根目录下）	所属模块	调试场景
scripts/run-node.mjs	启动脚本	CLI 参数解析、入口逻辑
src/gateway/server.impl.ts	网关模块	网关启动、端口监听、连接管理
src/security/auth/token-validator.ts	安全模块	令牌校验（解决 token missing 问题）
src/state/storage/file-storage.ts	状态模块	配置文件读取（从 .openclaw 目录加载）
src/agent/core/agent.impl.ts	智能体模块	AI 对话逻辑、技能调用

3. 调试核心快捷键

快捷键（Windows）	功能	调试场景
F5	启动/继续调试	开始调试、断点暂停后继续执行
F10	单步跳过（步进）	逐行执行，不进入函数内部（如快速查看网关启动流程）
F11	单步进入（步入）	进入函数内部（如令牌校验函数）
Shift+F11	单步跳出（步出）	从函数内部返回调用处
F9	切换断点	快速添加/删除断点
Ctrl+F9	临时禁用所有断点	跳过当前调试流程，让网关全速启动
Shift+F5	停止调试	终止调试会话，关闭网关
Ctrl+F10	运行到光标处	精准跳过中间代码，直接到目标行

4. 调试效率技巧

• 条件断点：右键断点 → 「编辑条件」，如 token === undefined（仅令牌缺失时触发，精准定位认证问题）；
• 日志断点：右键断点 → 「编辑日志消息」，如 令牌值：${token}，不暂停代码直接输出变量；
• 变量修改：调试时在「变量」面板双击值，直接修改（如临时替换无效令牌，验证认证逻辑）。

六、常见问题排查

1. 构建报错 bash 未识别

• 确认 Git Bash 安装成功，且 VS Code 终端已切换为 Git Bash；
• 手动指定 Bash 路径执行脚本："C:\\Program Files\\Git\\bin\\bash.exe" scripts/bundle-a2ui.sh。

2. 断点灰色（未命中）

• 执行 pnpm run build 确保 dist/ 目录生成 .map 源映射文件；
• 检查 tsconfig.json 中 sourceMap: true 是否开启；
• 补充简化配置中的 sourceMaps: true 配置。

3. 网关启动提示 token missing

• 执行 node scripts/run-node.mjs tokens link --scope gateway 重新生成令牌；
• 检查 C:\Users\nixgn\.openclaw\tokens.json 中是否存在 gateway 类型令牌；
• 调试时在 src/security/auth/token-validator.ts 断点，查看令牌读取路径是否正确。

4. 配置文件读取失败

• 在调试「监视」面板输入 process.env.OPENCLAW_STATE_DIR，确认配置目录路径正确；
• 补充简化配置中的 env 字段，强制指定 OPENCLAW_STATE_DIR 为 C:\\Users\\nixgn\\.openclaw；
• 检查 .openclaw 目录下的 state.json/openclaw.json 是否存在 JSON 语法错误。

七、总结

OpenClaw v2026.2.26 本地搭建与调试的核心要点：

1. 目录认知：源码采用 Monorepo 架构，核心逻辑在 src/，启动脚本在 scripts/run-node.mjs；
2. 配置体系：无源码内 config 目录，所有配置存储在 C:\Users\nixgn\.openclaw，tokens.json 是网关认证关键；
3. 环境适配：Windows 需配置 Git Bash 解决 Shell 脚本兼容，确保 pnpm run build 正常执行；
4. 调试核心：简化版 launch.json 保留核心配置即可基础调试，按需补充 sourceMaps/env 可提升调试体验，断点聚焦网关启动、令牌校验、配置读取等核心逻辑。