Doramagic.ai
English

Doramagic 项目包 · 项目说明书

openclaw 项目

你自己的个人 AI 助手，跨操作系统、跨平台，以龙虾方式运行。🦞

OpenClaw Overview & Gateway Architecture

OpenClaw 是一个以主机（host）+ 插件（extension）为基本结构的代理平台，核心网关（Gateway）作为中枢协调运行时，对接模型提供方、IM 通道、记忆/知识库、工作流引擎与可观测性后端。所有官方与社区扩展都集中在 extensions/ 目录下，例如飞书通道插件 @openclaw/feishu、Mattermost 通道插件 @openclaw/ma...

章节 相关页面

继续阅读本节完整说明和来源证据。

OpenClaw 总览与网关架构

平台定位与核心形态

OpenClaw 是一个以主机（host）+ 插件（extension）为基本结构的代理平台，核心网关（Gateway）作为中枢协调运行时，对接模型提供方、IM 通道、记忆/知识库、工作流引擎与可观测性后端。所有官方与社区扩展都集中在 extensions/ 目录下，例如飞书通道插件 @openclaw/feishu、Mattermost 通道插件 @openclaw/mattermost、Tlon/Urbit 通道插件 @openclaw/tlon 等。@openclaw/tlon 的 README 明确指出其为 OpenClaw 的 Tlon/Urbit 通道插件，支持私聊、群组提及与线程回复 资料来源：[extensions/tlon/README.md]。

通道插件以 id 作为唯一标识（例如 feishu、mattermost、tlon），并在 selectionLabel 中携带本地化显示名（如 Feishu/Lark (飞书)）以适配首次安装向导 资料来源：[extensions/feishu/package.json]。通道元数据还包含 order（在引导中出现的顺序）与 exposure（控制是否在「已配置 / 引导 / 文档」三处公开）等字段 资料来源：[extensions/qa-channel/package.json]。

插件元数据与兼容性矩阵

每个扩展在其 package.json 顶层声明 openclaw 字段，作为网关加载时使用的元数据。常见的键及含义如下表所示：

字段用途
extensions网关要加载的入口模块路径数组（TS 源码）
setupEntry首次安装/Setup 向导的入口
setupFeatures引导特性开关，如 legacyStateMigrations
channel通道元数据：id / label / selectionLabel / docsPath / blurb / order / exposure
install安装配置：npmSpec / clawhubSpec / minHostVersion / defaultChoice
compat.pluginApi所需最低插件 API 版本
build.openclawVersion构建目标 OpenClaw 主机版本
release.publishToClawHub / publishToNpm发布目标

例如 @openclaw/codex 声明 minHostVersion: ">=2026.5.1-beta.1"、compat.pluginApi: ">=2026.6.2"、build.openclawVersion: "2026.6.2" 资料来源：[extensions/codex/package.json]；@openclaw/mattermost 则要求 minHostVersion: ">=2026.4.10" 资料来源：[extensions/mattermost/package.json]。这种「最低主机版本 + 插件 API 版本 + 构建版本」的三层约束，使网关在加载扩展前就能精确判定兼容性。

通道、工作流与记忆子系统

网关将能力拆分为多个子系统，通过统一的 RPC / CLI 暴露能力：

  • 模型提供方与监督：@openclaw/codex 通过 @openai/codex 0.135.0 暴露 Codex 管理的 GPT 模型目录与运行时面 资料来源：[extensions/codex/README.md]()；@openclaw/codex-supervisor 基于 @modelcontextprotocol/sdk 1.29.0 负责 Codex app-server 集群的监督 资料来源：[extensions/codex-supervisor/package.json]()。
  • 通道适配：飞书、Mattermost、Tlon 等通道插件把外部 IM/办公平台的事件汇入网关，再以通道原生形式回送 资料来源：[extensions/feishu/package.json](extensions/mattermost/package.json)。
  • 工作流引擎：@openclaw/lobster 提供带类型的可恢复审批管线（typed pipelines、resumable approvals）资料来源：[extensions/lobster/package.json]()；extensions/open-prose 内置 OpenProse 标准库，涵盖 inspector.prose、vm-improver.prose、user-memory.prose 等评估、改进与记忆类程序 资料来源：[extensions/open-prose/skills/prose/lib/README.md]()。
  • 记忆与知识库：@openclaw/memory-wiki 是一个独立的持久化维基编译器，提供 isolated / bridge / unsafe-local 三种模式，并支持 Obsidian 工作流 资料来源：[extensions/memory-wiki/README.md]()。它通过网关 RPC 暴露读写能力，例如 wiki.status、wiki.compile、wiki.search、wiki.get、wiki.obsidian.* 等 资料来源：[extensions/memory-wiki/README.md]()。
  • 本地可观测性：@openclaw/diagnostics-otel 基于 OpenTelemetry 导出指标、追踪与日志（OTLP Proto）资料来源：[extensions/diagnostics-otel/package.json]()。
  • 本地网页抽取：@openclaw/web-readability-plugin 使用 @mozilla/readability 0.6.0 与 linkedom 0.18.12 完成本地 Readability 抽取 资料来源：[extensions/web-readability/package.json]()。

