1Password secrets broker

기준일: 2026-07-26
공식 기준: 1Password secrets broker

1Password secrets broker 문서는 OpenClaw 공식 문서(plugins/onepassword)를 한국어로 정리한 가이드입니다. Use the optional 1Password plugin as an audited agent secrets broker 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Use the optional 1Password plugin as an audited agent secrets broker

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

문서 구성

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

• 1Password secrets broker
• Security model
• 시작하기 전에
• Configure registered secrets
• Use the agent tool
• Policy tiers and approvals
• Inspect status and audit history
• 1Password CLI behavior
• Error codes

상세 내용

1Password secrets broker

The bundled onepassword plugin gives agents one policy-controlled tool for reading a curated set of 1Password fields. It is disabled by default and does nothing until plugins.entries.onepassword.config is present.

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

Security model

file and is never accepted in openclaw.json.

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

주요 항목:

• Service-account authentication only. The token stays in a local credentials
• Curated registry only. Agents can list configured slugs, but the plugin never
• Per-slug auto, approve, or deny policy.
• Approval grants expire. A cached value never bypasses current policy.
• Every access attempt is recorded in OpenClaw's shared SQLite state. Audit
• After the current tool execution, OpenClaw-owned transcript persistence
• The value is model-visible for that execution. If the model copies it into a
• The plugin invokes op once per cache miss. It does not retry rate limits or
• Each op call runs with a minimal environment that disables 1Password

시작하기 전에

Create the token directory and file under the OpenClaw state directory:

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

주요 항목:

• the 1Password CLI (op) installed on the Gateway host
• a 1Password service account with access to the selected items
• a dedicated service-account token file

openclaw plugins enable onepassword

mkdir -p ~/.openclaw/credentials/onepassword
chmod 700 ~/.openclaw/credentials/onepassword
printf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \
  ~/.openclaw/credentials/onepassword/service-account-token
chmod 600 ~/.openclaw/credentials/onepassword/service-account-token
unset OP_SERVICE_ACCOUNT_TOKEN

Configure registered secrets

Slugs use lowercase letters, numbers, and hyphens, start with a letter or number, and contain at most 64 characters. A registry can contain up to 32 slugs; descriptions can contain up to 200 characters. field accepts one field label or ID, must not contain a comma, and defaults to credential. An item-level vault overrides the default vault. opBin can set an absolute path to the op executable; otherwise the plugin resolves op from PATH. Item titles must not start with a hyphen.

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

{
  "plugins": {
    "entries": {
      "onepassword": {
        "enabled": true,
        "config": {
          "vault": "Automation",
          "defaultPolicy": "approve",
          "cacheTtlSeconds": 300,
          "grantTtlHours": 720,
          "opTimeoutMs": 15000,
          "items": {
            "repository-token": {
              "item": "Repository automation token",
              "field": "credential",
              "policy": "approve",
              "description": "Token for repository automation",
            },
            "model-key": {
              "item": "Model provider key",
              "vault": "Agent credentials",
              "policy": "auto",
            },
          },
        },
      },
    },
  },
}

Use the agent tool

The result contains only the slug, description, policy, and whether a standing grant is active. It never contains a secret value and does not query 1Password.

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

{ "action": "list" }

{
  "action": "get",
  "slug": "repository-token",
  "reason": "Authenticate the requested repository operation"
}

Policy tiers and approvals

Allow once authorizes only the current tool call. Allow always writes a standing grant for that agent and slug to SQLite; other agents must receive their own approval. OpenClaw offers allow always only when the caller has a concrete agent identity. The grant expires after grantTtlHours, which defaults to 720 hours. An unresolved or timed-out approval denies the request; the maximum approval wait is 600 seconds. The plugin retains up to 1,024 standing grants; at that bound, the oldest grant is evicted and its agent must approve the next access.

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

주요 항목:

• auto: fetch immediately and audit the request.
• deny: block and audit the request.
• approve: use an unexpired standing grant, or ask a human to allow once,

Inspect status and audit history

This reports whether the token file exists, whether op resolved and its path, the registered item count, and per-policy counts. It never reads or prints the token or secret values.

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

openclaw onepassword status

openclaw onepassword audit
openclaw onepassword audit --limit 100

1Password CLI behavior

Each cache miss runs op item get with the configured item, vault, and exact field selector, JSON output, a bounded timeout, and --cache=false. The child receives only that field rather than the full item. Only OP_SERVICE_ACCOUNT_TOKEN and HOME are present in the child environment.

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

Error codes

Failed attempts carry one closed error code in the tool result and the audit row.

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

Code	Meaning
TOKEN_MISSING	Token file is missing or empty
OP_NOT_FOUND	op binary could not be resolved
ITEM_NOT_FOUND	Configured item is not in the vault
FIELD_NOT_FOUND	Configured field is not on the item; available labels are listed
RATE_LIMITED	1Password service-account rate limit reached
AUTH_FAILED	Service-account authentication failed
TIMEOUT	op exceeded opTimeoutMs
OP_ERROR	Any other op failure or invalid output

Code	Meaning
INVALID_ACTION, INVALID_REASON, INVALID_SLUG	Request failed input validation
UNKNOWN_SLUG	Slug is not in the configured registry
TOOL_CALL_ID_MISSING	Call arrived without a tool call id
POLICY_NOT_EVALUATED	No matching authorization for this call; the request was not policy-approved
POLICY_CHANGED	Config changed between approval and execution
GRANT_EXPIRED	Standing grant lapsed before execution
APPROVAL_CANCELLED	The run was aborted while the approval was pending

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw plugins enable onepassword

mkdir -p ~/.openclaw/credentials/onepassword
chmod 700 ~/.openclaw/credentials/onepassword
printf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \
  ~/.openclaw/credentials/onepassword/service-account-token
chmod 600 ~/.openclaw/credentials/onepassword/service-account-token
unset OP_SERVICE_ACCOUNT_TOKEN

{
  "plugins": {
    "entries": {
      "onepassword": {
        "enabled": true,
        "config": {
          "vault": "Automation",
          "defaultPolicy": "approve",
          "cacheTtlSeconds": 300,
          "grantTtlHours": 720,
          "opTimeoutMs": 15000,
          "items": {
            "repository-token": {
              "item": "Repository automation token",
              "field": "credential",
              "policy": "approve",
              "description": "Token for repository automation",
            },
            "model-key": {
              "item": "Model provider key",
              "vault": "Agent credentials",
              "policy": "auto",
            },
          },
        },
      },
    },
  },
}

{ "action": "list" }

{
  "action": "get",
  "slug": "repository-token",
  "reason": "Authenticate the requested repository operation"
}

openclaw onepassword status

관련 링크

• 공식 원문: plugins/onepassword
• OpenClaw 문서 홈

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