OpenClaw OpenHarness 插件深度解析

140+ 工具/19 命令/5 钩子/22 模块

统一插件架构+核心能力拆解+安全治理+踩坑记录

我是atyou, 今天教大家OpenHarness 是 OpenClaw 的一个统一插件，将 140+ 工具、19 个斜杠命令、5 个钩子、22 个模块集成在一个插件包中，覆盖工具调用、代码智能、LSP、治理、Swarm 多 Agent、成本管理、认证、上下文管理等全方位能力。

OpenClaw 生态中，大多数插件只负责单一功能：有的做工具调用，有的做代码分析，有的做成本管理。但 OpenHarness 走了一条不同的路——它把所有能力打包成一个统一插件。

140+ 工具、19 个斜杠命令、5 个钩子、22 个模块，这不是简单的堆砌，而是经过精心设计的分层架构。从底层的工具调用、代码智能，到上层的治理审批、Swarm 多 Agent 编排，再到横向的成本追踪和会话管理，OpenHarness 几乎覆盖了 OpenClaw 的所有核心场景。

今天我将深入源码，逐一拆解这 22 个模块的设计思路、实现细节、踩坑记录，并给出安全建议。

— — — — — — — — — —

一、架构总览

OpenHarness 采用分层架构设计，22 个模块按职责分为 5 层：核心工具层、智能分析层、治理控制层、协作编排层、基础设施层。

Step 1目录结构

OpenHarness 的源码组织清晰，每个模块一个目录，每个目录包含 index.ts 作为入口：

openharness/src/

├── tools/# 19 个核心工具（bash, file, glob, grep, web, skill...）

├── code-intel/# 6 个代码智能工具（符号搜索、定义、引用、依赖、大纲、复杂度）

├── lsp/# 8 个 LSP 工具（定义跳转、引用查找、悬停提示、诊断、重命名...）

├── governance/# 治理模块（权限控制 + before_tool_call/after_tool_call 钩子）

├── swarm/# Swarm 多 Agent 编排（8 个工具，最多 5 并发）

├── cost/# 成本管理（8 个工具，内置 6 种模型定价）

├── auth/# OAuth 认证（3 个工具：status, login, logout）

├── bridge/# 桥接通信（5 个工具：spawn, send, receive, close, list）

├── context/# 上下文管理（5 个工具 + before_prompt_build 钩子）

├── commands/# 19 个斜杠命令（status, summary, compact, usage, cost...）

├── mcp/# MCP 服务器集成

├── memory/# 记忆管理

├── provider/# 模型提供者

├── repl/# REPL 交互

├── session/# 会话管理

├── session-ops/# 会话操作

├── skills/# 技能管理

├── structured-output/# 结构化输出

├── interactive/# 交互式工具

├── gitflow/# Git 工作流

└── github/# GitHub 集成

💡为什么是统一插件而非多个小插件？

统一插件的优势在于模块间可以共享状态（如 cost 追踪、governance 权限），避免跨插件通信的延迟和复杂性。同时用户只需安装一个插件即可获得全部能力。

图1：OpenHarness 分层架构图（作者自绘）

Step 2模块职责矩阵

•tools/ — 19 个基础工具：bash 执行、文件读写、glob/grep 搜索、web 访问、技能调用等

•code-intel/ — 6 个代码分析工具：正则实现的符号搜索、定义查找、引用分析、依赖追踪、大纲生成、复杂度评估

•lsp/ — 8 个 LSP 协议工具：支持 TS/Python/Go/Rust/Java 的语言服务器集成

•governance/ — 权限治理：3 种模式（default/auto/plan）+ 2 个工具调用钩子

•swarm/ — 多 Agent 编排：最多 5 并发 Agent，支持团队创建和任务委派

•cost/ — 成本追踪：内置 6 种模型定价，支持用量统计和快速模式

•auth/ — OAuth PKCE 认证：支持 Anthropic/xAI 的 status/login/logout

•bridge/ — 隔离子会话通信：spawn/send/receive/close/list 5 个工具