安装、CLI 与开发者面

openclaw CLI 是网关对外的主要交互入口：

  • 安装插件：openclaw plugin add @openclaw/codex 资料来源：[extensions/codex/README.md]()。
  • 维基操作：openclaw wiki init | compile | ingest | lint | search | get | apply 资料来源：[extensions/memory-wiki/README.md]()。
  • 桥接与不安全本地导入：openclaw wiki bridge import、openclaw wiki unsafe-local import。
  • Obsidian CLI 集成：openclaw wiki obsidian status | search | open | command | daily。

CLI 命名空间与 RPC 命名空间保持一致（例如 wiki.*），便于代理以同构方式调用：memory-wiki 暴露 wiki_status、wiki_lint、wiki_apply、wiki_search、wiki_get 五个 Agent 工具 资料来源：[extensions/memory-wiki/README.md]()。@openclaw/plugin-sdk 作为 workspace 私有开发依赖被多个官方扩展共同使用（参见 codex、memory-wiki、lobster 等的 devDependencies），是插件作者对接网关能力的标准面。

社区焦点与平台策略

主线公开策略已切换为「稳定化（Stabilisation Mode）」：核心被锁定以保证质量，新特性请求将被关闭，仅继续接收 Bug 报告（社区贴 #5799）。因此通道与官方集成的扩展（Feishu、Mattermost、Tlon、DingTalk、QQBot 等）成为用户差异化的主要来源。其中飞书通道已切换到由 @m1heng 维护的 @openclaw/feishu 实现，package.json 描述中也明确标注「community maintained by @m1heng」（社区贴 #8650）。DingTalk 等通道虽已实现，但未进入首次安装向导（社区贴 #26534），需在配置层手动启用。

最新发布 openclaw 2026.6.5-beta.2 中，QQBot 在原生投递前会剥离模型推理/思考的脚手架，防止原始 <thinking> 内容泄露到通道回复；MCP 工具结果在 materialize 边界对 resource_link、resource、audio 等非文本/图像块进行强制转换，避免 Anthropic 400 错误与会话污染（来自最新发布说明）。

packages/markdown-core 提供共享的 Markdown IR / 渲染原语，被多个需要处理 Markdown 的扩展复用 资料来源：[packages/markdown-core/package.json]()。

See Also

  • @openclaw/memory-wiki — 持久化维基与 Obsidian 集成
  • 插件与扩展开发指南
  • 通道插件总览（Feishu / Mattermost / Tlon / DingTalk / QQBot）
  • OpenProse 工作流与 .prose 程序
  • OpenTelemetry 诊断导出

来源：https://github.com/openclaw/openclaw / 项目说明书

Channels & Messaging Integrations

OpenClaw 的消息通道是一组独立的插件化 npm 包，每个通道对应一种外部即时通讯或协作平台（如 Slack、Discord、飞书、QQ Bot 等），由 OpenClaw 宿主加载后挂载到统一的网关 (Gateway) 上。package.json 的 openclaw 字段描述了通道元数据，包含 id、label、selectionLabel、blurb、docs...

章节 相关页面

继续阅读本节完整说明和来源证据。

通道与消息集成 (Channels & Messaging Integrations)

概览

OpenClaw 的消息通道是一组独立的插件化 npm 包，每个通道对应一种外部即时通讯或协作平台（如 Slack、Discord、飞书、QQ Bot 等），由 OpenClaw 宿主加载后挂载到统一的网关 (Gateway) 上。package.json 的 openclaw 字段描述了通道元数据，包含 id、label、selectionLabel、blurb、docsPath、commands、configuredState 等子项，宿主据此在 openclaw CLI、设置向导和文档系统中正确呈现通道。

