从0到1搭建OpenClaw项目：完整教程及项目配置文件详解

从0到1做出一个小龙虾

前言：最近小龙虾挺火的，但是如果你仅仅只是停留在会用的地步，你的Token会消耗很快，

其实完全可以通过对小龙虾这个项目的细致分析做出一个适合于自己使用的小龙虾，只保留自己需要的部分功能，这样Token消耗会更少。

真心寻找有意对小龙虾项目深入研究的生财圈友。

所谓授人以鱼，不如授人以渔，那些教你如何用小龙虾的教程不过是给你一条鱼，但是你还是不知道如何渔，如果你不满足仅停留在用小龙虾的初级阶段。

对小龙虾底层原理感兴趣，而是有意了解小龙虾背后实现的技术细节，同时搭建属于自己个性化的小龙虾欢迎找鱼丸要我微信。

OpenClaw 完整搭建教程

本教程将带你一步一步，从零开始搭建一个完整的 OpenClaw 项目。

我们会按照正确的依赖顺序，逐个文件进行编写，确保每一步都能正常运行。

11

搭建阶段

508

目录总数

500+

源代码文件

30+

扩展插件

教程目录

1. 阶段 1项目配置文件
2. 阶段 2基础设施模块 (infra/)
3. 阶段 3日志系统 (logging/)
4. 阶段 4终端工具 (terminal/)
5. 阶段 5配置管理 (config/)
6. 阶段 6核心工具函数
7. 阶段 7渠道系统 (channels/)
8. 阶段 8消息渠道实现
9. 阶段 9网关系统 (gateway/)
10. 阶段 10CLI 命令行
11. 阶段 11高级功能与入口

核心原则

编写顺序遵循依赖关系：被依赖的文件先写，依赖别人的文件后写。这样可以确保每完成一个文件，都能立即进行测试。

1

项目配置文件

这是项目的根基，定义项目元信息、依赖、编译选项。没有这些文件，项目无法初始化。

1. 1package.json✅ 已完成
2. 项目的身份证，定义名称、版本、依赖、脚本命令
3. 依赖：无（第一个文件）
4. 关键字段说明：
5. • name: 项目名称 "openclaw-clone"
6. • type: "module" 启用 ES Module
7. • engines: Node.js >= 22.12.0
8. • packageManager: pnpm@10.23.0
9. • scripts: build, dev, test, lint, gateway 等命令
10. • dependencies: 核心依赖（SDK、框架、工具库）
11. • devDependencies: 开发依赖（TypeScript、测试、lint）
12. 📄 查看完整代码

1. 2tsconfig.json✅ 已完成
2. TypeScript 编译器配置，定义如何将 TS 编译成 JS
3. 依赖：package.json（需要先有项目）
4. 关键配置说明：
5. • target: ES2023（现代 JavaScript）
6. • module: NodeNext（ESM 模块系统）
7. • strict: true（严格类型检查）
8. • outDir: ./dist（输出目录）
9. • rootDir: ./src（源码目录）
10. 📄 查看完整代码

1. 3pnpm-workspace.yaml✅ 已完成
2. pnpm 工作区配置，定义 monorepo 结构
3. 依赖：package.json
4. 📄 查看完整代码

1. 4.env.example✅ 已完成
2. 环境变量模板，告诉用户需要配置哪些环境变量
3. 依赖：无
4. 包含配置项：
5. • AI 提供商 API Keys（Anthropic、OpenAI、Google）
6. • 消息渠道配置（Telegram、Discord、Slack、WhatsApp）
7. • 网关配置（端口、绑定地址）
8. • 可选服务（ElevenLabs、Deepgram）
9. 5.npmrc✅ 已完成
10. npm/pnpm 配置文件
11. 依赖：无
12. 📄 查看完整代码

🎉 阶段 1 完成！

所有项目配置文件已创建完成。现在可以运行 pnpm install 安装依赖。

2

基础设施模块 (src/infra/)

这是整个项目的地基！所有其他模块都会依赖这里的工具函数。必须最先编写。

重要提示

infra/ 目录下的文件是最底层的工具，它们只依赖 Node.js 内置模块，不依赖项目中的其他代码。