•context/ — 上下文管理：发现、压缩、Token 估算、状态查询、指令添加

•commands/ — 19 个斜杠命令：状态、摘要、压缩、用量、成本、技能、钩子、记忆等

— — — — — — — — — —

二、核心工具层：tools/ 模块

tools/ 是 OpenHarness 的基础层，提供 19 个核心工具，覆盖了文件操作、命令执行、搜索、网络访问、技能调用等日常开发所需的所有基础能力。

Step 1bash 工具

bash 工具允许执行 shell 命令，是最强大的工具之一。支持超时控制、工作目录指定、环境变量注入。

bash(command: string, timeout?: number, workdir?: string)

# 示例

bash('ls -la /tmp')

bash('python script.py', timeout=30000, workdir='/path/to/project')

📝踩坑记录 #1：bash 超时处理

症状：长时间运行的命令（如 npm install）可能超时。原因：默认超时时间较短。解决方案：显式传入 timeout 参数，单位为毫秒。对于大项目安装，建议设置 300000（5 分钟）。

Step 2文件读写工具组

包含 file_read, file_write, file_edit 三个工具，分别对应读取、写入、编辑文件。file_edit 支持精确的字符串替换。

file_read(path: string, offset?: number, limit?: number)

file_write(path: string, content: string)

file_edit(path: string, oldString: string, newString: string)

📝踩坑记录 #2：file_edit 的 oldString 匹配失败

症状：file_edit 报错 'oldString not found in content'。原因：oldString 必须与文件内容完全匹配，包括缩进和换行。解决方案：先用 file_read 读取文件，确认 exact content 后再执行 edit。注意 Read 工具输出的行号前缀（如 '1: '）不是文件内容的一部分。

Step 3搜索工具组

glob 和 grep 是两个核心搜索工具。glob 用于文件名模式匹配，grep 用于文件内容正则搜索。

glob(pattern: string, path?: string)

grep(pattern: string, include?: string, path?: string, output_mode?: string)

# glob: 查找所有 TypeScript 文件

glob('**/*.ts')

# grep: 查找所有 console.log 调用

grep('console\\.log', include='*.ts', output_mode='content')

Step 4其他核心工具

•web_fetch — 获取网页内容，支持 markdown/text/html 格式

•skill — 加载和执行 OpenClaw 技能

•config — 读取和修改 OpenClaw 配置

•brief — 生成项目或文件的简要摘要

•todo — 创建和管理待办事项列表

•plan-mode — 切换规划模式，先规划后执行

•tasks — 管理后台任务

•agent — 启动和管理子 Agent

•team — 团队配置管理

•cron — 定时任务管理

•notebook-edit — Jupyter Notebook 单元格编辑

— — — — — — — — — —

三、代码智能层：code-intel/ 模块

code-intel/ 提供 6 个代码分析工具，基于正则表达式实现，支持 TypeScript/JavaScript/Python/Go 四种语言。不依赖 LSP 服务器，启动即用。

Step 1符号搜索

symbol_search 工具使用正则模式在代码库中搜索函数、类、变量等符号定义。支持按语言过滤。

# 搜索所有函数定义

symbol_search(pattern='function\\s+\\w+', lang='typescript')

# 搜索 Python 类定义

symbol_search(pattern='class\\s+\\w+', lang='python')

Step 2定义与引用

find_definitions 和 find_references 分别用于查找符号的定义位置和所有引用位置。

💡与 LSP 的区别

code-intel 基于正则实现，无需启动 LSP 服务器，适合快速搜索。LSP 工具更精确，支持跨文件语义分析，但需要配置语言服务器。两者互补使用。

Step 3依赖分析与复杂度

•dependencies — 分析文件的 import/require 依赖关系

•outline — 生成文件的大纲结构（函数、类、常量等）

•complexity — 评估代码复杂度（圈复杂度、嵌套深度等）

— — — — — — — — — —

四、LSP 层：lsp/ 模块

lsp/ 模块提供 8 个基于 Language Server Protocol 的工具，支持 TypeScript/Python/Go/Rust/Java 五种语言。与 code-intel 的正则方案互补。