资料来源：extensions/slack/package.json:18-58、extensions/discord/package.json:14-55

通道插件架构

每个通道都遵循相同的 openclaw 扩展描述约定：

  • 入口：extensions: ["./index.ts"] 指定运行时入口；setupEntry: "./setup-entry.ts" 指定首次安装/迁移入口。
  • 兼容性与版本：compat.pluginApi 声明所要求的 OpenClaw 插件 API 最低版本；build.openclawVersion 标记构建时宿主版本。
  • 安装策略：install.npmSpec 与 install.minHostVersion 控制升级和回滚；某些通道（如 Discord、Slack）启用 allowInvalidConfigRecovery 以容忍遗留配置。
  • 配置检测：configuredState.env 通过 anyOf / allOf 列出环境变量名；宿主据此判断通道是否"已配置"。
  • 发布渠道：release.publishToClawHub 与 release.publishToNpm 决定双发布或仅 npm。
  • 命令与技能：commands.nativeCommandsAutoEnabled 与 commands.nativeSkillsAutoEnabled 控制是否在通道内启用原生斜杠命令和技能。
  • 延迟加载：startup.deferConfiguredChannelFullLoadUntilAfterListen（Slack）等字段让已配置的通道在网关开始监听后再做完整加载。

资料来源：extensions/slack/package.json:40-58、extensions/feishu/package.json:32-66

已支持的通道一览

下表汇总了仓库内可见的通道插件核心元数据（截取自各插件的 package.json）：

通道 IDselectionLabel协议/后端关键配置检测备注
slackSlack (Socket Mode)Socket ModeSLACK_APP_TOKEN / SLACK_BOT_TOKEN / SLACK_USER_TOKENmarkdownCapable: true
discordDiscord (Bot API)Bot APIDISCORD_BOT_TOKEN原生命令与技能自动启用
feishu飞书/Lark (飞书)@larksuiteoapi/node-sdk飞书开放平台凭证社区维护者 @m1heng
qqbotQQ Bot (Official API)QQ 官方机器人 API—支持群聊与私信
synology-chatSynology Chat (Webhook)Webhook—连接群晖 Chat
clickclackClickClack自建 token—markdownCapable: true
tlonTlon (Urbit)Urbit—CLI 含 --ship 等参数
qa-channelQA Channel合成 Slack-class仅内部order: 999，不暴露

资料来源：extensions/slack/package.json:18-58、extensions/discord/package.json:14-55、extensions/feishu/package.json:32-66、extensions/qqbot/package.json:14-31、extensions/synology-chat/package.json:16-36、extensions/clickclack/package.json:5-23、extensions/tlon/package.json:6-44、extensions/qa-channel/package.json:4-19

节点应用与通道的协同

虽然节点（macOS / iOS / Android）本身是"更简单的节点"，但它们与通道插件共享同一套网关协议。iOS 应用在 Settings -> Gateway 中呈现状态、服务器与远程地址，并支持配对/鉴权门控；通道插件与节点之间的会话协调通过网关完成。社区长期关注的 #75 议题正是希望补齐 Linux/Windows 节点以匹配 macOS 能力。

资料来源：apps/ios/README.md:21-44

社区关注点

  • 飞书插件替换（#8650，69 评论）：内置的飞书插件被建议切换为 @m1heng/clawdbot-feishu 以获得更丰富的功能。仓库内 extensions/feishu/package.json 已标注由 @m1heng 社区维护，并使用 @larksuiteoapi/node-sdk 1.66.0 作为后端。
  • 钉钉首次安装选项（#26534，78 评论）：要求把 DingTalk 加入首次安装/设置向导的通道列表，与现有通道发现流程对齐。
  • 通道响应清洗（2026.6.5-beta.2）：QQBot 现在会在原生投递前剥离模型推理/思考脚手架，避免 <thinking> 等标记泄露到通道回复中（#89913, #90132）。
  • 稳定期策略（#5799，6 评论）：核心已锁定，新通道类特性请求将被关闭，仅接受缺陷报告，通道插件主要在各自的 npm 包内迭代。

资料来源：extensions/feishu/package.json:1-12、extensions/qqbot/package.json:14-31

