​

플러그인 (확장)

​

빠른 시작 (플러그인을 처음 사용하시나요?)

1. 이미 로드된 플러그인 확인:

openclaw plugins list

2. 공식 플러그인 설치 (예시: 음성통화):

openclaw plugins install @openclaw/voice-call

3. 게이트웨이를 재시작한 다음 plugins.entries.<id>.config에서 구성합니다.

​

사용 가능한 공식 플러그인

• Microsoft Teams는 2026.1.15부터 플러그인으로만 제공됩니다. Teams를 사용한다면 @openclaw/msteams를 설치하세요.
• Memory (Core) — 번들 메모리 검색 플러그인 (plugins.slots.memory를 통해 기본 활성화)
• Memory (LanceDB) — 번들 장기 메모리 플러그인 (자동 회수/캡처; plugins.slots.memory = "memory-lancedb"로 설정)
• Voice Call — @openclaw/voice-call
• Zalo Personal — @openclaw/zalouser
• Matrix — @openclaw/matrix
• Nostr — @openclaw/nostr
• Zalo — @openclaw/zalo
• Microsoft Teams — @openclaw/msteams
• Google Antigravity OAuth (프로바이더 인증) — google-antigravity-auth로 번들화 (기본 비활성화)
• Gemini CLI OAuth (프로바이더 인증) — google-gemini-cli-auth로 번들화 (기본 비활성화)
• Qwen OAuth (프로바이더 인증) — qwen-portal-auth로 번들화 (기본 비활성화)
• Copilot Proxy (프로바이더 인증) — 로컬 VS Code Copilot Proxy 브릿지; 내장 github-copilot 디바이스 로그인과 다름 (번들, 기본 비활성화)

• 게이트웨이 RPC 메서드
• 게이트웨이 HTTP 핸들러
• 에이전트 도구
• CLI 명령어
• 백그라운드 서비스
• 선택적 설정 검증
• 스킬 (플러그인 매니페스트 내 skills 디렉터리를 나열하여)
• 자동 응답 명령어 (AI 에이전트를 호출하지 않고 실행됨)

​

런타임 도우미

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

• 코어 messages.tts 설정을 사용합니다 (OpenAI 또는 ElevenLabs).
• PCM 오디오 버퍼와 샘플 속도를 반환합니다. 플러그인은 프로바이더에 맞게 재샘플/인코딩해야 합니다.
• Edge TTS는 전화에서 지원되지 않습니다.

​

디바이스 검색 및 우선순위

1. 설정 경로

• plugins.load.paths (파일 또는 디렉터리)

2. 워크스페이스 확장

• <workspace>/.openclaw/extensions/*.ts
• <workspace>/.openclaw/extensions/*/index.ts

3. 글로벌 확장

• ~/.openclaw/extensions/*.ts
• ~/.openclaw/extensions/*/index.ts

4. 번들 확장 (OpenClaw와 함께 배송되며, 기본 비활성화)