Step 1LSP 工具列表

•lsp_goto_definition — 跳转到符号定义位置

•lsp_find_references — 查找符号的所有引用

•lsp_hover — 获取符号的悬停信息（类型、文档）

•lsp_diagnostics — 获取错误、警告、提示

•lsp_rename — 跨文件重命名符号

•lsp_symbols — 获取文档或工作区符号

•lsp_implementation — 查找接口实现

•lsp_completions — 获取代码补全建议

📝踩坑记录 #3：LSP 服务器未启动

症状：调用 LSP 工具返回空结果或错误。原因：对应语言的 LSP 服务器未启动或未正确配置。解决方案：确保已安装对应语言的 LSP 服务器（如 typescript-language-server、pyright、gopls），并在 OpenClaw 配置中启用。

📝踩坑记录 #4：lsp_rename 前未验证

症状：重命名操作失败或部分文件未更新。原因：未先调用 lsp_prepare_rename 验证重命名是否可行。解决方案：始终先调用 lsp_prepare_rename 检查，确认后再执行 lsp_rename。

— — — — — — — — — —

五、治理层：governance/ 模块

governance/ 是 OpenHarness 的安全闸门，提供权限控制和工具调用钩子，确保 AI 的行为在可控范围内。

Step 1三种治理模式

•default — 默认模式：所有工具调用正常执行，无额外限制

•auto — 自动模式：根据工具风险等级自动判断是否需要审批

•plan — 规划模式：所有工具调用需要先规划后执行，适合高风险场景

Step 2工具调用钩子

governance 注册了两个钩子，在工具调用前后进行拦截和审计：

•before_tool_call — 工具调用前拦截：检查权限、验证参数、记录审计日志

•after_tool_call — 工具调用后拦截：检查结果、更新状态、触发后续动作

⚠️安全提醒

在生产环境中，建议至少启用 auto 模式。对于涉及敏感操作（如文件删除、API 调用）的场景，使用 plan 模式。

— — — — — — — — — —

六、Swarm 多 Agent 编排

swarm/ 模块提供 8 个工具，支持多 Agent 并发执行、团队创建、任务委派和消息传递。最多支持 5 个并发 Agent。

Step 1Swarm 工具列表

•swarm_spawn — 启动新的子 Agent

•swarm_status — 查询 Agent 状态

•swarm_list — 列出所有活跃 Agent

•swarm_stop — 停止指定 Agent

•team_create — 创建 Agent 团队

•team_list — 列出所有团队

•send_message — 向 Agent 发送消息

•delegate — 委派任务给 Agent

Step 2并发控制

Swarm 最多支持 5 个并发 Agent。超过限制时会排队等待。这对于并行探索、多文件分析等场景非常有用。

# 并行启动多个 explore agent

task(subagent_type='explore', load_skills=[],

run_in_background=true,

description='Findauth patterns',

prompt='...')

# 最多 5 个并发

# 第 6 个会排队等待

💡最佳实践

每个 explore/librarian agent 的 prompt 应包含 4 个部分：CONTEXT（当前任务背景）、GOAL（需要达成的目标）、DOWNSTREAM（结果将用于什么）、REQUEST（具体搜索指令）。这样 agent 返回的结果才精准可用。

— — — — — — — — — —

七、成本管理：cost/ 模块

cost/ 模块提供 8 个工具，内置 6 种模型的定价信息，支持实时成本追踪、用量统计和快速模式切换。

Step 1cost 工具列表

•cost_track — 追踪当前会话的成本

•cost_summary — 生成成本摘要报告

•model_set/list — 设置/列出当前使用的模型

•effort_set — 设置任务复杂度等级

•passes_set — 设置执行轮次

•usage_stats — 获取用量统计

•fast_mode — 切换快速模式（降低成本）

Step 2内置模型定价

cost 模块内置了 6 种常见模型的定价信息，包括输入/输出 Token 价格。无需额外配置即可开始成本追踪。

💡成本控制技巧