常见使用模式

  • 环境变量配置：在 configuredState.env 中声明所有必需变量（如 DISCORD_BOT_TOKEN），宿主会自动检测"已配置"状态。
  • 首次安装脚本：当 setupEntry 与 setupFeatures.legacyStateMigrations: true 同时存在（Discord、Feishu），可平滑迁移旧版配置。
  • 延迟加载：使用 Socket Mode 或需要长连接的通道（如 Slack）可启用 deferConfiguredChannelFullLoadUntilAfterListen，让网关先就绪再加载通道。
  • Markdown 兼容：若通道支持 Markdown 渲染（Slack、ClickClack），建议开启 markdownCapable: true 以让 agent 直接发送结构化内容。
  • 优先级排序：channel.order 字段影响 CLI 添加通道时的显示顺序，例如 feishu: 35、clickclack: 85、tlon: 90、qa-channel: 999。

资料来源：extensions/slack/package.json:18-58、extensions/discord/package.json:14-55、extensions/clickclack/package.json:5-23、extensions/tlon/package.json:6-44、extensions/feishu/package.json:32-66

常见失败模式

  • 环境变量缺失：未设置 DISCORD_BOT_TOKEN 等关键变量时，configuredState 检测失败，通道不会出现在"已配置"列表中。
  • 宿主版本过低：当宿主版本低于 minHostVersion（如 slack: >=2026.5.28、feishu: >=2026.5.29）时，安装会被拒绝或回退。
  • 插件 API 不匹配：compat.pluginApi: ">=2026.6.2" 是当前主流要求；不满足时宿主可能拒绝加载。
  • 遗留配置损坏：通常通过 allowInvalidConfigRecovery: true 修复，必要时手动清理。
  • 节点-通道会话错位：iOS 等节点在后台/前台切换时可能出现死 socket，需结合 wake/resume 与 node/operator session reconnect 协同处理。

资料来源：extensions/slack/package.json:40-58、apps/ios/README.md:21-44

参见 (See Also)

  • OpenProse 工作流与示例
  • Memory Wiki 插件
  • QA 场景与通道
  • iOS 节点调试清单

资料来源：extensions/slack/package.json:18-58、extensions/discord/package.json:14-55

AI Agent Runtime, Models & Tools

本页说明 OpenClaw 项目中AI Agent 运行时（Runtime）、模型（Models）与工具（Tools）三大支柱的组成、职责与协作关系。OpenClaw 采用插件化架构，将模型供给、Agent 编排、知识持久化与渠道分发解耦，由宿主（host）统一装配。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 2.1 Codex 运行时

继续阅读本节完整说明和来源证据。

章节 2.2 GitHub Copilot 运行时

继续阅读本节完整说明和来源证据。

章节 3.1 OpenProse 编排语言

继续阅读本节完整说明和来源证据。

一、定位与总体职责

OpenClaw 的 AI 能力并非由单一进程提供，而是由若干插件式运行时共同构成。每个运行时对应一个或多个 AgentHarness，负责与底层模型 SDK 建立连接、调度模型回合（turn）、处理媒体理解与提示词叠加（prompt overlays）。模型目录与执行表面（surfaces）由对应插件暴露，宿主负责生命周期管理。

资料来源：extensions/codex/README.md:1-9

二、运行时与模型接入

2.1 Codex 运行时

@openclaw/codex 是官方提供的 OpenAI Codex 接入插件，充当 Provider + Harness 的双重角色：

  • 通过 Codex app-server 暴露 Codex 托管的 GPT 模型目录。
  • 提供 Codex 运行时表面，供 OpenClaw agent 执行模型回合、媒体理解与 prompt overlays。
  • 通过 openclaw plugin add @openclaw/codex 安装使用。

资料来源：extensions/codex/README.md:1-9

2.2 GitHub Copilot 运行时

@openclaw/copilot 插件以 @github/copilot-sdk 为底层，通过 JSON-RPC 与 GitHub Copilot CLI 通信，注册一个名为 github-copilot 的 AgentHarness。其 package.json 声明关键依赖：

  • 运行时依赖：@github/copilot-sdk（1.0.0-beta.9）。
  • 开发依赖：@github/copilot、@openclaw/plugin-sdk。
  • 兼容宿主版本：>=2026.5.28，plugin API >=2026.6.2。
  • bundleRuntimeDependencies: false 表示不打包 SDK 副本。

资料来源：extensions/copilot/package.json:1-44

三、Agent 编排与工具

3.1 OpenProse 编排语言

OpenProse 是 OpenClaw 体系内的 Agent 编程语言，专注于多 session 编排、并行执行、循环、错误处理与子 Agent 调度。其 examples/ 目录提供从基础到高级的渐进式样例，涵盖 01–27 多个主题，包括：单 session 调用、并行评审、let/const 绑定、map/filter/reduce 管道、try/catch/retry-backoff 等。

