OpenClaw Plugin Agent Tools 등록 및 설정하기

LLM이 특정 작업을 직접 수행하게 만들고 싶을 때가 많아요. 하지만 도구를 연결하고 관리하는 과정이 복잡하면 개발 흐름이 끊기기 마련이죠. 매번 수동으로 기능을 호출하는 대신, Agent가 스스로 필요한 도구를 선택해 실행할 수 있는 환경을 만드는 것이 중요해요.

필요한 것

• OpenClaw 플러그인 개발 환경
• @sinclair/typebox (Basic tool 정의 시 필요)
• JSON-schema 기반의 function 호출 방식에 대한 이해

빠른 시작

5분 만에 Agent Tool을 등록하고 활성화하는 방법이에요.

1. Basic Tool 등록하기

가장 기본적인 형태의 도구예요. api.registerTool을 사용해 등록하며, 별도의 설정이 없으면 기본적으로 활성화돼요.

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 }] };
    },
  });
}

2. Optional Tool 등록하기

사용자가 직접 선택했을 때만 활성화되는 도구예요. 부작용(side effects)이 있거나 추가적인 자격 증명이 필요한 경우에 추천해요.

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 },
  );
}

3. Config에서 도구 활성화하기

Optional tool은 agents.list[].tools.allow 또는 글로벌 tools.allow 설정에 추가해야 사용할 수 있어요.

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // 특정 tool 이름
            "workflow", // plugin id (해당 플러그인의 모든 도구 활성화)
            "group:plugins", // 모든 플러그인 도구
          ],
        },
      },
    ],
  },
}

문제 해결

도구가 예상대로 작동하지 않는다면 다음 사항을 확인해 보세요.

• 이름 충돌: Tool 이름이 Core tool 이름과 겹치면 해당 도구는 등록되지 않고 건너뛰게 돼요.
• Allowlist 설정: Optional tool은 반드시 allow 리스트에 명시되어야 해요. 리스트에 Plugin tool만 적혀 있다면 Core tool은 별도로 포함하지 않는 한 활성 상태를 유지해요.

질문이 더 있거나 도움이 필요하신가요? AI Setup Assistant에게 물어보세요.

다음 단계

• tools.profile: 기본 allowlist 설정 방법
• tools.byProvider: Provider별 도구 허용 및 차단 정책
• tools.sandbox.tools.*: Sandbox 환경에서의 도구 정책
• Core tool 목록 확인 및 이름 충돌 방지 가이드