使用 fast_mode 可以显著降低成本，适合简单任务。对于复杂架构决策，保持完整模式以确保质量。effort_set 可以设置任务的复杂度等级，影响 Agent 的探索深度。

— — — — — — — — — —

八、认证与 MCP 集成

auth/ 模块提供 OAuth PKCE 认证支持，mcp/ 模块实现 MCP 协议集成。

Step 1OAuth PKCE 认证

auth/ 支持 Anthropic 和 xAI 的 OAuth PKCE 流程，包含 3 个工具：

•auth_status — 查询当前认证状态

•auth_login — 触发 OAuth 登录流程

•auth_logout — 清除认证信息

📝踩坑记录 #5：OAuth Token 过期

症状：调用 API 时返回 401 Unauthorized。原因：OAuth Token 已过期。解决方案：调用 auth_status 检查状态，如已过期则重新 auth_login。PKCE 流程会自动刷新 Token，但长时间不使用时仍需重新授权。

Step 2MCP 服务器集成

mcp/ 模块允许 OpenHarness 作为 MCP 客户端连接到外部 MCP 服务器，扩展工具能力。支持 tool 调用、resource 读取和 prompt 获取三种操作模式。

— — — — — — — — — —

九、上下文管理与桥接通信

context/ 和 bridge/ 是两个关键的横向模块，分别负责上下文优化和子会话隔离通信。

Step 1上下文管理 (context/)

context/ 提供 5 个工具 + 1 个钩子：

•context_discover — 发现和收集相关上下文信息

•context_compress — 压缩上下文以节省 Token

•estimate_tokens — 估算文本的 Token 数量

•context_status — 查询当前上下文状态

•add_instruction — 添加新的指令到上下文

•before_prompt_build (钩子) — 自动加载 CLAUDE.md 文件到提示词

Step 2桥接通信 (bridge/)

bridge/ 提供隔离的子会话通信机制，包含 5 个工具：

•bridge_spawn — 启动隔离的子会话

•bridge_send — 向子会话发送消息

•bridge_receive — 接收子会话的响应

•bridge_close — 关闭子会话

•bridge_list — 列出活跃的子会话

💡bridge vs swarm 的区别

bridge 提供隔离的子会话通信，适合需要独立上下文的场景。swarm 提供多 Agent 并发执行，适合并行探索。bridge 更轻量，swarm 功能更强大。

— — — — — — — — — —

十、其他模块一览

除了上述核心模块，OpenHarness 还包含多个辅助模块，覆盖记忆管理、模型提供、REPL 交互、会话管理、技能管理、结构化输出、Git 工作流、GitHub 集成等。

Step 1辅助模块列表

•memory/ — 记忆管理：存储和检索项目相关的决策和模式

•provider/ — 模型提供者：管理和切换不同的 LLM 提供商

•repl/ — REPL 交互：提供交互式命令行界面

•session/ — 会话管理：创建、读取、搜索 OpenCode 会话

•session-ops/ — 会话操作：会话级别的运维操作

•skills/ — 技能管理：加载和执行 OpenClaw 技能

•structured-output/ — 结构化输出：确保 Agent 输出符合 JSON Schema

•interactive/ — 交互式工具：需要用户交互的工具

•gitflow/ — Git 工作流：原子提交、分支管理、PR 创建

•github/ — GitHub 集成：Issue、PR、Review 操作

— — — — — — — — — —

十一、19 个斜杠命令

commands/ 模块提供 19 个斜杠命令，覆盖状态查询、会话管理、配置操作、代码操作等多个维度。

Step 1状态与查询类

•/status — 查询当前会话状态

•/summary — 生成会话摘要

•/compact — 压缩会话上下文

•/usage — 查看用量统计

•/cost — 查看成本报告

•/doctor — 诊断环境配置

Step 2配置与管理类

•/skills — 列出可用技能

•/hooks — 查看已注册钩子

•/memory — 管理记忆系统

•/resume — 恢复之前的工作

•/session — 会话管理

•/model — 切换模型

•/permissions — 权限管理

Step 3代码操作类

•/plan — 进入规划模式

