1. Agent Finder 热潮下，企业 Agent 治理的真实缺口在哪
Agent Finder 和 ARD 规范的出现，把一个问题摆到了台面上：当企业里同时跑着几十个 Agent、上百个 MCP Server、各种 Skills 和内部 API 时，谁来管这些能力？不是缺 Agent，而是缺一个能回答“能力在哪里、该用哪个、能不能信”的运行层。这篇文章就以 MateClaw 为参照，拆解能力目录和运行闭环怎么落地，并给出可复制的目录结构配置和闭环验证动作。
先说清楚几个概念。Agent Finder 是 GitHub 给 Copilot 做的一个能力发现入口，让 Copilot 能从公共或私有目录里找到合适的 AI 资源。ARD（Agentic 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_MODE=dev \ 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把本次任务的经验写进 Memory，wikiCitation让知识库引用可追溯，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-approval，approvals数组里出现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 URL，Key 只有一个，审计日志也集中。
具体操作：先去 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 在生产环境误操作。把能力目录当代码管，是这套体系能长期跑稳的前提。