graph LR
  A[用户任务] --> B[OpenProse 程序]
  B --> C{运行时选择}
  C -->|Codex| D[Codex Harness]
  C -->|Copilot| E[Copilot Harness]
  D --> F[模型回合]
  E --> F
  F --> G[工具调用]
  G --> H[渠道/记忆/Markdown 渲染]

资料来源：extensions/open-prose/skills/prose/examples/README.md:1-90

3.2 OpenProse 标准库

extensions/open-prose/skills/prose/lib/ 收录一组生产级 .prose 程序，形成可递归的"改进闭环"：

  • 评估类：inspector.prose、vm-improver.prose、program-improver.prose、cost-analyzer.prose、calibrator.prose、error-forensics.prose。
  • 记忆类：user-memory.prose（跨项目个人记忆）、project-memory.prose（项目级制度记忆）。
  • 闭环：Run → Inspector → VM/Program Improver → PR，再回到 Run。

资料来源：extensions/open-prose/skills/prose/lib/README.md:1-31

3.3 知识持久化：memory-wiki

@openclaw/memory-wiki 是与活动记忆插件解耦的持久化维基编译器。它将持久知识编译成可导航的 Markdown 知识库，配套确定性索引、来源溯源、声明（claims）/证据（evidence）结构化元数据，并可选接入 Obsidian CLI 工作流。

提供三种模式：isolated（默认，私库）、bridge（通过公共 seam 读取活动记忆产物）、unsafe-local（显式同机本地访问，非便携）。资料来源：extensions/memory-wiki/README.md:1-26

四、渲染与交付工具

4.1 Markdown 核心库

@openclaw/markdown-core 是内部共享包，统一管理 Markdown 解析、frontmatter、code-spans、fences、IR（中间表示）、render 渲染以及 render-aware chunking。其 exports 字段细分为 code-spans、fences、frontmatter、ir、render、render-aware-chunking 等子入口，便于上层插件按需引入。资料来源：packages/markdown-core/package.json:1-30

4.2 渠道交付

模型回合的最终交付经由渠道插件完成。多个渠道以统一元数据描述（docsPath、docsLabel、systemImage 等），例如：

渠道插件关键能力
@openclaw/telegram通过 @BotFather 注册的 Bot，markdown 渲染
@openclaw/qqbotQQ 官方 Bot API，支持群聊与私聊
@openclaw/slackSocket Mode，支持 markdown
@openclaw/clickclack自托管聊天，原生 Bot Token

资料来源：extensions/telegram/package.json、extensions/qqbot/package.json、extensions/slack/package.json、extensions/clickclack/package.json

五、社区关注与现状

根据社区讨论（#5799），项目已进入Stabilisation Mode：核心被锁定以提升稳定性，新特性请求将被关闭，仅接受 Bug 报告。这意味着运行时与工具集的设计更倾向于"已稳定接口"，新模型/新工具的接入将以独立插件形式发布，而非侵入核心。资料来源：community context #5799

See Also

  • OpenClaw Codex 插件：extensions/codex/README.md
  • GitHub Copilot 运行时：extensions/copilot/package.json
  • OpenProse 编排语言：extensions/open-prose/skills/prose/examples/README.md
  • 持久化知识库：extensions/memory-wiki/README.md
  • Markdown 渲染核心：packages/markdown-core/package.json

资料来源：extensions/codex/README.md:1-9

Companion Apps, Nodes, Deployment & Extensibility

OpenClaw 通过「配套应用（Companion Apps）+ 节点（Nodes）」与「插件扩展（Extensibility）」两层模型完成部署。官方已提供 macOS、iOS、Android 应用作为「更简单的节点（simpler nodes）」，社区长期呼吁补齐 Linux/Windows（参见 issue 75，109 条评论）。最新一期（2026.6.5-bet...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 扩展的边界与注意事项

继续阅读本节完整说明和来源证据。

概述

OpenClaw 通过「配套应用（Companion Apps）+ 节点（Nodes）」与「插件扩展（Extensibility）」两层模型完成部署。官方已提供 macOS、iOS、Android 应用作为「更简单的节点（simpler nodes）」，社区长期呼吁补齐 Linux/Windows（参见 issue #75，109 条评论）。最新一期（2026.6.5-beta.2）已进入「Stabilisation Mode」，核心被锁定以保证稳定性，新功能请求将被关闭与自动关闭（参见 issue #5799），因此本文聚焦当前稳定形态下的配套节点、插件机制与部署实践。