•/export — 导出会话内容

•/diff — 查看代码差异

•/branch — 分支管理

•/commit — 创建 Git 提交

•/help — 显示帮助信息

— — — — — — — — — —

十二、常见问题与排错

12.1code-intel 和 LSP 应该用哪个？

症状：不确定何时使用 code-intel 工具，何时使用 LSP 工具。

•快速搜索、不需要精确语义分析 → 用 code-intel（基于正则，无需启动服务器）

•跨文件引用查找、重命名符号、类型信息 → 用 LSP（语义精确，但需配置语言服务器）

•两者互补：code-intel 适合探索阶段，LSP 适合精确操作阶段

12.2Swarm 并发数限制为 5，不够用怎么办？

Swarm 的并发限制是硬限制，但可以通过分批执行来绕过。

•将探索任务分组，每组不超过 5 个 agent

•先启动第一批 5 个，等待完成后启动下一批

•对于大规模代码库分析，使用 librarian agent 替代多个 explore agent

12.3cost 追踪不准确怎么办？

症状：cost_summary 显示的成本与实际账单不符。

•确认 model_set 已正确设置当前使用的模型

•检查内置定价是否为最新版本（模型价格可能调整）

•cost 模块追踪的是 Token 用量，实际账单可能包含其他费用（如 API 调用次数费）

12.4governance 的 auto 模式如何判断风险等级？

auto 模式基于工具类型和操作路径自动判断风险。

•高风险操作：文件删除（rm）、bash 执行危险命令、API 写入调用

•中风险操作：文件编辑、配置修改

•低风险操作：文件读取、搜索、状态查询

•可在 permissions 命令中自定义风险规则

12.5bridge 子会话通信超时怎么办？

症状：bridge_receive 长时间无响应。

•确认子会话已正确 spawn 且未崩溃

•检查 bridge_list 确认会话仍在活跃状态

•设置合理的超时时间，避免无限等待

•如会话已死，调用 bridge_close 清理后重新 spawn

— — — — — — — — — —

十三、安全建议

•bash 工具具有完整的 shell 权限，在治理模块中建议对危险命令（rm -rf、curl | bash 等）设置拦截规则

•OAuth Token 和 API Key 等敏感凭证切勿硬编码在配置文件中，应使用环境变量或凭证管理工具

•governance 模块在生产环境中不应使用 default 模式，至少启用 auto 模式

•Swarm 多 Agent 场景下，每个子 Agent 继承父 Agent 的权限，注意权限隔离

•bridge 子会话通信可能泄露敏感数据，确保通信内容不包含凭证信息

•LSP 工具可能暴露代码库结构，在共享环境中注意访问控制

•定期审查 commands/ 中的 /permissions 配置，确保权限规则与团队安全策略一致

⚠️重要提醒

本文中出现的所有 Token 均为示例或已脱敏处理。请务必使用你自己的 Token，并妥善保管。切勿将敏感凭证提交到 Git 仓库。

— — — — — — — — — —

总结

OpenHarness 是一个设计精良的统一插件，将 140+ 工具、19 个命令、5 个钩子、22 个模块集成在一个包中。它的分层架构使得每个模块职责清晰、互相补充。

关键要点回顾：

•tools/19 个基础工具，覆盖文件、命令、搜索、网络、技能

•code-intel/6 个正则代码分析工具，无需 LSP 服务器

•lsp/8 个 LSP 工具，支持 5 种语言，语义精确

•governance/3 种治理模式 + 2 个工具调用钩子

•swarm/最多 5 并发 Agent，支持团队编排

•cost/内置 6 种模型定价，实时成本追踪

•commands/19 个斜杠命令，覆盖全场景操作

— — — — — — — — — —

我是atyou, 您有什么感兴趣的主题，可以给我留言。让我们一起拥抱AI, 共同进步，享受美好生活。

参考文档：

•OpenClaw 官方文档

•Language Server Protocol 规范

•OAuth 2.0 PKCE 规范 (RFC 7636)

•MCP (Model Context Protocol)

•OpenClaw 安全最佳实践