Plugin permission requests

기준일: 2026-07-26
공식 기준: Plugin permission requests

Plugin permission requests 문서는 OpenClaw 공식 문서(plugins/plugin-permission-requests)를 한국어로 정리한 가이드입니다. Ask users to approve plugin tool calls and plugin-owned permission prompts 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Ask users to approve plugin tool calls and plugin-owned permission prompts

한국어 가이드 범위: plugins/plugin-permission-requests 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Choose the right gate
• Request approval before a tool call
• Decision behavior
• Route approval prompts
• Codex native permissions
• 트러블슈팅
• 관련 문서

상세 내용

본문

Plugin permission requests let plugin code pause a tool call or plugin-owned operation until a user approves or denies it. They use the Gateway plugin.approval.* flow and the same approval UI surfaces that handle chat approval buttons and /approve commands.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Choose the right gate

Pick the gate that matches the decision point you need:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Gate	Use it when	What it controls
Optional tools	A tool should not be visible to the model until the user opts in.	Tool exposure through tools.allow.
Plugin permission requests	A plugin hook or plugin-owned operation must ask before one action runs.	Runtime approval through plugin.approval.*.
Exec approvals	A host command or shell-like tool needs operator approval.	Host exec policy and durable exec allowlists.
Codex native permission requests	Codex asks before native shell, file, MCP, or app-server actions.	Codex app-server or native hook approval handling, routed through plugin approvals when OpenClaw owns the prompt.
MCP approval elicitations	A Codex MCP server requests approval for a tool call.	MCP approval responses bridged through OpenClaw plugin approvals.

Request approval before a tool call

Most plugin-authored prompts should start in a before_tool_call hook. The hook runs after the model selects a tool and before OpenClaw executes it:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Keep title short and action-focused; the Gateway caps it at 80 characters.
• Keep description specific and bounded; the Gateway caps it at 512
• Include the action, target, and risk. Do not include secrets, tokens, or
• severity defaults to "warning" when omitted. Use "critical" only for
• allowedDecisions defaults to ["allow-once", "allow-always", "deny"] when
• timeoutMs defaults to 120000 (2 minutes) and is capped at 600000 (10

id: "deploy-policy",
  name: "Deploy Policy",
  register(api) {
    api.on("before_tool_call", async (event) => {
      if (event.toolName !== "deploy_service") {
        return;
      }

      const environment =
        typeof event.params.environment === "string" ? event.params.environment : "unknown";

      return {
        requireApproval: {
          title: "Deploy service",
          description: `Deploy service to ${environment}.`,
          severity: environment === "production" ? "critical" : "warning",
          allowedDecisions:
            environment === "production"
              ? ["allow-once", "deny"]
              : ["allow-once", "allow-always", "deny"],
          timeoutMs: 120_000,
          onResolution(decision) {
            console.log(`deploy approval resolved: ${decision}`);
          },
        },
      };
    });
  },
});

Decision behavior

OpenClaw creates a pending approval with a plugin: ID, delivers it to the available approval surfaces, and waits for a decision.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Decision	Result
allow-once	The current call continues.
allow-always	The current call continues and the decision is passed to the plugin.
deny	The call is blocked with a denied tool result.
Timeout	The call is blocked.
Cancellation	The call is blocked when the run is aborted.
No approval route	The call is blocked because no connected approval surface can resolve it.

Route approval prompts

Approval prompts can resolve in local UI surfaces or in chat channels that support approval handling. To forward plugin approval prompts to explicit chat targets, configure approvals.plugin:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  approvals: {
    plugin: {
      enabled: true,
      mode: "targets",
      agentFilter: ["main"],
      targets: [{ channel: "slack", to: "U12345678" }],
    },
  },
}

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

Codex native permissions

Codex native permission prompts can also travel through plugin approvals, but they have different ownership than plugin-authored hooks.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Codex app-server approval requests route through OpenClaw after Codex review.
• The native hook permission_request relay can ask through
• MCP tool approval elicitations route through plugin approvals when Codex marks

트러블슈팅

approval route accepted the request. Connect an approval-capable client, use a channel that supports same-chat /approve, or configure approvals.plugin.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

관련 문서

주요 항목:

• Plugin hooks
• Building plugins
• Advanced exec approvals
• Gateway protocol
• Codex harness runtime

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/plugin-permission-requests
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

id: "deploy-policy",
  name: "Deploy Policy",
  register(api) {
    api.on("before_tool_call", async (event) => {
      if (event.toolName !== "deploy_service") {
        return;
      }

      const environment =
        typeof event.params.environment === "string" ? event.params.environment : "unknown";

      return {
        requireApproval: {
          title: "Deploy service",
          description: `Deploy service to ${environment}.`,
          severity: environment === "production" ? "critical" : "warning",
          allowedDecisions:
            environment === "production"
              ? ["allow-once", "deny"]
              : ["allow-once", "allow-always", "deny"],
          timeoutMs: 120_000,
          onResolution(decision) {
            console.log(`deploy approval resolved: ${decision}`);
          },
        },
      };
    });
  },
});

{
  approvals: {
    plugin: {
      enabled: true,
      mode: "targets",
      agentFilter: ["main"],
      targets: [{ channel: "slack", to: "U12345678" }],
    },
  },
}

/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny

관련 링크

• 공식 원문: plugins/plugin-permission-requests
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.