扩展与插件架构

每个扩展以独立 npm 包存在，并在 package.json 的 openclaw 字段中声明注册入口与兼容性。典型结构包含 extensions（入口模块数组）、install（npm 规格与最低主机版本）、compat（插件 API 契约）、build（构建版本绑定）、release（分发渠道）五个子段。

  • 资料来源：extensions/memory-wiki/package.json:1-20
  • 资料来源：extensions/codex/package.json:1-20
  • 资料来源：extensions/slack/package.json

例如 @openclaw/codex 通过 extensions: ["./index.ts"] 暴露 Codex app-server harness，把 Codex 管理的 GPT 模型目录与运行时接入 Gateway（minHostVersion: ">=2026.5.1-beta.1"）。@openclaw/memory-wiki 同样以 extensions: ["./index.ts"] 注册持久化 wiki 编译器，引入 vault 概念并支持 isolated、bridge、unsafe-local 三种工作模式（默认 isolated）。@openclaw/diffs-language-pack 则是语言增强型扩展：安装后向 Diffs 插件贡献静态查看器资源，但不注册独立的 agent tool，安装后必须重启 Gateway 才生效。

  • 资料来源：extensions/codex/README.md:1-9
  • 资料来源：extensions/memory-wiki/README.md:1-12
  • 资料来源：extensions/diffs-language-pack/README.md:1-15

配套应用与节点（Companion Apps & Nodes）

OpenClaw 将每一类 channel 插件视作一种"节点"形态。下表整理了仓库内可见的官方 channel 插件元信息（来自各 package.json 的 openclaw.channel 字段）：

包名渠道 ID部署形态关键配置 / 备注
@openclaw/telegramtelegramBot API 消息通道TELEGRAM_BOT_TOKEN；markdownCapable: true
@openclaw/slackslackSocket Mode 机器人SLACK_APP_TOKEN / SLACK_BOT_TOKEN / SLACK_USER_TOKEN 任一
@openclaw/synology-chatsynology-chatWebhook 出站选择标签 "Synology Chat (Webhook)"；order: 90
@openclaw/clickclackclickclack自托管聊天markdownCapable: true；order: 85
@openclaw/qa-channelqa-channel合成 Slack-class 传输仅供 qa-lab 自动化场景；order: 999
  • 资料来源：extensions/telegram/package.json
  • 资料来源：extensions/slack/package.json
  • 资料来源：extensions/synology-chat/package.json
  • 资料来源：extensions/clickclack/package.json
  • 资料来源：extensions/qa-channel/package.json

这些 channel 都通过 install.npmSpec 暴露给 openclaw plugin add 解析，并通过 minHostVersion 与主机建立版本契约。社区还要求将 DingTalk 加入首次安装向导（issue #26534）、把内置飞书插件切换到 @m1heng/clawdbot-feishu（issue #8650），本质上都是「first-install channel」扩展诉求。

@openclaw/codex 则走另一条线索：它不是聊天通道，而是把 Codex app-server 接入为"模型提供方 + harness"，让智能体在统一 Gateway 内运行 Codex-backed 推理、媒体理解与 prompt 覆盖。

  • 资料来源：extensions/codex/README.md:1-9
  • 资料来源：extensions/codex/package.json:1-20

部署与扩展实践

部署一条配套节点的标准流程如下：

  1. 安装插件：通过 openclaw plugin add <npmSpec> 安装，例如 openclaw plugin add @openclaw/codex。
  2. 配置环境变量：channel 插件通过 configuredState.env 声明检测集合——Telegram 需要 TELEGRAM_BOT_TOKEN，Slack 接受任一 Slack token。
  3. 在 plugins.entries.<id>.config 下写入配置：memory-wiki 的 vault.path、vaultMode、obsidian.enabled、render.createBacklinks 等都集中放置。
  4. 按需暴露 RPC 与 Agent 工具：memory-wiki 同时注册 Gateway RPC（wiki.status、wiki.search 等）与 Agent 工具（wiki_status、wiki_lint 等），并可作为 corpus=all 时的非排他性 memory 语料补充。
  • 资料来源：extensions/memory-wiki/README.md:1-60
  • 资料来源：extensions/memory-wiki/README.md:60-130
  • 资料来源：extensions/codex/README.md:1-9