1. 1src/infra/errors.ts✅ 已完成
2. 错误处理工具函数
3. 依赖：无（纯工具函数）
4. 导出：ErrorCode枚举, AppError类, extractErrorCode(), formatErrorMessage(), assert(), ensureValue()
5. 2src/infra/env.ts✅ 已完成
6. 环境变量处理工具
7. 依赖：无
8. 导出：isTruthyEnvValue(), getEnv(), getEnvBool(), isDevelopment(), isVerbose(), requireEnv()
9. 3src/infra/dotenv.ts✅ 已完成
10. .env 文件加载器
11. 依赖：无（纯文件操作）
12. 导出：parseEnvContent(), loadEnvFile(), loadEnvFiles(), initDotenv()
13. 4src/infra/runtime-guard.ts✅ 已完成
14. Node.js 版本检查
15. 依赖：无
16. 导出：checkNodeVersion(), assertNodeVersion(), getRuntimeInfo(), initRuntimeGuard()
17. 5src/infra/warnings.ts✅ 已完成
18. 进程警告过滤器
19. 依赖：无
20. 导出：installWarningFilter(), suppressWarningType(), allowWarningType(), emitWarning()
21. 6src/infra/is-main.ts✅ 已完成
22. 判断模块是否为入口文件
23. 依赖：无
24. 导出：isMain(), runIfMain() - 用于ESM模块判断是否为直接运行
25. 7src/infra/path-env.ts✅ 已完成
26. PATH 环境变量管理
27. 依赖：无
28. 导出：getPathEntries(), prependPath(), appendPath(), removePath(), isInPath()
29. 8src/infra/ports.ts✅ 已完成
30. 端口可用性检查
31. 依赖：无
32. 导出：isPortAvailable(), findAvailablePort(), arePortsAvailable(), DEFAULT_GATEWAY_PORT
33. 9src/infra/backoff.ts✅ 已完成
34. 指数退避算法（重试机制）
35. 依赖：无
36. 导出：calculateBackoff(), sleep(), sleepWithBackoff(), retry(), withRetry()
37. 10src/infra/dedupe.ts✅ 已完成
38. 去重工具
39. 依赖：无
40. 导出：dedupe(), dedupeBy(), createDeduper(), createAsyncDeduper(), throttle(), debounce()
41. 11src/infra/binaries.ts✅ 已完成
42. 二进制文件路径管理
43. 依赖：无
44. 导出：getProjectRoot(), getBinaryName(), findBinary(), getBinaryPath(), getNodeModulesBin()
45. 12src/infra/archive.ts✅ 已完成
46. 压缩文件处理（tar, zip, gz）
47. 依赖：无
48. 导出：detectArchiveType(), gunzipFile(), gzipFile(), isArchive(), getExtractedPath()
49. 13src/infra/unhandled-rejections.ts✅ 已完成
50. 未捕获异常处理
51. 依赖：errors.ts
52. 导出：installErrorHandlers(), uninstallErrorHandlers(), wrapMain(), createErrorBoundary()
53. 14src/infra/index.ts✅ 已完成
54. infra 模块聚合导出
55. 依赖：以上所有 infra 文件
56. 功能：统一导出所有infra模块，提供initInfra()初始化函数

🎉 阶段 2 完成！

所有基础设施模块已创建完成（14个文件）。这些工具函数将被整个项目使用。

3

日志系统 (src/logging/)

日志系统是调试和监控的基础，几乎所有模块都会用到它。

1. 1src/logging/levels.ts✅ 已完成
2. 日志级别定义（debug, info, warn, error）
3. 依赖：无
4. 导出：LogLevel枚举, parseLogLevel(), shouldLog(), formatLogLevel()
5. 2src/logging/console.ts✅ 已完成
6. 控制台输出管理
7. 依赖：levels.ts
8. 导出：configureConsole(), writeToConsole(), formatLogMessage(), clearLine()
9. 3src/logging/subsystem.ts✅ 已完成
10. 子系统日志创建器
11. 依赖：levels.ts, console.ts
12. 导出：createSubsystemLogger(), getSubsystemLogger() - 创建如 [Gateway], [Telegram] 前缀日志器
13. 4src/logging/logger.ts✅ 已完成
14. 主日志记录器
15. 依赖：levels.ts, console.ts, subsystem.ts
16. 导出：Logger类, getLogger(), configureLogger(), debug(), info(), warn(), error()
17. 5src/logging/index.ts✅ 已完成
18. logging 模块聚合导出
19. 依赖：以上所有 logging 文件
20. 导出：所有日志功能 + initLogging() + loggers对象（预配置子系统日志器）

