用途：arch-clean 用于在代码库中实施整洁架构原则，重点为六边形模式下的端口/适配器、依赖倒置、用例、实体与可测试性。它通过重构或生成代码来强制关注点分离，使系统更模块化、更易测试。
适用场景：将单体应用重构以提升可维护性、启动需要高可测试性的新项目、在不产生紧耦合的前提下集成外部依赖；也适用于复杂业务逻辑场景（如电商后端），或将遗留代码改造为微服务等现代架构。
主要能力：生成适配器所需的端口接口，实现依赖倒置（如定义 interface UserPort { fetchUser(id: string): User; } 这类契约）；创建编排实体与端口的用例类，促进单一职责；通过将外部库包装为适配器来倒置依赖，例如把直接数据库调用改为端口实现；通过为单元测试组织代码（如在用例中 mock 端口）来强化可测试性；通过静态分析校验架构规则，例如检查内层不依赖外层。
使用方式：可通过 OpenClaw 的 CLI 进行快速重构，或通过 API 用于自动化流水线。先用扫描命令分析代码库，再应用转换。脚本可将输出管道传给 Make 或 Gradle 等构建工具。需指定目标目录与语言（如 TypeScript 或 Java）以避免使用默认值。可在 CI/CD 中作为 pre-commit 钩子强制执行架构。
常用命令/API：使用 OpenClaw CLI，子命令以 arch-clean 为前缀。认证需设置环境变量 $OPENCLAW_API_KEY。生成端口接口：openclaw arch-clean generate-port --name UserPort --methods "fetchUser(id: string)" --lang ts。倒置模块依赖：openclaw arch-clean invert-dep --path src/services --adapter DatabaseAdapter。创建用例：openclaw arch-clean create-usecase --name FetchUser --ports UserPort --entities User。API 端点：POST /api/arch-clean/generate，请求体 { "type": "port", "name": "UserPort", "methods": ["fetchUser(id: string)"] }，需在请求头携带 $OPENCLAW_API_KEY；PUT /api/arch-clean/invert，请求体 { "path": "src/services", "adapter": "DatabaseAdapter" }。配置格式：使用 JSON 文件定义自定义规则，如 .openclaw-arch.json 中 { "layers": { "domain": ["entities", "usecases"], "adapters": ["http", "db"] } }。
集成说明：可将 OpenClaw 作为项目依赖加入（如 npm install openclaw 或通过 Docker 镜像）。设置 $OPENCLAW_API_KEY 用于认证请求。IDE 插件可通过设置配置，如 { "arch-clean": { "defaultLang": "ts", "excludePaths": ["tests/**"] } }。可与 ESLint 等 linter 结合，例如 openclaw arch-clean scan | eslint --fix。需确保代码库采用受支持的结构，如 domain、application、infrastructure 等文件夹，以匹配六边形模式。
错误处理：检查命令输出中的错误；CLI 返回非零退出码并附带 JSON 错误信息，如 { "error": "Dependency not inverted: invalid path" }。API 会返回 HTTP 4xx/5xx 响应，响应体如 { "code": 400, "message": "Missing required field: methods" }。可用 try-catch 包裹调用，例如：try { const response = await fetch('/api/arch-clean/generate', { headers: { 'X-API-Key': process.env.OPENCLAW_API_KEY } }); if (!response.ok) throw new Error(response.statusText); } catch (error) { console.error('Arch error:', error.message); }。对瞬时错误（如网络问题）可用指数退避重试最多 3 次。
使用示例：将简单服务重构为使用端口：对 Node.js 应用运行 openclaw arch-clean invert-dep --path src/userService.js --adapter HttpAdapter，可将直接 HTTP 调用转换为端口，例如把 axios.get('/user') 改为 this.userPort.fetchUser(id)，通过允许 mock 提升可测试性。为业务逻辑生成用例：在 Java 项目中执行 openclaw arch-clean create-usecase --name OrderProcessor --ports PaymentPort --entities Order，会生成 OrderProcessor.java，包含类似 public void process(Order order) { this.paymentPort.charge(order); } 的方法，从而支持依赖注入。
限制：资料未提供具体收费、价格、平台支持范围与效果保证等信息。使用前需确保代码库结构符合受支持的六边形模式，且需配置认证密钥。