​

Security

[!WARNING] 개인 비서 신뢰 모델: 이 문서는 gateway 하나당 신뢰할 수 있는 운영자 경계가 하나라는 가정을 전제로 합니다. OpenClaw는 여러 적대적 사용자가 하나의 agent/gateway를 공유하는 hostile multi-tenant 보안 경계를 제공하지 않습니다. 상호 비신뢰 사용자를 다뤄야 한다면 신뢰 경계를 분리하세요. 가능하면 gateway, 자격 증명, OS 사용자, 호스트를 각각 나누는 것이 좋습니다.

​

Scope first: personal assistant security model

• 권장 보안 태세: gateway 하나당 사용자/신뢰 경계 하나
• 지원하지 않는 경계: 서로 신뢰하지 않는 여러 사용자가 하나의 gateway나 agent를 공유하는 구성
• 적대적 사용자 격리가 필요하면 신뢰 경계별로 gateway를 분리하고, 가능하면 OS 사용자/호스트도 분리
• 여러 비신뢰 사용자가 하나의 도구 활성 agent에 메시지를 보낼 수 있다면, 그 agent의 위임된 도구 권한을 사실상 공유한다고 봐야 함

​

Quick check: openclaw security audit

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix
openclaw security audit --json

• 누가 봇과 대화할 수 있는가
• 봇이 어디에서 행동할 수 있는가
• 봇이 무엇에 접근할 수 있는가

​

Deployment assumption (important)

• ~/.openclaw와 openclaw.json을 포함한 gateway host 상태를 수정할 수 있는 사람은 신뢰된 운영자로 취급합니다.
• 여러 상호 비신뢰 운영자가 하나의 gateway를 공유하는 것은 권장하지 않습니다.
• mixed-trust 팀이라면 gateway를 분리하고, 가능하면 OS 사용자/호스트도 나누세요.
• 기술적으로 한 머신에서 여러 gateway를 띄울 수는 있지만, 권장 운영 기본값은 아닙니다.
• 권장 기본값: 사용자당 머신/호스트(VPS) 하나, 그 사용자용 gateway 하나, 그 안에 하나 이상의 agent

​

Practical consequence (operator trust boundary)

• 읽기/제어-plane 접근이 있는 운영자는 설계상 gateway session metadata와 history를 볼 수 있습니다.
• sessionKey, session ID, label은 라우팅 선택자이지 인증 토큰이 아닙니다.
• sessions.list, sessions.preview, chat.history 같은 메서드에서 운영자별 완전 격리를 기대하는 것은 이 모델 밖의 요구입니다.
• hostile-user isolation이 필요하면 trust boundary별로 별도 gateway를 사용하세요.

​

Personal assistant model (not a multi-tenant bus)

• 여러 사람이 하나의 tool-enabled agent와 대화할 수 있다면, 모두가 같은 권한 세트를 사실상 조종할 수 있습니다.
• 사용자별 session/memory 격리는 privacy에는 도움이 되지만, 공유 agent를 사용자별 host authorization 경계로 바꾸지는 않습니다.
• 상호 적대적일 수 있는 사용자라면 trust boundary별로 gateway를 분리해야 합니다.

​

Shared Slack workspace: real risk

• 허용된 발신자는 agent policy 안에서 exec, browser, network/file tool을 유도할 수 있습니다.
• 한 사용자의 prompt/content injection이 shared state, device, output에 영향을 줄 수 있습니다.
• 공유 agent가 민감한 credential/file에 접근 가능하다면, 허용된 발신자가 tool 사용을 통해 유출을 유도할 수 있습니다.

​

Company-shared agent: acceptable pattern

• 전용 머신/VM/컨테이너에서 실행
• 전용 OS 사용자 + 전용 browser/profile/account 사용
• 개인 Apple/Google 계정이나 개인 password-manager/browser profile에 로그인하지 않기

​

Gateway and node trust concept

• Gateway는 control plane과 policy surface(gateway.auth, tool policy, routing)
• Node는 paired device 위의 remote execution surface(command, device action, host-local capability)
• gateway에 인증된 호출자는 gateway 범위에서 신뢰됩니다.
• pairing 이후의 node action은 해당 node에서의 trusted operator action입니다.
• sessionKey는 routing/context selector이지 per-user auth가 아닙니다.
• exec approval은 operator intent를 확인하는 guardrail이지 hostile multi-tenant isolation 메커니즘이 아닙니다.