🎉 阶段 3 完成！

日志系统已创建完成（5个文件）。现在可以在任何模块中使用 debug/info/warn/error 记录日志。

4

终端工具 (src/terminal/)

终端输出的美化工具，包括颜色、进度条、表格等。

1. 1src/terminal/palette.ts✅ 已完成
2. 调色板定义（颜色常量）
3. 依赖：无
4. 导出：ANSI色码, palette语义色, colors着色函数, stripAnsi(), shouldUseColors()
5. 2src/terminal/theme.ts✅ 已完成
6. 输出主题样式
7. 依赖：palette.ts
8. 导出：symbols符号集, styled样式函数, box(), indent(), truncate(), center()
9. 3src/terminal/progress-line.ts✅ 已完成
10. 进度条和旋转指示器
11. 依赖：theme.ts
12. 导出：createSpinner(), createProgressBar(), withSpinner(), startProgress()
13. 4src/terminal/table.ts✅ 已完成
14. 表格输出
15. 依赖：theme.ts, palette.ts
16. 导出：table(), simpleTable(), keyValueTable(), printTable()
17. 5src/terminal/index.ts✅ 已完成
18. terminal 模块聚合导出
19. 依赖：以上所有 terminal 文件
20. 导出：所有终端功能 + initTerminal() + terminal便捷对象

🎉 阶段 4 完成！

终端工具模块已创建完成（5个文件）。现在可以使用彩色输出、进度条和表格显示。

5

配置管理 (src/config/)

配置系统负责读取、验证、存储用户配置。这是连接用户设置和程序逻辑的桥梁。

1. 1src/config/paths.ts✅ 已完成
2. 路径常量（配置目录、会话目录等）
3. 依赖：无
4. 导出：getConfigDir(), getSessionsDir(), ensureConfigDirs(), paths对象
5. 2src/config/types.ts✅ 已完成
6. TypeScript 类型定义
7. 依赖：无
8. 导出：OpenClawConfig, ChannelConfig, AgentConfig, AIProviderConfig 等接口
9. 3src/config/zod-schema.ts✅ 已完成
10. Zod 验证 Schema
11. 依赖：zod库
12. 导出：OpenClawConfigSchema, ChannelConfigSchema 等验证模式
13. 4src/config/io.ts✅ 已完成
14. 配置文件读写
15. 依赖：paths.ts, zod-schema.ts
16. 导出：loadConfig(), saveConfig(), mergeEnvConfig(), createDefaultConfig()
17. 5src/config/validation.ts✅ 已完成
18. 配置验证逻辑
19. 依赖：zod-schema.ts
20. 导出：validateConfig(), validateChannel(), validateEnvironment()
21. 6src/config/sessions/main-session.ts✅ 已完成
22. 主会话管理
23. 依赖：paths.ts
24. 导出：SessionManager类, createSession(), saveSession(), addMessage()
25. 7src/config/config.ts✅ 已完成
26. 配置模块聚合
27. 依赖：io.ts, validation.ts, paths.ts
28. 导出：getConfig(), setConfig(), getChannels(), getAgents(), config对象
29. 8src/config/index.ts✅ 已完成
30. config 模块导出
31. 依赖：所有config文件
32. 导出：所有配置功能的统一入口

🎉 阶段 5 完成！

配置管理模块已创建完成（8个文件）。现在可以读取、验证和管理应用配置。

6

核心工具函数

项目级别的通用工具函数和全局状态管理。

