插件 Agent 工具
适用范围
在以下情况使用本页：
- 您想在插件中添加新的 agent 工具
- 您需要通过白名单使工具成为可选
Clawdbot 插件可以注册agent 工具（JSON 架构函数），这些工具在 agent 运行期间暴露给 LLM。工具可以是必需的（始终可用）或可选的（可选加入）。
Agent 工具在主配置中的 tools 下配置，或在每个 agent 的 agents.list[].tools 下配置。白名单/黑名单策略控制 agent 可以调用哪些工具。
基本工具
import { Type } from "@sinclair/typebox";
export default function (api) {
api.registerTool({
name: "my_tool",
description: "Do a thing",
parameters: Type.Object({
input: Type.String(),
}),
async execute(_id, params) {
return { content: [{ type: "text", text: params.input }] };
},
});
}可选工具（可选加入）
可选工具永远不会自动启用。用户必须将它们添加到 agent 白名单中。
export default function (api) {
api.registerTool(
{
name: "workflow_tool",
description: "Run a local workflow",
parameters: {
type: "object",
properties: {
pipeline: { type: "string" },
},
required: ["pipeline"],
},
async execute(_id, params) {
return { content: [{ type: "text", text: params.pipeline }] };
},
},
{ optional: true },
);
}在 agents.list[].tools.allow（或全局 tools.allow）中启用可选工具：
{
agents: {
list: [
{
id: "main",
tools: {
allow: [
"workflow_tool", // 特定工具名称
"workflow", // 插件 ID（启用来自该插件的所有工具）
"group:plugins" // 所有插件工具
]
}
}
]
}
}其他影响工具可用性的配置选项：
- 仅命名插件工具的白名单被视为插件可选加入；核心工具保持启用，除非您还在白名单中包含核心工具或组。
tools.profile/agents.list[].tools.profile（基础白名单）tools.byProvider/agents.list[].tools.byProvider（提供商特定的允许/拒绝）tools.sandbox.tools.*（沙箱时的沙箱工具策略）
规则 + 提示
- 工具名称不得与核心工具名称冲突；跳过冲突的工具。
- 白名单中使用的插件 ID 不得与核心工具名称冲突。
- 对于触发副作用或需要额外二进制文件/凭据的工具，首选
optional: true。