​

Trust boundary matrix

​

Not vulnerabilities by design

• policy/auth/sandbox bypass가 없는 prompt-injection-only chain
• hostile multi-tenant 환경을 가정한 주장
• 공유 gateway에서 정상적인 operator read path를 IDOR로 분류하는 주장
• localhost-only 배포의 HSTS 같은 지적
• 이 저장소에 존재하지 않는 inbound webhook path의 서명 문제
• sessionKey를 auth token처럼 해석한 주장

​

Researcher preflight checklist

1. 최신 main 또는 최신 릴리스에서 재현되는가
2. 정확한 code path(file, function, line range)와 테스트한 version/commit이 있는가
3. 영향이 문서화된 trust boundary를 실제로 넘는가
4. Out of Scope에 이미 해당하지 않는가
5. 기존 advisory와 중복되지 않는가
6. deployment assumption(local/loopback vs exposed, trusted vs untrusted operator)을 명시했는가

​

Hardened baseline in 60 seconds

{
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: { mode: "token", token: "replace-with-long-random-token" },
  },
  session: {
    dmScope: "per-channel-peer",
  },
  tools: {
    profile: "messaging",
    deny: ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"],
    fs: { workspaceOnly: true },
    exec: { security: "deny", ask: "always" },
    elevated: { enabled: false },
  },
  channels: {
    whatsapp: { dmPolicy: "pairing", groups: { "*": { requireMention: true } } },
  },
}

​

Shared inbox quick rule

• session.dmScope를 "per-channel-peer"로 설정
• dmPolicy는 "pairing" 또는 엄격한 allowlist로 유지
• 이것은 협업용 inbox hardening이지 hostile host isolation이 아님을 기억

​

What the audit checks (high level)

• gateway bind/auth 노출
• control UI/browser 원격 제어 surface
• elevated, runtime, filesystem tool exposure
• sandboxing과 workspace scope
• credential/config/state file permission
• plugin/extension 노출
• model/tool 조합이 너무 위험한지 여부

​

Credential storage map

• WhatsApp account state: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Allowlist/pairing state:
  • ~/.openclaw/credentials/<channel>-allowFrom.json
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json
• Model auth profiles: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Optional file-backed secrets payload: ~/.openclaw/secrets.json
• Legacy OAuth import: ~/.openclaw/credentials/oauth.json

​

Security Audit Checklist

1. open + tools enabled: DM/group 노출부터 줄이고 tool policy와 sandboxing을 조정
2. public network exposure: LAN bind, Funnel, missing auth는 즉시 수정
3. browser control remote exposure: operator access처럼 취급
4. permissions: state/config/credential/auth가 group/world-readable인지 확인
5. plugins/extensions: 신뢰하는 것만 로드
6. model choice: tools가 있는 bot에는 최신 지시 추종성이 강한 모델 사용

​

Security audit glossary

​

Control UI over HTTP

• localhost에서는 non-secure HTTP로 페이지를 열었을 때도 device identity 없이 Control UI auth를 허용합니다.
• pairing check를 우회하지는 않습니다.
• remote(non-localhost) device identity 요구사항을 완화하지도 않습니다.

​

Insecure or dangerous flags summary

• gateway.controlUi.allowInsecureAuth=true
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true
• gateway.controlUi.dangerouslyDisableDeviceAuth=true
• hooks.gmail.allowUnsafeExternalContent=true
• hooks.mappings[<index>].allowUnsafeExternalContent=true
• tools.exec.applyPatch.workspaceOnly=false

• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback
• gateway.controlUi.dangerouslyDisableDeviceAuth
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
• channels.discord.dangerouslyAllowNameMatching
• channels.slack.dangerouslyAllowNameMatching
• channels.googlechat.dangerouslyAllowNameMatching
• channels.msteams.dangerouslyAllowNameMatching
• channels.irc.dangerouslyAllowNameMatching
• channels.mattermost.dangerouslyAllowNameMatching
• agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets
• agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources
• agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin
• 같은 key의 agent별 override들

​

Reverse Proxy Configuration

gateway:
  trustedProxies:
    - "127.0.0.1" # proxy가 localhost에서 실행될 때
  # Optional. Default false.
  # proxy가 X-Forwarded-For를 제공할 수 없을 때만 켜세요.
  allowRealIpFallback: false
  auth:
    mode: password
    password: ${OPENCLAW_GATEWAY_PASSWORD}

proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

​

HSTS and origin notes

• OpenClaw gateway는 local/loopback 우선입니다. TLS를 reverse proxy에서 종료한다면, proxy가 노출하는 HTTPS 도메인에 HSTS를 설정하세요.
• gateway가 직접 HTTPS를 종료한다면 gateway.http.securityHeaders.strictTransportSecurity로 HSTS header를 보낼 수 있습니다.
• 자세한 배포 가이드는 Trusted Proxy Auth를 참고하세요.
• non-loopback Control UI 배포에서는 기본적으로 gateway.controlUi.allowedOrigins가 필요합니다.
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true는 Host-header origin fallback을 켜는 것으로, 위험한 operator-selected policy로 봐야 합니다.
• DNS rebinding과 proxy host-header 동작은 deployment hardening 문제로 다루고, trustedProxies를 좁게 유지하며 gateway를 공용 인터넷에 직접 노출하지 마세요.

​

Local session logs live on disk

​

Node execution (system.run)

• node pairing(approval + token)이 필요합니다.
• Mac 쪽에서는 Settings → Exec approvals에서 security/ask/allowlist로 제어합니다.
• approval mode는 정확한 request context와, 가능하면 하나의 구체적인 local script/file operand에 바인딩됩니다. interpreter/runtime command에서 정확히 하나의 직접 local file을 식별할 수 없으면, approval-backed execution은 semantic coverage를 약속하는 대신 거부됩니다.
• 원격 실행을 원하지 않으면 security를 deny로 두고 해당 Mac의 node pairing을 제거하세요.

​

Dynamic skills (watcher / remote nodes)

• Skills watcher: SKILL.md가 바뀌면 다음 agent turn에서 skills snapshot이 바뀔 수 있음
• Remote nodes: macOS node가 연결되면 macOS 전용 skill이 bin probing 결과에 따라 활성 대상이 될 수 있음

​

The Threat Model

• 임의 shell command 실행
• 파일 읽기/쓰기
• network service 접근
• WhatsApp 같은 채널이 연결되어 있으면 사람에게 메시지 전송

• AI를 속여 나쁜 행동을 하게 만들기
• 데이터 접근을 위한 social engineering
• 인프라 정보를 탐색하기

​

Core concept: access control before intelligence

• Identity first: 누가 봇과 대화할 수 있는지 결정
• Scope next: 봇이 어디에서 행동할 수 있는지 결정
• Model last: 모델은 조작될 수 있다고 가정하고, 조작되더라도 blast radius가 작도록 설계

​

Command authorization model

​

Control plane tools risk

• gateway: config.apply, config.patch, update.run 호출 가능
• cron: 원래 chat/task가 끝난 뒤에도 계속 실행되는 scheduled job 생성 가능

{
  tools: {
    deny: ["gateway", "cron", "sessions_spawn", "sessions_send"],
  },
}

​

Plugins/extensions

• 신뢰하는 출처의 plugin만 설치
• 가능하면 명시적 plugins.allow allowlist 사용
• 활성화 전에 plugin config를 검토
• plugin 변경 후 gateway 재시작
• npm으로 plugin을 설치할 때(openclaw plugins install <npm-spec>)는 untrusted code 실행처럼 취급
  • 설치 경로: ~/.openclaw/extensions/<pluginId>/ 또는 $OPENCLAW_STATE_DIR/extensions/<pluginId>/
  • OpenClaw는 npm pack 후 해당 디렉터리에서 npm install --omit=dev를 실행
  • lifecycle script가 설치 중에 코드를 실행할 수 있음
  • 가능하면 pinned exact version을 쓰고, 활성화 전에 unpacked code를 검토

​

DM access model (pairing / allowlist / open / disabled)

• pairing (기본값): 모르는 발신자에게 짧은 pairing code를 보내고, 승인 전까지 메시지를 무시
• allowlist: 모르는 발신자를 즉시 차단
• open: 누구나 DM 가능. 반드시 channel allowlist에 "*"가 있어야 함
• disabled: inbound DM 전체 무시

openclaw pairing list <channel>
openclaw pairing approve <channel> <code>

​

DM session isolation (multi-user mode)

{
  session: { dmScope: "per-channel-peer" },
}

​

Secure DM mode (recommended)

• 기본값: session.dmScope: "main" (모든 DM이 하나의 session 공유)
• local CLI onboarding 기본값: 값이 비어 있으면 session.dmScope: "per-channel-peer"를 기록
• secure DM mode: session.dmScope: "per-channel-peer" (채널+발신자별로 분리된 DM context)

