Menu bar

기준일: 2026-07-26
공식 기준: Menu bar

Menu bar 문서는 OpenClaw 공식 문서(platforms/mac/menu-bar)를 한국어로 정리한 가이드입니다. Menu bar status logic and what is surfaced to users 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Menu bar status logic and what is surfaced to users

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

문서 구성

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

What is shown
State model
IconState enum (Swift)
ActivityKind -> badge symbol
Visual mapping
Context submenu
Status row text (menu)
Event ingestion
Debug override
Testing checklist
관련 문서

상세 내용

What is shown

주요 항목:

The current agent work state renders in the menu bar icon and in the first status row of the menu.
Health status is hidden while work is active; it returns once all sessions are idle.
A root "Context" item opens a submenu with recent sessions instead of expanding them in the root menu.
A "Nodes" block in the root menu lists paired devices only (from node.list), not client/presence entries.
A root "Usage" section appears below Context when provider usage snapshots are available, followed by cost details when available.
Quick Chat opens the floating main-session composer; its current global shortcut appears beside the item.

State model

주요 항목:

Source: WorkActivityStore (apps/macos/Sources/OpenClaw/WorkActivityStore.swift).
Events arrive as ControlAgentEvent with a runId; the handler (ControlChannel.routeWorkActivity) reads sessionKey from the event payload and defaults to "main" if absent.
Priority: the main session (sessionKey == "main" by default) always wins. If main is active, its state shows immediately. If main is idle, the most recently active non-main session shows instead. The store does not flip mid-activity; it only switches when the current session goes idle or main becomes active.
Activity kinds:
job: high-level command execution (state: started|streaming|done|error|...).
tool: phase: start|result with name, optional meta/args.

IconState enum (Swift)

주요 항목:

idle
workingMain(ActivityKind)
workingOther(ActivityKind)
overridden(ActivityKind) (debug override)

ActivityKind -> badge symbol

ActivityKind wraps a ToolKind (bash, read, write, edit, attach, other) or a bare job. Each maps to an SF Symbol badge drawn over the critter icon (IconState.badgeSymbolName):

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

Kind	Symbol
`bash`	`chevron.left.slash.chevron.right`
`read`	`doc`
`write`	`pencil`
`edit`	`pencil.tip`
`attach`	`paperclip`
`other` / `job`	`gearshape.fill`

Visual mapping

주요 항목:

idle: normal critter, no badge.
workingMain: badge with symbol, full tint (.primary prominence), leg "working" animation.
workingOther: badge with symbol, muted tint (.secondary prominence), no scurry.
overridden: uses the chosen symbol/tint regardless of real activity.

Context submenu

주요 항목:

The root menu shows one "Context" row with a session count/status; it opens a submenu (MenuSessionsInjector).
The submenu header shows the active session count for the last 24 hours.
Each session row keeps its token bar, age, preview, thinking/verbose toggle, reset, compact, and delete actions.
Loading, disconnected, and session-load error messages render inside the Context submenu.
Usage and cost sections stay root-level below Context so they remain glanceable without opening the submenu.

주요 항목:

While work is active: <Session role> · <activity label> ("\(roleLabel) · \(activity.label)" in MenuContentView), where role label is Main or Other.
When idle: falls back to the health summary.

Event ingestion

주요 항목:

Source: control-channel agent events, routed by ControlChannel.routeWorkActivity(from:).
Parsed fields:
stream: "job" with data.state for start/stop.
stream: "tool" with data.phase, data.name, optional data.meta/data.args.
Tool labels come from ToolDisplayRegistry.resolve(name:args:meta:); unresolved names fall back to the raw tool name.

Debug override

주요 항목:

Settings > Debug > "Icon override" picker:
System (auto) (default)
Working: main / Working: other (per tool kind: bash, read, write, edit, other)
Idle
Stored under UserDefaults key openclaw.iconOverride; mapped to IconState.overridden.

Testing checklist

주요 항목:

Trigger main session job: icon switches immediately and status row shows the main label.
Trigger non-main session job while main is idle: icon/status shows the non-main session; stays stable until it finishes.
Start main while another session is active: icon flips to main instantly.
Rapid tool bursts: badge does not flicker (2s grace window before clearing a finished tool, WorkActivityStore.toolResultGrace).
Health row reappears once all sessions are idle.

실습 체크리스트

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

Menu bar

기준일: 2026-07-26
공식 기준: Menu bar

핵심 요약

Menu bar status logic and what is surfaced to users

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

문서 구성

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