扩展的边界与注意事项

  • unsafe-local 模式被刻意标记为实验性、非可移植，仅作为同机本地路径的紧急出口。
  • 扩展应当只通过"公共接缝（public seams）"读取 active memory 插件，避免绑定内部实现。
  • Obsidian CLI 集成要求官方 obsidian CLI 已安装并位于 PATH 中。
  • 安装语言增强包（如 diffs-language-pack）后必须重启 Gateway 才能生效。
  • 在 Stabilisation Mode 下，新功能请求会被自动关闭，建议聚焦缺陷修复与现有插件的运维。
  • 资料来源：extensions/memory-wiki/README.md:60-130
  • 资料来源：extensions/diffs-language-pack/README.md:1-15

See Also

  • 飞书、DingTalk 等多渠道融合的部署建议：参考 channel 插件参考文档与 issue #8650、#26534。
  • OpenProse 标准库与「改进循环」（Inspector → VM/Program Improver）为扩展开发者提供运行时分析工具：extensions/open-prose/skills/prose/lib/README.md。
  • 配套 QA 场景与 qa-lab 扩展：qa/README.md。

来源：https://github.com/openclaw/openclaw / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：[Bug]: installing error message "WSL version output did not include a parseable WSL version"

可能阻塞安装或首次运行。

high 来源证据：[Feature]: [Feature Request] Native payment support for AI agents via HTTP 402

可能影响授权、密钥配置或安全边界。

medium 失败模式：installation: [Bug]: requiresReasoningContentOnAssistantMessages missing from ModelCompatSchema — can't rep...

Developers may fail before the first successful local run: [Bug]: requiresReasoningContentOnAssistantMessages missing from ModelCompatSchema — can't replicate native DeepSeek behavior on custom providers

medium 失败模式：installation: [Feature]: [Feature Request] Native payment support for AI agents via HTTP 402

Developers may fail before the first successful local run: [Feature]: [Feature Request] Native payment support for AI agents via HTTP 402

Pitfall Log / 踩坑日志

项目：openclaw/openclaw

摘要：发现 22 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Bug]: installing error message "WSL version output did not include a parseable WSL version"。

1. 安装坑 · 来源证据：[Bug]: installing error message "WSL version output did not include a parseable WSL version"

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: installing error message "WSL version output did not include a parseable WSL version"
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/openclaw/openclaw/issues/90953 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

2. 安全/权限坑 · 来源证据：[Feature]: [Feature Request] Native payment support for AI agents via HTTP 402

  • 严重度：high
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: [Feature Request] Native payment support for AI agents via HTTP 402
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/openclaw/openclaw/issues/91079 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 失败模式：installation: [Bug]: requiresReasoningContentOnAssistantMessages missing from ModelCompatSchema — can't rep...

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: [Bug]: requiresReasoningContentOnAssistantMessages missing from ModelCompatSchema — can't replicate native DeepSeek behavior on custom providers
  • 对用户的影响：Developers may fail before the first successful local run: [Bug]: requiresReasoningContentOnAssistantMessages missing from ModelCompatSchema — can't replicate native DeepSeek behavior on custom providers
  • 证据：failure_mode_cluster:github_issue | https://github.com/openclaw/openclaw/issues/89660 | [Bug]: requiresReasoningContentOnAssistantMessages missing from ModelCompatSchema — can't replicate native DeepSeek behavior on custom providers

4. 安装坑 · 失败模式：installation: [Feature]: [Feature Request] Native payment support for AI agents via HTTP 402

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: [Feature]: [Feature Request] Native payment support for AI agents via HTTP 402
  • 对用户的影响：Developers may fail before the first successful local run: [Feature]: [Feature Request] Native payment support for AI agents via HTTP 402
  • 证据：failure_mode_cluster:github_issue | https://github.com/openclaw/openclaw/issues/91079 | [Feature]: [Feature Request] Native payment support for AI agents via HTTP 402

5. 安装坑 · 失败模式：installation: openclaw 2026.5.31-beta.2

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.5.31-beta.2
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.5.31-beta.2
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.5.31-beta.2 | openclaw 2026.5.31-beta.2

6. 安装坑 · 失败模式：installation: openclaw 2026.5.31-beta.3

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.5.31-beta.3
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.5.31-beta.3
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.5.31-beta.3 | openclaw 2026.5.31-beta.3