​

Allowlists (DM + groups) — terminology

• DM allowlist: direct message에서 누가 말할 수 있는지
  • dmPolicy="pairing"이면 승인 결과가 ~/.openclaw/credentials/의 account-scoped pairing allowlist store에 기록되고 config allowlist와 병합됩니다.
• Group allowlist: 어떤 group/channel/guild의 메시지를 받을지
  • 예: channels.whatsapp.groups, channels.telegram.groups, channels.discord.guilds, channels.slack.channels
  • groupPolicy="allowlist"와 groupAllowFrom으로 group 내부 발신자도 따로 제한 가능
  • group check는 먼저 allowlist/policy, 그다음 mention/reply activation 순서
  • bot 메시지에 대한 reply(암묵적 mention)도 groupAllowFrom 같은 sender allowlist를 우회하지 않음
  • dmPolicy="open", groupPolicy="open"은 마지막 수단으로만 사용

​

Prompt injection (what it is, why it matters)

• inbound DM을 pairing/allowlist로 잠그기
• group에서는 mention gating 사용
• untrusted content를 읽는 agent에서 runtime/fs/control-plane tool을 기본 deny
• 가능한 한 sandbox와 좁은 workspace scope 사용
• 강한 instruction-following model 사용

​

Unsafe external content bypass flags

• hooks.gmail.allowUnsafeExternalContent=true
• hooks.mappings[<index>].allowUnsafeExternalContent=true

​

Prompt injection does not require public DMs

• group allowlist 안의 사람이 악성 콘텐츠를 보낼 수 있음
• email, web page, attached doc, pasted transcript 모두 injection surface가 될 수 있음
• trusted sender라도 계정 탈취나 혼동된 지시를 통해 위험 입력을 보낼 수 있음

​

Model strength (security note)

• 작은 모델은 악성 프롬프트와 role confusion에 더 쉽게 흔들릴 수 있음
• 위험한 tool surface가 열려 있으면 그 약점이 실질적 행동으로 이어질 수 있음
• 강한 모델도 안전하지는 않지만, 더 나은 방어선이 됨

​

Reasoning & verbose output in groups

• reply는 필요한 최소한으로 유지
• 민감한 config/path/token은 로그와 transcript에서 redaction
• 비신뢰 group에서는 control-plane 정보와 infra detail을 자세히 말하지 않게 설계

​

Configuration Hardening (examples)

​

0) File permissions

• ~/.openclaw는 보통 700
• openclaw.json, auth profile, credential file은 보통 600
• 다른 사용자나 프로세스가 읽거나 쓸 수 없도록 유지

​

0.4) Network exposure (bind + port + firewall)

• 가능하면 gateway.bind: "loopback" 유지
• LAN, tailnet, custom bind를 쓴다면 auth를 반드시 설정
• 공개 포트 노출보다 reverse proxy + auth + firewall 조합 선호

​

0.4.1) Docker port publishing + UFW (DOCKER-USER)

• 필요하지 않은 port publish 금지
• UFW를 쓴다면 Docker와 함께 실제로 차단되는지 확인
• container bind와 published port를 최소화

​

0.4.2) mDNS/Bonjour discovery (information disclosure)

• 일반적으로 최소 모드 사용
• 불필요하면 discovery 자체를 끄기
• LAN 전체가 신뢰되지 않는다면 full mode는 피하기

​

0.5) Lock down the Gateway WebSocket (local auth)

• local process도 인증을 요구
• dashboard나 Control UI도 같은 auth 경계를 사용
• “로컬이니까 auth를 끈다”는 습관을 피할 것

​

0.6) Tailscale Serve identity headers

• proxy header를 어디까지 신뢰할지 명확히 설정
• tailnet 노출과 public exposure를 혼동하지 않기
• Serve/Funnel은 운영자 접근 경계의 일부로 다루기

​

0.6.1) Browser control via node host (recommended)

• 개인 세션/쿠키와 분리
• 업무 전용 계정만 로그인
• 가능한 경우 sandboxed browser와 별도 device 사용

​

0.7) Secrets on disk (what’s sensitive)

• gateway token/password
• model provider API key
• OAuth credential material
• auth profile
• plugin이나 helper가 추가로 쓰는 local secret file

​

0.8) Logs + transcripts (redaction + retention)