1. 1src/types/index.ts✅ 已完成
2. 全局类型定义
3. 依赖：无
4. 导出：Result类型, ok(), err(), Message, Sender, ToolCall等通用类型
5. 2src/utils/index.ts✅ 已完成
6. 通用工具函数
7. 依赖：无
8. 导出：sleep(), uuid(), hash(), deepClone(), groupBy(), formatBytes()等
9. 3src/globals.ts✅ 已完成
10. 全局状态（verbose, yes, debug 标志）
11. 依赖：无
12. 导出：isVerbose(), setVerbose(), isDebug(), globals对象
13. 4src/runtime.ts✅ 已完成
14. 运行时环境定义
15. 依赖：types/
16. 导出：Runtime接口, ServiceRegistry, registerShutdownHandlers()
17. 5src/version.ts✅ 已完成
18. 版本信息管理
19. 依赖：package.json
20. 导出：getVersion(), getVersionInfo(), printVersion(), version对象
21. 6src/logger.ts✅ 已完成
22. 便捷日志函数
23. 依赖：globals.ts, logging/
24. 导出：logInfo(), logWarn(), logError(), logSuccess(), log对象

🎉 阶段 6 完成！

核心工具函数模块已创建完成（6个文件）。现在项目有了完整的基础设施支持。

7

渠道系统 (src/channels/)

渠道系统是消息路由的核心，定义了所有渠道共用的接口和逻辑。

1. 1src/channels/types.ts✅ 已完成
2. 渠道类型定义
3. 依赖：无
4. 导出：Channel接口, ChannelMessage, ChannelSender, ChannelHandler等
5. 2src/channels/registry.ts✅ 已完成
6. 渠道注册表
7. 依赖：types.ts
8. 导出：channelRegistry, registerChannelFactory(), getChannel(), getAllChannels()
9. 3src/channels/session.ts✅ 已完成
10. 渠道会话管理
11. 依赖：types.ts
12. 导出：ChannelSessionManager, ConversationSession, sessionManager
13. 4src/channels/allowlists/index.ts✅ 已完成
14. 白名单管理
15. 依赖：types.ts
16. 导出：Allowlist类, allowlistRegistry, AllowlistConfig
17. 5src/channels/sender-identity.ts✅ 已完成
18. 发送者身份解析
19. 依赖：types.ts
20. 导出：SenderIdentityManager, UnifiedIdentity, identityManager
21. 6src/channels/typing.ts✅ 已完成
22. 输入指示器
23. 依赖：types.ts
24. 导出：TypingIndicator, typingIndicator, withTyping()
25. 7src/channels/index.ts✅ 已完成
26. channels 模块导出
27. 依赖：以上所有 channels 文件
28. 导出：所有渠道功能 + initChannels(), connectAllChannels()

🎉 阶段 7 完成！

渠道系统核心模块已创建完成（7个文件）。现在有了统一的渠道抽象层。

8

消息渠道实现

每个消息平台的具体实现。每个渠道都是独立的模块，可以单独开发和测试。

提示

以下渠道可以并行开发，它们之间没有依赖关系。建议先实现一个作为模板，然后复制到其他渠道。

1. 1src/telegram/✅ 已完成
2. Telegram 机器人集成
3. 依赖：channels/, logging/, config/
4. 文件：types.ts, bot.ts, index.ts（使用 grammy 库）
5. 2src/discord/✅ 已完成
6. Discord 机器人集成
7. 依赖：channels/, logging/, config/
8. 文件：types.ts, client.ts, index.ts（使用 discord.js REST API）
9. 3src/slack/✅ 已完成
10. Slack 集成
11. 依赖：channels/, logging/, config/
12. 文件：types.ts, client.ts, index.ts（使用 @slack/bolt）
13. 4src/signal/✅ 已完成
14. Signal 协议集成
15. 依赖：channels/, logging/, config/
16. 文件：index.ts（使用 signal-cli）
17. 5src/imessage/✅ 已完成
18. iMessage 集成（macOS）
19. 依赖：channels/, logging/, config/
20. 文件：index.ts（使用 AppleScript + Messages.app）
21. 6src/whatsapp/✅ 已完成
22. WhatsApp Web 集成（Baileys）
23. 依赖：channels/, logging/, config/
24. 文件：index.ts（使用 Baileys 库）
25. 7src/line/✅ 已完成
26. LINE 集成
27. 依赖：channels/, logging/, config/
28. 文件：index.ts（使用 LINE Messaging API）