7. 安装坑 · 失败模式：installation: openclaw 2026.5.31-beta.4

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.5.31-beta.4
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.5.31-beta.4
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.5.31-beta.4 | openclaw 2026.5.31-beta.4

8. 安装坑 · 失败模式：installation: openclaw 2026.6.1

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.6.1
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.6.1
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.6.1 | openclaw 2026.6.1

9. 安装坑 · 失败模式：installation: openclaw 2026.6.1-beta.1

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.6.1-beta.1
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.6.1-beta.1
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.6.1-beta.1 | openclaw 2026.6.1-beta.1

10. 安装坑 · 失败模式：installation: openclaw 2026.6.1-beta.2

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.6.1-beta.2
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.6.1-beta.2
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.6.1-beta.2 | openclaw 2026.6.1-beta.2

11. 安装坑 · 失败模式：installation: openclaw 2026.6.1-beta.3

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.6.1-beta.3
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.6.1-beta.3
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.6.1-beta.3 | openclaw 2026.6.1-beta.3

12. 安装坑 · 失败模式：installation: openclaw 2026.6.2-beta.1

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.6.2-beta.1
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.6.2-beta.1
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.6.2-beta.1 | openclaw 2026.6.2-beta.1

13. 安装坑 · 失败模式：installation: openclaw 2026.6.5-beta.1

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.6.5-beta.1
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.6.5-beta.1
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.6.5-beta.1 | openclaw 2026.6.5-beta.1

14. 安装坑 · 失败模式：installation: openclaw 2026.6.5-beta.2

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：Developers should check this installation risk before relying on the project: openclaw 2026.6.5-beta.2
  • 对用户的影响：Upgrade or migration may change expected behavior: openclaw 2026.6.5-beta.2
  • 证据：failure_mode_cluster:github_release | https://github.com/openclaw/openclaw/releases/tag/v2026.6.5-beta.2 | openclaw 2026.6.5-beta.2

15. 能力坑 · 能力判断依赖假设

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：README/documentation is current enough for a first validation pass.
  • 对用户的影响：假设不成立时，用户拿不到承诺的能力。
  • 证据：capability.assumptions | github_repo:1103012935 | https://github.com/openclaw/openclaw | README/documentation is current enough for a first validation pass.

16. 维护坑 · 维护活跃度未知

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：未记录 last_activity_observed。
  • 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
  • 证据：evidence.maintainer_signals | github_repo:1103012935 | https://github.com/openclaw/openclaw | last_activity_observed missing
  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 证据：downstream_validation.risk_items | github_repo:1103012935 | https://github.com/openclaw/openclaw | no_demo; severity=medium

18. 安全/权限坑 · 存在评分风险

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：no_demo
  • 对用户的影响：风险会影响是否适合普通用户安装。
  • 证据：risks.scoring_risks | github_repo:1103012935 | https://github.com/openclaw/openclaw | no_demo; severity=medium

19. 安全/权限坑 · 来源证据：Add OAuth support to the built-in xAI provider

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add OAuth support to the built-in xAI provider
  • 对用户的影响：可能影响授权、密钥配置或安全边界。
  • 证据：community_evidence:github | https://github.com/openclaw/openclaw/issues/91090 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

20. 安全/权限坑 · 来源证据：[Bug]: requiresReasoningContentOnAssistantMessages missing from ModelCompatSchema — can't replicate native DeepSeek beh…

  • 严重度：medium
  • 证据强度：source_linked
  • 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: requiresReasoningContentOnAssistantMessages missing from ModelCompatSchema — can't replicate native DeepSeek behavior on custom providers
  • 对用户的影响：可能阻塞安装或首次运行。
  • 证据：community_evidence:github | https://github.com/openclaw/openclaw/issues/89660 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

21. 维护坑 · issue/PR 响应质量未知

  • 严重度：low
  • 证据强度：source_linked
  • 发现：issue_or_pr_quality=unknown。
  • 对用户的影响：用户无法判断遇到问题后是否有人维护。
  • 证据：evidence.maintainer_signals | github_repo:1103012935 | https://github.com/openclaw/openclaw | issue_or_pr_quality=unknown

22. 维护坑 · 发布节奏不明确

  • 严重度：low
  • 证据强度：source_linked
  • 发现：release_recency=unknown。
  • 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
  • 证据：evidence.maintainer_signals | github_repo:1103012935 | https://github.com/openclaw/openclaw | release_recency=unknown

来源：Doramagic 发现、验证与编译记录