• logging.redactSensitive를 켜기
• 보존 기간을 필요한 만큼만 유지
• transcript가 disk에 남는다는 점을 운영자와 팀이 이해하도록 하기

​

1) DMs: pairing by default

​

2) Groups: require mention everywhere

​

3) Separate Numbers

​

4) Read-Only Mode (Today, via sandbox + tools)

• filesystem tool deny
• sandbox 활성화
• workspaceAccess: "ro" 또는 "none"
• runtime/control-plane tool deny

​

5) Secure baseline (copy/paste)

{
  session: { dmScope: "per-channel-peer" },
  tools: {
    profile: "messaging",
    deny: ["group:automation", "group:runtime", "group:fs", "gateway", "cron", "sessions_spawn", "sessions_send"],
    fs: { workspaceOnly: true },
    elevated: { enabled: false },
  },
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

​

Sandboxing (recommended)

• non-main 또는 all 모드 고려
• write가 필요 없으면 workspace를 read-only 또는 none으로
• bind mount는 최소화
• elevated는 예외 상황에서만

​

Sub-agent delegation guardrail

• 비신뢰 콘텐츠를 다루는 agent에는 runtime/fs/control-plane tool을 기본 제한
• delegation이 늘수록 session 수, tool path, memory path가 함께 늘어난다는 점 고려
• group/session spawn 권한은 쉽게 열지 않기

​

Browser control risks

• 로그인된 세션, intranet, local admin panel에 접근할 수 있음
• browser automation은 SSRF-like pivot이 될 수 있음
• 개인 브라우저 프로필을 재사용하지 않는 것이 좋음

​

Browser SSRF policy (trusted-network default)

• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork는 정말 필요할 때만 사용
• 내부 admin panel이나 metadata endpoint에 agent가 닿지 않도록 설계

​

Per-agent access profiles (multi-agent)

• 대화 전용 agent
• 읽기 전용 도구 agent
• 강한 coding/runtime agent
• 브라우저 전용 agent

​

Example: full access (no sandbox)

{
  agents: {
    list: [
      {
        id: "trusted-work",
        tools: { profile: "coding" },
        sandbox: { mode: "off" },
      },
    ],
  },
}

​

Example: read-only tools + read-only workspace

{
  agents: {
    list: [
      {
        id: "readonly-review",
        tools: {
          allow: ["read", "browser"],
        },
        sandbox: {
          mode: "all",
          workspaceAccess: "ro",
        },
      },
    ],
  },
}

​

Example: no filesystem/shell access (provider messaging allowed)

{
  agents: {
    list: [
      {
        id: "chat-only",
        tools: {
          profile: "messaging",
          deny: ["group:runtime", "group:fs", "gateway", "cron"],
        },
      },
    ],
  },
}

​

What to Tell Your AI

• 낯선 사람에게 filesystem이나 secret를 노출하지 말 것
• permission boundary를 넘지 말 것
• group에서는 최소 권한으로 행동할 것
• 확실하지 않으면 실행보다 질문을 선택할 것

​

Security Rules

• 먼저 사람과 surface를 제한하고, 나중에 도구를 연다
• open group과 powerful tool 조합을 피한다
• 개인 계정과 공유 계정을 섞지 않는다
• plugin, skill, browser profile은 trusted code / trusted state로 본다
• auth, sandbox, allowlist는 “있으면 좋은 것”이 아니라 기본선이다

​

Incident Response

​

Contain

• gateway 프로세스를 즉시 중지
• network exposure 차단
• 관련 node/browser session 분리

​

Rotate (assume compromise if secrets leaked)

• gateway token/password 교체
• model API key/OAuth credential 회전
• 채널 bot token과 기타 secret도 교체

​

Audit

• openclaw security audit --deep 실행
• session log, transcript, command history를 검토
• 어떤 surface가 열려 있었는지 재구성

​

Collect for a report

• 재현 절차
• 관련 config
• 영향 범위와 노출된 secret 목록
• 수정 후 재검증 결과

​

Secret Scanning (detect-secrets)

• commit 전에 secret scanner 실행
• plaintext credential이 auth profile이나 .env에 남지 않았는지 확인
• generated file도 함께 점검

​

If CI fails

• 노출된 secret를 즉시 revoke
• 파일에서 제거 후 새 값으로 교체
• 필요한 경우 이력 정리와 추가 보고 수행

​

Reporting Security Issues