What is shown
State model
IconState enum (Swift)
ActivityKind -> badge symbol
Visual mapping
Context submenu
Status row text (menu)
Event ingestion
Debug override
Testing checklist
관련 문서

상세 내용

What is shown

주요 항목:

The current agent work state renders in the menu bar icon and in the first status row of the menu.
Health status is hidden while work is active; it returns once all sessions are idle.
A root "Context" item opens a submenu with recent sessions instead of expanding them in the root menu.
A "Nodes" block in the root menu lists paired devices only (from node.list), not client/presence entries.
A root "Usage" section appears below Context when provider usage snapshots are available, followed by cost details when available.
Quick Chat opens the floating main-session composer; its current global shortcut appears beside the item.

State model

주요 항목:

Source: WorkActivityStore (apps/macos/Sources/OpenClaw/WorkActivityStore.swift).
Events arrive as ControlAgentEvent with a runId; the handler (ControlChannel.routeWorkActivity) reads sessionKey from the event payload and defaults to "main" if absent.
Priority: the main session (sessionKey == "main" by default) always wins. If main is active, its state shows immediately. If main is idle, the most recently active non-main session shows instead. The store does not flip mid-activity; it only switches when the current session goes idle or main becomes active.
Activity kinds:
job: high-level command execution (state: started|streaming|done|error|...).
tool: phase: start|result with name, optional meta/args.

IconState enum (Swift)

주요 항목:

idle
workingMain(ActivityKind)
workingOther(ActivityKind)
overridden(ActivityKind) (debug override)

ActivityKind -> badge symbol

ActivityKind wraps a ToolKind (bash, read, write, edit, attach, other) or a bare job. Each maps to an SF Symbol badge drawn over the critter icon (IconState.badgeSymbolName):

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

Kind	Symbol
`bash`	`chevron.left.slash.chevron.right`
`read`	`doc`
`write`	`pencil`
`edit`	`pencil.tip`
`attach`	`paperclip`
`other` / `job`	`gearshape.fill`

Visual mapping

주요 항목:

idle: normal critter, no badge.
workingMain: badge with symbol, full tint (.primary prominence), leg "working" animation.
workingOther: badge with symbol, muted tint (.secondary prominence), no scurry.
overridden: uses the chosen symbol/tint regardless of real activity.

Context submenu

주요 항목:

The root menu shows one "Context" row with a session count/status; it opens a submenu (MenuSessionsInjector).
The submenu header shows the active session count for the last 24 hours.
Each session row keeps its token bar, age, preview, thinking/verbose toggle, reset, compact, and delete actions.
Loading, disconnected, and session-load error messages render inside the Context submenu.
Usage and cost sections stay root-level below Context so they remain glanceable without opening the submenu.

주요 항목:

While work is active: <Session role> · <activity label> ("\(roleLabel) · \(activity.label)" in MenuContentView), where role label is Main or Other.
When idle: falls back to the health summary.

Event ingestion

주요 항목:

Source: control-channel agent events, routed by ControlChannel.routeWorkActivity(from:).
Parsed fields:
stream: "job" with data.state for start/stop.
stream: "tool" with data.phase, data.name, optional data.meta/data.args.
Tool labels come from ToolDisplayRegistry.resolve(name:args:meta:); unresolved names fall back to the raw tool name.

Debug override

주요 항목:

Settings > Debug > "Icon override" picker:
System (auto) (default)
Working: main / Working: other (per tool kind: bash, read, write, edit, other)
Idle
Stored under UserDefaults key openclaw.iconOverride; mapped to IconState.overridden.

Testing checklist

주요 항목:

Trigger main session job: icon switches immediately and status row shows the main label.
Trigger non-main session job while main is idle: icon/status shows the non-main session; stays stable until it finishes.
Start main while another session is active: icon flips to main instantly.
Rapid tool bursts: badge does not flicker (2s grace window before clearing a finished tool, WorkActivityStore.toolResultGrace).
Health row reappears once all sessions are idle.

실습 체크리스트

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

Menu bar

핵심 요약

문서 구성

상세 내용

What is shown

State model

IconState enum (Swift)

ActivityKind -> badge symbol

Visual mapping

Context submenu

Status row text (menu)

Event ingestion

Debug override

Testing checklist

관련 문서

실습 체크리스트

관련 링크

관련 가이드

Menu bar

핵심 요약

문서 구성

상세 내용

What is shown

State model

IconState enum (Swift)

ActivityKind -> badge symbol

Visual mapping

Context submenu

Status row text (menu)

Event ingestion

Debug override

Testing checklist

관련 문서

실습 체크리스트

관련 링크

관련 가이드