🎉 阶段 8 完成！

所有7个消息渠道实现已创建完成（13个文件）。每个渠道都实现了统一的Channel接口。

9

网关系统 (src/gateway/)

网关是整个系统的控制中心，负责管理所有渠道、会话和消息路由。

1. 1src/gateway/protocol/schema/✅ 已完成
2. WebSocket 协议定义
3. 依赖：无
4. 文件：messages.ts（消息类型）, events.ts（事件类型）, index.ts（协议常量）
5. 2src/gateway/auth.ts✅ 已完成
6. 认证管理
7. 依赖：crypto
8. 导出：GatewayAuth类, TokenStore接口, generateToken(), validateToken()
9. 3src/gateway/client.ts✅ 已完成
10. 网关客户端
11. 依赖：protocol/, WebSocket
12. 导出：GatewayClient类, connect(), subscribe(), sendMessage()
13. 4src/gateway/server/✅ 已完成
14. WebSocket + HTTP 服务器
15. 依赖：ws库, protocol/, auth.ts
16. 文件：ws-server.ts（WebSocket服务）, http-server.ts（REST API）, index.ts
17. 5src/gateway/boot.ts✅ 已完成
18. 网关启动逻辑
19. 依赖：server/, auth.ts, channels/
20. 导出：Gateway类, bootGateway(), createGateway(), 提供HTTP API端点
21. 6src/gateway/index.ts✅ 已完成
22. gateway 模块导出
23. 依赖：以上所有 gateway 文件
24. 导出：所有网关功能 + startGateway()快捷启动函数

🎉 阶段 9 完成！

网关系统已创建完成（10个文件）。现在可以通过WebSocket和REST API管理所有消息渠道。

10

CLI 命令行 (src/cli/)

命令行界面是用户与程序交互的入口。这里定义所有 CLI 命令。

1. 1src/cli/argv.ts✅ 已完成
2. 命令行参数解析
3. 依赖：无
4. 导出：parseArgs(), validateArgs(), generateHelp(), commonArgs
5. 2src/cli/prompt.ts✅ 已完成
6. 用户输入提示
7. 依赖：readline
8. 导出：promptText(), promptConfirm(), promptPassword(), promptSelect()
9. 3src/cli/progress.ts✅ 已完成
10. 进度显示
11. 依赖：无
12. 导出：Spinner类, ProgressBar类, StepIndicator类, withSpinner()
13. 4src/cli/deps.ts✅ 已完成
14. 依赖注入容器
15. 依赖：channels/types
16. 导出：CliDeps接口, createDefaultDeps(), getDeps(), setDeps()
17. 5src/cli/program.ts✅ 已完成
18. CLI 程序构建
19. 依赖：commander库, deps.ts
20. 导出：buildProgram(), createProgram(), 添加gateway/config/channel命令
21. 6src/cli/gateway-cli.ts✅ 已完成
22. gateway 命令
23. 依赖：deps.ts, gateway/, progress.ts
24. 导出：startGatewayCommand(), statusGatewayCommand()
25. 7src/cli/run-main.ts✅ 已完成
26. CLI 主入口
27. 依赖：program.ts, infra/
28. 导出：runMain(), main() - 应用程序启动入口
29. 8src/cli/index.ts✅ 已完成
30. CLI 模块导出
31. 依赖：以上所有cli文件
32. 导出：所有CLI功能的统一入口

🎉 阶段 10 完成！

CLI命令行模块已创建完成（8个文件）。现在可以通过命令行启动和管理网关。

11

高级功能与入口

最后阶段：AI 代理、浏览器控制、媒体处理等高级功能，以及程序入口文件。

