1. Agent Finder 热潮下企业 Agent 治理的真实缺口在哪Agent Finder 和 ARD 规范的出现把一个问题摆到了台面上当企业里同时跑着几十个 Agent、上百个 MCP Server、各种 Skills 和内部 API 时谁来管这些能力不是缺 Agent而是缺一个能回答“能力在哪里、该用哪个、能不能信”的运行层。这篇文章就以 MateClaw 为参照拆解能力目录和运行闭环怎么落地并给出可复制的目录结构配置和闭环验证动作。先说清楚几个概念。Agent Finder 是 GitHub 给 Copilot 做的一个能力发现入口让 Copilot 能从公共或私有目录里找到合适的 AI 资源。ARDAgentic Resource Discovery是 Google 同期发布的开放规范核心是让 Agent 能可靠地回答三个问题能力在哪里当前任务该用哪个能力这个能力是否可信、安全、可连接MateClaw 则是一个企业 Agent Harness 项目它把 Tools、Skills、MCP、ACP 统一收进能力层再通过员工级绑定和 Tool Guard 做运行治理。适合谁看如果你是企业里的 Java 或平台开发者正在被“工具越接越多、prompt 越写越长、权限越放越大”折磨或者你正在评估怎么把 Agent 从 demo 推进到生产这篇就是写给你的。我试过把十几个 MCP Server 直接塞进一个 Agent 的上下文结果模型开始乱选工具成本翻了三倍排查了两天才定位到是工具描述互相干扰。这个坑能力目录能帮你绕过去。核心检索词先明确Agent Finder 是什么、能做什么、适合谁。它是一个能力发现机制能帮 Agent 在运行时按任务找到合适的工具或资源适合任何 Agent 数量超过个位数的团队。MateClaw 则是把这种发现能力收敛到企业内部做成可注册、可绑定、可审批、可审计的运行闭环。下面按“问题场景 → 前置准备 → 可复制配置 → 验证请求 → 常见错排查 → 接入通道”的顺序展开每一步都给可跟做的命令和配置。2. MateClaw 能力目录前置准备ARD 描述与目录注册怎么落地在动手配目录之前得先理解 ARD 描述文件长什么样。ARD 的核心是一个 JSON 结构用来描述一个 agentic resource 的元数据它是什么、能做什么、怎么调用、需要什么权限、由谁维护。MateClaw 内部把这套思路映射成了自己的能力注册逻辑Tools、Skills、MCP、ACP 都进同一个能力层。前置准备分三步环境、目录结构、能力描述文件。环境方面你需要一个能跑 MateClaw 的机器Node.js 18 或 Docker 都行。我建议先用 Docker 起一个本地实例避免污染开发机。命令如下docker run -d \ --name mateclaw-local \ -p 8080:8080 \ -v $(pwd)/mateclaw-data:/data \ -e MATE_CLAW_MODEdev \ mateaix/mateclaw:latest启动后访问http://localhost:8080能看到 Web Console 就说明环境 OK。这一步不涉及任何外部网络配置纯本地。目录结构是能力目录的骨架。MateClaw 的能力目录建议按“资源类型 / 维护团队 / 版本”三层组织这样后续做权限绑定和审计时能直接按路径过滤。一个可复制的目录结构如下capabilities/ ├── tools/ │ ├── platform-team/ │ │ ├── db-query-readonly.json │ │ └── log-search.json │ └──>{ id: tool.db-query-readonly, type: tool, name: 只读数据库查询, description: 对生产库执行只读 SELECT 查询返回结果集禁止任何写操作, version: 1.2.0, maintainer: platform-team, securityLabels: [read-only, database, requires-approval], inputSchema: { type: object, properties: { sql: { type: string, description: 只允许 SELECT 语句 }, limit: { type: integer, default: 100 } }, required: [sql] }, outputSchema: { type: object, properties: { rows: { type: array }, rowCount: { type: integer } } }, endpoint: mcp://internal/db-query, timeoutMs: 15000 }这个文件就是 ARD 思路在 MateClaw 里的落地形态。securityLabels是关键它决定了这个能力被绑到员工后调用时是否触发 Tool Guard 审批。read-only和requires-approval两个标签叠加意味着即使是只读查询高风险场景下也要走审批流。能力描述写完后要注册进 MateClaw 的目录。MateClaw 支持从目录批量导入命令如下curl -X POST http://localhost:8080/api/capabilities/import \ -H Content-Type: application/json \ -d { source: local, path: /data/capabilities, mode: merge, conflictPolicy: version-wins }mode: merge表示增量合并conflictPolicy: version-wins表示同 id 能力按版本号高者覆盖。导入成功后Web Console 的 Capability Catalog 页面会列出所有已注册能力按类型和维护团队分组。这一步做完你就有了一份企业内部的“能力目录”。它和 ARD 的区别在于ARD 面向跨组织开放发现MateClaw 当前面向企业内部收敛。但两者的元数据模型是相通的后续如果 MateClaw 支持导出ai-catalog.json就能直接对接 ARD 生态。前置准备里还有一个容易忽略的点能力描述里的description字段质量直接决定 Agent 选能力的准确率。我踩过的坑是早期把描述写成“查询数据库”结果 Agent 在需要查日志时也选了这个工具。后来改成“对生产库执行只读 SELECT 查询返回结果集禁止任何写操作”误选率明显下降。描述要写清楚“做什么、不做什么、边界在哪”。3. 可复制配置员工绑定与运行闭环的 settings 片段能力目录建好后下一步是把能力绑到具体的数字员工身上并配置运行闭环。MateClaw 的核心设计是 per-employee binding也就是每个员工只拿到自己职责范围内的能力而不是全局裸奔。先看员工配置。MateClaw 的员工定义是一个 YAML 文件放在employees/目录下。以客服助理为例# employees/cs-assistant.yaml id: employee.cs-assistant name: 客服助理 role: 处理退款、订单查询、政策咨询 goal: 在权限范围内快速响应客户问题高风险操作转人工 backstory: 你是一名有三年经验的电商客服熟悉退款政策但不具备财务操作权限 model: primary: claude-sonnet fallback: [gpt-4o-mini, qwen-plus] failoverPolicy: on-error capabilities: bind: - skill.cs-team.refund-policy - tool.db-query-readonly - mcp.internal.crm-mcp deny: - tool.db-write - tool.code-execution guard: approvalRequired: - tool.db-query-readonly audit: true maxToolCallsPerTask: 20 memory: wiki: true dream: true retentionDays: 90这个配置里有几个关键点。capabilities.bind是白名单只有列出的能力这个员工才能调用。capabilities.deny是显式拒绝优先级高于 bind防止误绑。guard.approvalRequired指定哪些能力调用前要审批这里把只读查询也放进去了因为客服场景下查生产库属于敏感操作。model.failoverPolicy: on-error配合fallback列表实现多模型 failover主模型挂了自动切备用任务不中断。运行闭环的配置在runtime/loop.yaml# runtime/loop.yaml loop: mode: plan-and-execute maxIterations: 15 selfCheck: true goalChecklist: true planning: discoverCapabilities: true catalogPath: /data/capabilities candidateLimit: 5 injectMode: on-demand execution: toolGuard: true timeoutMs: 30000 retryOnFailure: 1 fallbackOnToolError: true verification: checklistSource: goal requireAllChecked: true onFailure: escalate persistence: memoryWrite: true wikiCitation: true auditLog: /data/audit/loop.logplanning.discoverCapabilities: true是能力目录和运行闭环的接合点。开启后Agent 在规划阶段会先去能力目录里找候选能力而不是把所有工具 schema 塞进 prompt。candidateLimit: 5限制候选数量避免上下文膨胀。injectMode: on-demand表示只在需要时注入能力描述进一步省 token。execution.toolGuard: true开启工具守卫配合员工配置里的approvalRequired生效。verification.goalChecklist: true让 Agent 执行完后逐条对照 Goal 验收requireAllChecked: true表示有一条没通过就触发escalate转人工或降级。persistence部分对应运行闭环的沉淀环节。memoryWrite把本次任务的经验写进 MemorywikiCitation让知识库引用可追溯auditLog记录完整调用链。把这两个配置放好后重启 MateClaw 让配置生效docker restart mateclaw-local重启后Web Console 的 Employees 页面能看到客服助理点进去能看到它绑定的能力列表和 Guard 规则。Capability Catalog 页面能看到所有已注册能力及其被哪些员工绑定。这里有个配置上的坑要提醒capabilities.bind里引用的能力 id 必须和目录里注册的 id 完全一致包括大小写和点号分隔。我早期写成skill.refund-policy漏了团队前缀结果绑定静默失败Agent 运行时找不到能力报的是“no capability matched”排查了半天才发现是 id 不匹配。建议绑定后用下面的验证命令确认。4. 验证请求闭环跑通与成功结果确认配置写完后必须做一次端到端验证确认能力目录、员工绑定、运行闭环三者真的串起来了。验证分两步先验证能力发现再验证完整闭环。第一步验证能力发现。调用 MateClaw 的 discover 接口模拟 Agent 规划阶段找能力curl -X POST http://localhost:8080/api/runtime/discover \ -H Content-Type: application/json \ -d { employeeId: employee.cs-assistant, task: 客户想查订单 12345 的退款状态, candidateLimit: 5 }预期返回{ candidates: [ { id: mcp.internal.crm-mcp, score: 0.92, reason: 订单查询能力匹配任务关键词 }, { id: skill.cs-team.refund-policy, score: 0.88, reason: 退款政策知识匹配退款状态查询 }, { id: tool.db-query-readonly, score: 0.71, reason: 只读查询可作为兜底但需审批 } ], denied: [tool.db-write, tool.code-execution] }如果candidates为空说明能力目录没注册成功或员工绑定 id 不匹配。如果denied里出现了不该出现的能力说明 deny 列表配置有误。这一步能快速定位目录和绑定问题。第二步验证完整闭环。发起一个真实任务观察从规划到验收的全过程curl -X POST http://localhost:8080/api/runtime/execute \ -H Content-Type: application/json \ -d { employeeId: employee.cs-assistant, goal: 查询订单 12345 的退款状态并给出处理建议, stream: false }预期返回结构{ taskId: task-20260618-001, status: completed, plan: [ 调用 crm-mcp 查询订单状态, 调用 refund-policy 匹配退款规则, 生成处理建议 ], toolCalls: [ { capability: mcp.internal.crm-mcp, status: success, durationMs: 320 }, { capability: skill.cs-team.refund-policy, status: success, durationMs: 180 } ], approvals: [], goalChecklist: [ { item: 查询订单状态, checked: true }, { item: 匹配退款规则, checked: true }, { item: 给出处理建议, checked: true } ], citations: [ refund-policy#section-3.2 ], auditLog: /data/audit/loop.log#task-20260618-001 }看到status: completed、goalChecklist全部checked: true、citations有引用、auditLog有记录就说明闭环跑通了。approvals为空是因为这次任务没触发审批如果任务涉及approvalRequired里的能力这里会出现待审批项任务会暂停等审批。再验证一次审批流。发起一个会触发审批的任务curl -X POST http://localhost:8080/api/runtime/execute \ -H Content-Type: application/json \ -d { employeeId: employee.cs-assistant, goal: 直接查生产库确认订单 12345 的支付流水, stream: false }预期返回里status变成pending-approvalapprovals数组里出现tool.db-query-readonly的待审批项。这时候去 Web Console 的 Approvals 页面点通过任务才会继续。这一步验证的是 Tool Guard 和审批闭环。验证通过后你就有了一套可运行的能力目录加运行闭环。接下来把它接到统一的模型通道上才能让这套闭环真正跑在生产环境。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易卡在几个报错上。这一节按真实报错逐个拆。401 Unauthorized。这个报错通常出现在调用模型接口时。MateClaw 的模型接入走统一的 Base URL 和 API Key如果你在model配置里填的 Key 无效或过期就会 401。排查步骤先确认 Key 有没有多余空格再确认 Base URL 是否指向正确的通道。MateClaw 的模型配置建议统一走一个 API 通道避免每个模型单独配 Key。配置片段model: primary: claude-sonnet provider: baseUrl: https://taotoken.net/api apiKey: ${TAOTOKEN_API_KEY} modelId: claude-sonnet-4-20250514baseUrl、apiKey、modelId三件套必须齐全缺一个就会 401 或 404。apiKey用环境变量注入不要硬编码在 YAML 里。local proxy failed。这个报错一般出现在 MateClaw 尝试连接 MCP Server 或外部能力时。常见原因是 MCP Server 没启动或者 endpoint 地址写错。排查先用curl直接测 MCP Server 的健康端点确认它活着再检查能力描述文件里的endpoint字段和实际地址是否一致。如果是 Docker 环境注意容器内外的地址差异localhost在容器里指向容器自己要用宿主机的实际地址或 Docker 网络别名。reading choices 报错。这个通常出现在模型返回结构不符合预期时比如你用的模型返回格式和 MateClaw 解析逻辑不匹配。排查先确认modelId填的是 MateClaw 支持的模型标识不要填成别的平台的模型名。再检查provider.baseUrl是否指向兼容 OpenAI 或 Anthropic 协议的通道。如果模型返回的是流式格式但配置里stream: false也可能触发解析错误。把stream和模型实际返回格式对齐即可。OAuth 相关报错。如果你接的是需要 OAuth 的能力比如某些企业内部的 MCP Server报错通常是 token 过期或 scope 不足。排查先确认 OAuth token 的有效期再确认申请的 scope 是否覆盖了要调用的能力。MateClaw 的 Tool Guard 会在调用前检查 token 状态如果 token 过期会直接拦截并报 OAuth 错误而不是等到调用失败。这时候去 Web Console 的 Credentials 页面刷新 token 即可。还有一个隐蔽的坑能力目录导入后如果conflictPolicy设成version-wins但两个能力版本号相同会静默跳过后者导致你以为导入了实际没导入。排查方法是导入后调/api/capabilities/list确认数量或者直接在 Web Console 里数。我踩过一次目录里明明有 12 个能力导入后只有 11 个查了半天发现是两个文件 id 重复且版本号一样。最后如果所有配置都对但任务还是失败去看/data/audit/loop.log里面记录了每一步的输入输出和错误堆栈。这个日志是排查闭环问题最直接的工具比在 Web Console 里点来点去快得多。6. 统一 Key 与 API 通道把能力目录接到生产运行层能力目录和运行闭环配好后最后一步是把它接到统一的模型通道上。这一步的意义在于企业里可能有多个模型供应商、多个 API Key、多个计费账号如果每个员工、每个能力都单独配 Key管理成本会爆炸审计也做不了。统一通道能把 Key 收敛到一处按员工或任务维度做配额和审计。TaoToken 在这里的角色是统一 Key 和 API 通道。你可以在 TaoToken 控制台创建 API Key然后在 MateClaw 的模型配置里统一指向这个通道。这样所有员工的模型调用都走同一个 Base URLKey 只有一个审计日志也集中。具体操作先去 TaoToken 控制台创建 API Key拿到 Key 后在 MateClaw 的环境变量里注入export TAOTOKEN_API_KEY你的Key然后在runtime/loop.yaml的 model 配置里引用model: primary: claude-sonnet fallback: [gpt-4o-mini, qwen-plus] provider: baseUrl: https://taotoken.net/api apiKey: ${TAOTOKEN_API_KEY} modelId: claude-sonnet-4-20250514 failoverPolicy: on-error这样配置后MateClaw 的所有模型调用都走统一通道。多模型 failover 也在这个通道内完成主模型不可用时自动切 fallback 列表里的下一个任务不中断。如果你需要更细粒度的控制比如给不同员工分配不同的模型配额可以在 TaoToken 控制台创建多个 Key然后在员工配置里按员工引用不同的环境变量。但大多数场景下一个 Key 加 MateClaw 内部的员工级 Guard 就够了。接入完成后再跑一次第 4 节的验证请求确认模型调用也走通了。如果返回结果正常说明从能力目录到运行闭环再到模型通道整条链路都通了。后续如果要扩展几个方向值得关注把能力目录导出成 ARD 兼容的ai-catalog.json对接外部能力发现给能力加使用统计和评分让 Agent 规划时优先选高成功率的能力把 Tool Guard 的审批流接到企业现有的审批系统。这些都是在能力目录和运行闭环基础上的自然演进。最后给一个实用技巧能力描述文件建议纳入版本控制每次改动走 PR 审核。因为能力描述直接决定 Agent 选什么工具改错一个描述可能导致 Agent 在生产环境误操作。把能力目录当代码管是这套体系能长期跑稳的前提。