• <openclaw>/extensions/*

• plugins.allow가 비어 있고 번들이 아닌 플러그인이 검색 가능한 경우, OpenClaw는 플러그인 ID와 소스를 포함한 시작 경고를 기록합니다.
• 후보 경로는 검색 승인 전에 안전 검사를 받습니다. OpenClaw는 다음 경우 후보를 차단합니다:
  • 확장 항목이 심볼릭 링크/경로 탐색 탈출을 포함하여 플러그인 루트 밖으로 해석되는 경우,
  • 플러그인 루트/소스 경로가 전 세계 쓰기 가능한 경우,
  • 번들이 아닌 플러그인에서 경로 소유권이 의심스러운 경우 (POSIX 소유자가 현재 uid나 root가 아닌 경우).
• 설치/로드 경로 출처가 없는 번들이 아닌 로드된 플러그인은 신뢰를 고정(plugins.allow)하거나 설치 추적(plugins.installs)할 수 있도록 경고를 발생시킵니다.

​

패키지 팩

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

​

채널 카탈로그 메타데이터

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

플러그인 IDs

• 패키지 팩: package.json name
• 독립 파일: 파일 기본 이름 (~/.../voice-call.ts → voice-call)

​

설정

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

• enabled: 마스터 토글 (기본: true)
• allow: 허용 목록 (선택 사항)
• deny: 거부 목록 (선택 사항; 거부가 우선)
• load.paths: 추가 플러그인 파일/디렉터리
• entries.<id>: 플러그인별 토글 및 설정

• entries, allow, deny, 또는 slots의 알 수 없는 플러그인 ids는 오류입니다.
• 알 수 없는 channels.<id> 키는 플러그인 매니페스트에서 채널 id를 선언하지 않는 한 오류입니다.
• 플러그인 설정은 openclaw.plugin.json에 포함된 JSON 스키마를 사용하여 검증됩니다 (configSchema).
• 플러그인이 비활성화되면, 그 설정은 보존되며 경고가 발생합니다.

​

플러그인 슬롯 (독점적 카테고리)

{
  plugins: {
    slots: {
      memory: "memory-core", // 또는 "none"으로 메모리 플러그인 비활성화
    },
  },
}

​

제어 UI (스키마 + 라벨)

• plugins.entries.<id> / .enabled / .config에 플러그인별 라벨 추가
• 선택적 플러그인 제공 설정 필드 힌트를 아래에 병합: plugins.entries.<id>.config.<field>

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true },
    "region": { "label": "Region", "placeholder": "us-east-1" }
  }
}

​

CLI

openclaw plugins list
openclaw plugins info <id>
openclaw plugins install <path>                 # 로컬 파일/디렉터리를 ~/.openclaw/extensions/<id>로 복사
openclaw plugins install ./extensions/voice-call # 상대 경로 허용
openclaw plugins install ./plugin.tgz           # 로컬 타볼에서 설치
openclaw plugins install ./plugin.zip           # 로컬 zip에서 설치
openclaw plugins install -l ./extensions/voice-call # 링크 (복사 없음) 개발용
openclaw plugins install @openclaw/voice-call # npm에서 설치
openclaw plugins install @openclaw/voice-call --pin # 정확한 해결된 name@version 저장
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

​

플러그인 API (개요)

• 함수: (api) => { ... }
• 객체: { id, name, configSchema, register(api) { ... } }

​

플러그인 후크

​

예

export default function register(api) {
  api.registerHook(
    "command:new",
    async () => {
      // Hook logic here.
    },
    {
      name: "my-plugin.command-new",
      description: "Runs when /new is invoked",
    },
  );
}

• api.registerHook(...)을 통해 후크를 명시적으로 등록하세요.
• 후크 적합성 규칙은 여전히 적용됩니다 (OS/바이너리/환경/설정 요건).
• 플러그인 관리 후크는 openclaw hooks list에 plugin:<id>로 표시됩니다.
• openclaw hooks를 통해 플러그인 관리 후크를 활성화/비활성화할 수 없습니다; 대신 플러그인을 활성화/비활성화하십시오.

​

프로바이더 플러그인 (모델 인증)

• openclaw models auth login --provider <id> [--method <id>]

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // OAuth 흐름을 실행하고 인증 프로파일을 반환합니다.
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

• run은 prompter, runtime, openUrl, oauth.createVpsAwareHandlers 도우미와 함께 ProviderAuthContext를 받습니다.
• 기본 모델 또는 프로바이더 설정을 추가해야 할 때 configPatch를 반환합니다.
• --set-default가 에이전트 기본값을 업데이트할 수 있도록 defaultModel을 반환합니다.

​

메시징 채널 등록하기

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "demo channel plugin.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

• 설정은 channels.<id> 아래에 두십시오 (plugins.entries가 아님).
• meta.label은 CLI/UI 목록에서 라벨에 사용됩니다.
• meta.aliases는 정상화 및 CLI 입력을 위한 대체 id를 추가합니다.
• meta.preferOver는 모두 설정된 경우 자동 활성화를 건너뛰기 위해 다른 채널 id를 나열합니다.
• meta.detailLabel과 meta.systemImage는 UI가 더 풍부한 채널 라벨/아이콘을 표시할 수 있도록 합니다.

​

새로운 메시징 채널 작성하기 (단계별)

1. id 및 설정 모양 선택

• 모든 채널 설정은 channels.<id>에 있습니다.
• 다중 계정 설정을 위해 channels.<id>.accounts.<accountId>를 선호합니다.

2. 채널 메타데이터 정의

• meta.label, meta.selectionLabel, meta.docsPath, meta.blurb는 CLI/UI 목록을 제어합니다.
• meta.docsPath는 /channels/<id>와 같은 문서 페이지를 가리켜야 합니다.
• meta.preferOver는 플러그인이 다른 채널을 대체할 수 있도록 합니다 (자동 활성화는 선호함).
• meta.detailLabel과 meta.systemImage는 UI에서 자세한 텍스트/아이콘에 사용됩니다.

3. 필요한 어댑터 구현

• config.listAccountIds + config.resolveAccount
• capabilities (채팅 유형, 미디어, 스레드 등)
• outbound.deliveryMode + outbound.sendText (기본 전송용)

4. 필요한 경우 선택적 어댑터 추가

• setup (마법사), security (다이렉트 메시지 정책), status (상태/진단)
• gateway (시작/중지/로그인), mentions, threading, streaming
• actions (메시지 작업), commands (네이티브 명령어 동작)

5. 플러그인에 채널 등록

• api.registerChannel({ plugin })

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "ACME_TOKEN", enabled: true },
      },
    },
  },
}

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat 메시징 채널.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // `text`를 채널로 배달하세요
      return { ok: true };
    },
  },
};

export default function (api) {
  api.registerChannel({ plugin });
}

​

에이전트 도구

​

게이트웨이 RPC 메소드 등록하기

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

​

CLI 명령어 등록하기

export default function (api) {
  api.registerCli(
    ({ program }) => {
      program.command("mycmd").action(() => {
        console.log("Hello");
      });
    },
    { commands: ["mycmd"] },
  );
}

​

자동 응답 명령어 등록하기

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "플러그인 상태 표시",
    handler: (ctx) => ({
      text: `플러그인이 실행 중입니다! 채널: ${ctx.channel}`,
    }),
  });
}

• senderId: 발신자의 ID (사용 가능한 경우)
• channel: 명령어가 전송된 채널
• isAuthorizedSender: 발신자가 인증된 사용자인지 여부
• args: 명령어 후 전달된 인수 (if acceptsArgs: true)
• commandBody: 전체 명령어 텍스트
• config: 현재 OpenClaw 설정

• name: 명령어 이름 (선행 / 없이)
• description: 명령어 목록에 표시되는 도움말 텍스트
• acceptsArgs: 명령어가 인수를 허용하는지 여부 (기본값: false). 인수를 허용하지 않으며 인수가 제공된 경우, 명령어는 일치하지 않으며 메시지는 다른 핸들러로 전달됩니다.
• requireAuth: 인증된 발신자를 요구할지 여부 (기본값: true)
• handler: { text: string }을 반환하는 함수 (비동기 가능)

api.registerCommand({
  name: "setmode",
  description: "플러그인 모드 설정",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    const mode = ctx.args?.trim() || "default";
    await saveMode(mode);
    return { text: `모드 설정: ${mode}` };
  },
});

• 플러그인 명령어는 내장 명령어와 AI 에이전트 이전에 처리됩니다.
• 명령어는 전역적으로 등록되며 모든 채널에서 작동합니다.
• 명령어 이름은 대소문자를 구분하지 않습니다 (/MyStatus는 /mystatus와 일치).
• 명령어 이름은 문자로 시작해야 하며 문자, 숫자, 하이픈 및 밑줄만 포함해야 합니다.
• 예약된 명령어 이름 (예: help, status, reset 등)은 플러그인에 의해 재정의될 수 없습니다.
• 플러그인 간 중복 명령어 등록은 진단 오류와 함께 실패합니다.

​

백그라운드 서비스 등록하기

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

​

명명 규칙

• 게이트웨이 메서드: pluginId.action (예: voicecall.status)
• 도구: snake_case (예: voice_call)
• CLI 명령어: 케밥 또는 카멜, 하지만 핵심 명령어와 겹치지 않도록 주의하십시오.

​

스킬

​

배포 (npm)

• 메인 패키지: openclaw (이 리포)
• 플러그인: @openclaw/* 아래 별도의 npm 패키지 (예: @openclaw/voice-call)

• 플러그인 package.json은 하나 이상의 엔트리 파일과 함께 openclaw.extensions를 포함해야 합니다.
• 엔트리 파일은 .js 또는 .ts일 수 있습니다 (jiti는 런타임에 TS를 로드합니다).
• openclaw plugins install <npm-spec>은 npm pack을 사용하여 ~/.openclaw/extensions/<id>/로 추출하고 설정에서 활성화합니다.
• 설정 키 안정성: 범위별 패키지는 plugins.entries.*에 대해 비범위 id로 정규화됩니다.

​

예제 플러그인: Voice Call

• 소스: extensions/voice-call
• 스킬: skills/voice-call
• CLI: openclaw voicecall start|status
• 도구: voice_call
• RPC: voicecall.start, voicecall.status
• 설정 (twilio): provider: "twilio" + twilio.accountSid/authToken/from (선택적 statusCallbackUrl, twimlUrl)
• 설정 (dev): provider: "log" (네트워크 없음)

​

안전성 주의사항

• 신뢰할 수 있는 플러그인만 설치하십시오.
• plugins.allow 허용 목록을 선호하십시오.
• 변경 사항 후 게이트웨이를 재시작하십시오.

​

플러그인 테스트

• 리포 내 플러그인은 src/** 아래 Vitest 테스트를 유지할 수 있습니다 (예: src/plugins/voice-call.plugin.test.ts).
• 별도로 게시된 플러그인은 자체 CI (lint/build/test)를 실행하고 openclaw.extensions가 빌드된 엔트리 포인트 (dist/index.js)를 가리키는지를 검증해야 합니다.

​

최근 업데이트 메모

• 플러그인 시스템은 manifest-first discovery, enablement, runtime loading, registry consumption의 네 층으로 설명됩니다.
• 워크스페이스 플러그인은 기본 비활성화이며, plugins.allow는 source provenance가 아니라 플러그인 id를 신뢰합니다.
• provider plugin은 auth, non-interactive setup, wizard integration, discovery, onModelSelected lifecycle을 담당할 수 있습니다.