1. 1src/agents/✅ 已完成
2. AI 代理系统
3. 依赖：providers/
4. 文件：types.ts（Agent接口、Message、ToolCall）, agent.ts（BaseAgent类）, index.ts
5. 2src/providers/✅ 已完成
6. AI 提供商（Claude, GPT, Gemini）
7. 依赖：agents/types
8. 文件：types.ts（Provider接口、MODELS）, anthropic.ts（Claude实现）, index.ts
9. 3src/browser/✅ 已完成
10. 浏览器自动化（Playwright接口）
11. 依赖：无
12. 文件：index.ts - BrowserManager, BrowserController接口, takeScreenshot()
13. 4src/media/✅ 已完成
14. 媒体处理
15. 依赖：无
16. 文件：index.ts - getMediaInfo(), MediaProcessor, formatFileSize()
17. 5src/wizard/✅ 已完成
18. 安装向导
19. 依赖：cli/prompt, cli/progress
20. 文件：index.ts - runWizard()交互式配置, quickSetup()快速配置
21. 6src/entry.ts✅ 已完成
22. 程序入口点
23. 依赖：infra/, cli/run-main
24. 导出：entry(), start() - 初始化运行时并启动CLI
25. 7src/index.ts✅ 已完成
26. 库导出入口
27. 依赖：所有模块
28. 导出：所有公共API + openclaw()快捷启动函数
29. 8openclaw.mjs✅ 已完成
30. 可执行脚本入口
31. 依赖：dist/entry.js
32. 用户运行 `openclaw` 命令时的入口，加载编译后的entry.js

🎉 阶段 11 完成！

高级功能与入口文件已创建完成（11个文件）。整个项目搭建完成！

!

依赖关系总览

┌─────────────────────────────────────────────────────────┐

│ Node.js 内置模块 (fs, path, etc.) │

└────────────────────────┬────────────────────────────────┘

│

┌────────────┴────────────┐

▼ ▼

┌───────────────┐ ┌───────────────┐

│ infra/*.ts │ │ types/*.ts │

│ (基础工具) │ │ (类型定义) │

└───────┬───────┘ └───────┬───────┘

│ │

└────────────┬────────────┘

▼

┌───────────────────┐

│ logging/*.ts │

│ (日志系统) │

└─────────┬─────────┘

│

┌─────────┴─────────┐

▼ ▼

┌─────────────┐ ┌─────────────┐

│ terminal/* │ │ config/* │

│ (终端工具) │ │ (配置管理) │

└──────┬──────┘ └──────┬──────┘

│ │

└─────────┬─────────┘

▼

┌───────────────────┐

│ channels/*.ts │

│ (渠道系统) │

└─────────┬─────────┘

│

┌──────────────────┼──────────────────┐

▼ ▼ ▼

┌────────┐ ┌──────────┐ ┌──────────┐

│telegram│ │ discord │ │ slack │ ...

└───┬────┘ └────┬─────┘ └────┬─────┘

│ │ │

└────────────────┼──────────────────┘

▼

┌───────────────────┐

│ gateway/*.ts │

│ (网关系统) │

└─────────┬─────────┘

│

┌─────────┴─────────┐

▼ ▼

┌─────────────┐ ┌─────────────┐

│ cli/*.ts │ │ agents/* │

│ (命令行) │ │ (AI代理) │

└──────┬──────┘ └─────────────┘

│

▼

┌─────────────┐

│ entry.ts │

│ (入口点) │

└──────┬──────┘

│

▼

┌─────────────┐

│openclaw.mjs │

│ (可执行文件) │

└─────────────┘

🎉🎉🎉 恭喜！小龙虾搭建完成！🎉🎉🎉

所有 11个阶段 的代码文件已全部创建完成！

项目统计：

1. 配置文件：5 个
2. 基础设施模块 (infra/)：14 个
3. 日志系统 (logging/)：5 个
4. 终端工具 (terminal/)：5 个
5. 配置管理 (config/)：8 个
6. 核心工具：6 个
7. 渠道系统 (channels/)：7 个
8. 渠道实现 (telegram/discord/slack等)：13 个
9. 网关系统 (gateway/)：10 个
10. 命令行 (cli/)：8 个
11. 高级功能与入口：11 个

下一步：

1. 运行 pnpm install 安装依赖
2. 运行 pnpm build 编译 TypeScript
3. 配置 .env 文件（复制 .env.example）
4. 运行 pnpm gateway 启动网关服务

OpenClaw - Personal AI Assistant Platform

https://github.com/openclaw/openclaw

教程版本 v1.0 | 2026-02-26