macOS 접근성 API(AXUIElement)를 쓰면 앱을 맨 앞으로 가져오지 않고도 버튼을 누르고, 메뉴를 열고, 스크롤을 움직일 수 있습니다. 제가 같은 Mac 으로 다른 일을 하는 동안 자동화가 화면을 빼앗지 않게 하려고 작은 Swift CLI 를 만들면서 배운 것과, 생각보다 자주 부딪힌 함정을 정리한 기록입니다.

처음 문제는 단순했습니다. 데스크톱 앱 하나에서 반복 작업을 자동화하고 싶었는데, 흔히 쓰는 방식은 앱을 앞으로 띄운 뒤 키 입력이나 마우스 클릭을 흉내 내는 것입니다. 이 방식은 자동화가 도는 동안 사람이 컴퓨터를 쓸 수 없게 만듭니다. 사람이 친 글자가 대상 앱으로 들어갈 수도 있고, 반대로 자동화가 보낸 키가 사람이 쓰던 편집기로 들어갈 수도 있습니다. 결국 «자동화는 화면 뒤에서만 움직이고, 사람이 쓰는 화면은 건드리지 않는다»는 조건이 먼저라는 생각이 들었습니다.

먼저 밝혀 둘 것이 있습니다. 아래 내용은 macOS 27.0, Swift 6.3 환경에서 2026년 11월 8일부터 10일 사이에 직접 확인한 범위입니다. 대상 앱마다 접근성 트리 구조가 다르기 때문에, 특정 앱에서 된 동작이 다른 앱에서도 똑같이 된다고 보장하지는 못합니다. 화면 잠금 상태에서의 동작은 아직 확인하지 않았습니다. 글에 나오는 코드는 실제 도구의 식별자를 빼고 메모 앱을 예시로 다시 쓴 것이며, 컴파일러 타입 검사까지만 통과시켰습니다.

왜 접근성 API 인가: 키 입력 흉내와의 차이

macOS 에서 다른 앱을 조작하는 방법은 크게 세 갈래가 있습니다. 전역 키·마우스 이벤트를 만들어 보내는 방법, AppleScript 같은 앱 스크립팅을 쓰는 방법, 그리고 접근성 API 로 앱의 UI 요소에 직접 동작을 거는 방법입니다.

방식 앱을 앞으로 올려야 하는가 사람의 입력과 겹치는가 대상 앱의 협조가 필요한가
전역 키·마우스 이벤트 대체로 그렇습니다 겹칩니다(포커스·커서를 공유) 필요 없습니다
앱 스크립팅(AppleScript) 명령에 따라 다릅니다 덜 겹칩니다 스크립팅 사전을 제공하는 앱만 됩니다
접근성 API(AXUIElement) 동작에 따라 필요 없습니다 요소에 직접 걸어서 겹치지 않습니다 표준 UI 컴포넌트면 대부분 노출됩니다

전역 이벤트는 «지금 포커스를 가진 곳»에 입력이 들어간다는 전제 위에 서 있습니다. 그래서 대상 앱이 맨 앞에 있어야 하고, 그 순간 사람은 손을 떼야 합니다. 반면 접근성 API 는 «이 창의 이 버튼»이라는 요소 객체에 동작을 겁니다. 포커스와 무관하게 대상이 정해져 있으니, 원리적으로는 앱이 뒤에 있어도 동작할 수 있습니다. 화면 낭독기(VoiceOver)가 앱을 다루는 통로와 같은 통로를 쓰는 셈입니다.

제가 만든 도구는 kax 라는 이름의 작은 Swift CLI 입니다. 하는 일은 단순합니다. 실행 중인 앱의 pid 로 앱 요소를 만들고, 창과 자식 트리를 역할·제목·식별자로 찾고, 찾은 요소에 동작을 겁니다. 이 글은 그 세 단계와, 각 단계에서 «화면을 빼앗지 않는다»는 조건을 지키기 위해 덧붙인 장치에 관한 이야기입니다.

요소 찾기: 경로가 아니라 «지금 이 순간의 유일한 항목»

접근성 트리는 앱 → 창 → 그룹 → 버튼처럼 이어지는 나무 구조입니다. 처음에는 한 번 찾은 요소의 경로(몇 번째 창의 몇 번째 자식)를 저장해 두고 재사용했습니다. 애석하게도 이 방식은 금방 깨졌습니다. 창이 하나 더 열리거나, 목록에 항목이 하나 늘거나, 시트가 떴다 사라지기만 해도 인덱스가 밀립니다. 어제 «세 번째 버튼»이던 것이 오늘은 전혀 다른 버튼일 수 있습니다.

그래서 원칙을 두 가지로 정했습니다. 첫째, 누르기 직전에 매번 다시 찾습니다. 둘째, 역할과 제목이 정확히 같은 항목이 딱 하나일 때만 누릅니다. 0개면 화면 상태가 예상과 다른 것이고, 2개 이상이면 어느 쪽인지 제가 고를 근거가 없습니다. 어느 경우든 멈추는 쪽이 맞다고 판단했습니다. 잘못된 버튼을 누르는 비용이, 한 번 멈추고 다시 확인하는 비용보다 훨씬 크기 때문입니다.

swift
import AppKit
import ApplicationServices

func attr(_ el: AXUIElement, _ name: String) -> AnyObject? {
    var value: AnyObject?
    return AXUIElementCopyAttributeValue(el, name as CFString, &value) == .success ? value : nil
}

func children(_ el: AXUIElement) -> [AXUIElement] {
    (attr(el, kAXChildrenAttribute as String) as? [AXUIElement]) ?? []
}

func findAll(in root: AXUIElement, role: String, title: String, depth: Int = 12) -> [AXUIElement] {
    var hits: [AXUIElement] = []
    func walk(_ el: AXUIElement, _ remaining: Int) {
        if attr(el, kAXRoleAttribute as String) as? String == role,
           attr(el, kAXTitleAttribute as String) as? String == title {
            hits.append(el)
        }
        guard remaining > 0 else { return }
        for child in children(el) { walk(child, remaining - 1) }
    }
    walk(root, depth)
    return hits
}

enum FindError: Error {
    case notFound
    case ambiguous(Int)
}

// 정확히 하나일 때만 돌려준다. 0개·2개 이상이면 호출한 쪽이 멈춘다.
func findExactlyOne(in root: AXUIElement, role: String, title: String) throws -> AXUIElement {
    let hits = findAll(in: root, role: role, title: title)
    guard !hits.isEmpty else { throw FindError.notFound }
    guard hits.count == 1 else { throw FindError.ambiguous(hits.count) }
    return hits[0]
}

guard AXIsProcessTrusted() else {
    fputs("이 터미널에 접근성 권한이 없습니다\n", stderr)
    exit(2)
}
guard let target = NSRunningApplication
    .runningApplications(withBundleIdentifier: "com.apple.Notes").first else {
    fputs("대상 앱이 실행 중이 아닙니다\n", stderr)
    exit(2)
}
let app = AXUIElementCreateApplication(target.processIdentifier)
AXUIElementSetMessagingTimeout(app, 3.0)   // 응답 없는 앱에 무한정 묶이지 않게

let windows = (attr(app, kAXWindowsAttribute as String) as? [AXUIElement]) ?? []
guard let window = windows.first else {
    fputs("창이 없어 배경 조작을 미룹니다\n", stderr)
    exit(3)
}

맨 아래의 «창이 없으면 미룬다»는 줄은 처음엔 없었습니다. 이 줄이 왜 필요한지는 뒤의 함정에서 다시 나옵니다.

화면 뒤에서 되는 동작들

요소를 찾았으면 동작을 겁니다. 직접 확인한 범위에서, 아래 동작들은 대상 앱을 활성화하지 않았습니다. 즉 제가 쓰던 앱이 계속 맨 앞에 있는 상태에서 뒤의 앱이 반응했습니다.

동작 API 쓰임
버튼 누르기 AXPress 버튼·체크박스·메뉴 항목
메뉴 열기 AXShowMenu 항목의 컨텍스트 메뉴를 띄움
값 설정 AXValue 쓰기 입력 칸 글자, 스크롤 막대 위치
속성 읽기 AXValue·AXTitle·AXHelp 등 텍스트, 도움말 풍선에 담긴 날짜, 이미지 요소의 데이터

읽기 쪽에서 의외였던 것은 AXHelp 입니다. 마우스를 올렸을 때 뜨는 도움말 풍선의 내용이 AXHelp 속성으로 노출되는데, 제가 다룬 앱은 여기에 날짜를 담아 두고 있었습니다. 덕분에 마우스를 움직이지 않고도 날짜를 읽을 수 있었습니다. 화면에 보이는 것과 접근성 트리에 담긴 것이 꼭 같지는 않다는 점을 여기서 처음 실감했습니다.

AXPress 를 맨 앞 앱 확인으로 감싸기

동작 자체는 한 줄입니다. 중요한 것은 그 한 줄의 앞뒤입니다. 누르기 전에 지금 맨 앞 앱이 무엇인지 보고, 누른 뒤에 바뀌지 않았는지 다시 봅니다. 대상 앱이 이미 맨 앞에 있다면 사람이 그 앱을 쓰고 있다는 뜻으로 보고 아예 누르지 않습니다.

swift
func frontPID() -> pid_t? {
    NSWorkspace.shared.frontmostApplication?.processIdentifier
}

// 0 성공 · 4 AX 동작 실패 · 5 사용자가 쓰는 중이라 미룸 · 7 맨 앞 앱이 바뀌어 중단
func pressInBackground(_ el: AXUIElement, targetPID: pid_t) -> Int32 {
    let before = frontPID()
    if before == targetPID { return 5 }
    let err = AXUIElementPerformAction(el, kAXPressAction as CFString)
    if frontPID() != before { return 7 }
    return err == .success ? 0 : 4
}

종료 코드를 일부러 잘게 나눴습니다. 호출하는 스크립트 입장에서 «실패했다»와 «사용자가 쓰고 있어서 미뤘다»와 «화면이 바뀌어 멈췄다»는 다음 행동이 전부 다릅니다. 미룬 것은 잠시 뒤 다시 시도하면 되고, 멈춘 것은 사람이 무슨 일이 있었는지 봐야 합니다. 하나의 실패 코드로 묶으면 이 구분이 사라집니다.

스크롤 막대 값으로 이전 내용 불러오기

가장 쓸모 있었던 것은 스크롤 막대의 AXValue 를 직접 바꾸는 동작입니다. 스크롤 막대는 0(맨 위)부터 1(맨 아래)까지의 값을 갖는데, 이 값을 쓰면 앱은 사람이 막대를 끌어 올린 것처럼 반응합니다. 위로 갈수록 이전 항목을 이어서 불러오는 목록이라면, 값을 0 에 가깝게 설정하는 것만으로 앱이 뒤에서 이전 내용을 불러옵니다. 휠 이벤트를 보낼 필요도, 커서를 그 위에 올릴 필요도 없습니다.

swift
func verticalScrollBar(in window: AXUIElement) -> AXUIElement? {
    for area in children(window) where attr(area, kAXRoleAttribute as String) as? String == "AXScrollArea" {
        if let bar = attr(area, kAXVerticalScrollBarAttribute as String),
           CFGetTypeID(bar) == AXUIElementGetTypeID() {
            return (bar as! AXUIElement)
        }
    }
    return nil
}

func setScroll(_ bar: AXUIElement, to fraction: Double) -> AXError {
    guard (0...1).contains(fraction) else { return .illegalArgument }
    return AXUIElementSetAttributeValue(bar, kAXValueAttribute as CFString,
                                        NSNumber(value: fraction))
}

다만 값을 쓴 직후에 내용이 다 불러와져 있다고 가정하면 안 됩니다. 앱은 뒤에서 비동기로 내용을 채웁니다. 그래서 저는 값을 쓴 뒤 잠깐 기다렸다가 스크롤 값을 다시 읽었고, 내용을 읽기 전과 읽은 뒤의 행 수·스크롤 값이 다르면 그 회차의 결과는 확정하지 않았습니다.

함정 1: 권한은 실행 파일이 아니라 터미널에 붙습니다

접근성 권한을 처음 다룰 때 가장 헷갈린 것은 권한이 어디에 붙느냐였습니다. 직관적으로는 직접 빌드한 실행 파일에 권한을 줘야 할 것 같지만, 실제로는 반대였습니다. 접근성 권한(최신 macOS 에서는 «기기 제어 및 데이터 접근»이라는 이름으로 바뀌었습니다)은 CLI 실행 파일이 아니라 그 CLI 를 띄운 터미널 호스트 앱에 귀속됩니다. 같은 실행 파일도 권한을 받은 터미널에서 띄우면 되고, 다른 터미널에서 띄우면 안 됩니다.

그래서 첫 동작을 하기 전에 반드시 AXIsProcessTrusted() 로 확인하고, 아니면 즉시 끝내도록 했습니다. 권한이 없어서 실패한 것과 요소를 못 찾아서 실패한 것을 섞지 않으려는 것입니다. 둘은 고치는 방법이 전혀 다릅니다.

하나 더 있습니다. 에이전트 CLI 를 샌드박스 모드(작업 폴더 쓰기만 허용하는 모드 같은 것)로 돌리면, 터미널에 권한이 있어도 접근성 호출이 막혔습니다. 권한 확인을 통과했는데도 아무것도 안 되는 경우라면 샌드박스 안에서 도는지부터 보는 것이 빠릅니다.

함정 2: 창이 0개면 «배경 실행»도 앞으로 올라옵니다

대상 앱의 창이 모두 닫혀 있으면 접근성 트리에 누를 대상이 없습니다. 그래서 처음엔 open -g 로 앱을 «배경에서» 다시 열어 창을 만들려고 했습니다. -g 는 이름 그대로 앱을 앞으로 가져오지 않는 옵션입니다.

그런데 창이 하나도 없는 상태에서는 -g 를 줘도 앱이 맨 앞으로 올라왔습니다. 앱이 «창이 없으면 새 창을 보여 준다»는 자체 동작을 하면서 스스로 활성화하는 것으로 해석했습니다. 이건 확인한 원인이 아니라 해석입니다. 어쨌든 결론은 분명했습니다. 창이 하나라도 열려 있을 때만 배경 조작이 안전합니다. 앞의 예제에서 창이 없으면 미루고 끝내는 줄이 이 함정에서 나왔습니다.

함정 3: 2~3초 뒤에 올라왔다 내려가는 지연 활성화

가장 오래 헤맨 것은 이 함정입니다. 저장 시트 같은 모달을 여는 버튼을 누르면, 누른 직후에는 맨 앞 앱이 그대로였습니다. 앞의 pressInBackground 도 성공을 돌려줬습니다. 그런데 2~3초쯤 뒤에 대상 앱이 잠깐 맨 앞으로 올라왔다가 다시 내려가는 경우가 있었습니다. 같은 Mac 으로 다른 일을 하던 사람 입장에서는, 그 몇 초 동안 화면을 빼앗긴 것입니다.

입력 직전과 직후에 맨 앞 앱을 확인하는 방식으로는 이걸 잡을 수 없습니다. 확인하는 두 시점 사이가 아니라 그 뒤에 일어나고, 내려갈 때는 원래 앱으로 돌아가서 «최종 상태»만 보면 아무 일도 없었던 것처럼 보이기 때문입니다. 돌이켜 생각해 보면, 시점 두 개를 찍는 검사는 시점 사이의 변화만 잡는다는 당연한 사실을 놓치고 있었습니다.

그래서 시점을 찍는 대신 활성화 알림을 계속 듣는 감시를 동작과 함께 걸었습니다. NSWorkspace.didActivateApplicationNotification 은 앱이 활성화될 때마다 오기 때문에, 잠깐 올라왔다 내려가도 기록이 남습니다.

swift
final class ActivationWatch {
    private(set) var stolen = false
    private var token: NSObjectProtocol?

    init(targetPID: pid_t) {
        token = NSWorkspace.shared.notificationCenter.addObserver(
            forName: NSWorkspace.didActivateApplicationNotification,
            object: nil, queue: .main
        ) { [weak self] note in
            let activated = note.userInfo?[NSWorkspace.applicationUserInfoKey] as? NSRunningApplication
            if activated?.processIdentifier == targetPID { self?.stolen = true }
        }
    }

    deinit {
        if let token { NSWorkspace.shared.notificationCenter.removeObserver(token) }
    }
}

// 동작을 건 뒤 seconds 동안 RunLoop 를 돌리며 알림을 처리한다.
func watchAfterAction(targetPID: pid_t, seconds: TimeInterval, _ action: () -> AXError) -> Int32 {
    let watch = ActivationWatch(targetPID: targetPID)
    let err = action()
    let deadline = Date().addingTimeInterval(seconds)
    while Date() < deadline {
        RunLoop.current.run(until: Date().addingTimeInterval(0.05))
        if watch.stolen { return 7 }   // 잠깐이라도 올라왔으면 다음 입력을 하지 않는다
    }
    return err == .success ? 0 : 4
}

여기서 놓치기 쉬운 부분은 RunLoop.current.run 입니다. CLI 는 앱과 달리 이벤트 루프가 저절로 돌지 않습니다. sleep 으로 기다리면 그동안 온 알림이 처리되지 않고, 감시를 걸어 둔 의미가 없어집니다. 짧게 끊어서 RunLoop 를 직접 돌려야 알림이 실제로 들어옵니다.

이 감시가 해 주는 것은 «화면을 빼앗은 사실을 알아채고 다음 입력을 멈추는 것»까지입니다. 이미 빼앗긴 그 순간을 되돌려 주지는 못합니다. 감시를 몇 초 동안 유지할지도 결국 관찰에서 나온 값이라, 더 늦게 올라오는 경우가 없다고 장담하지는 못합니다.

안전장치를 한곳에 모으기

함정을 하나씩 만나면서 안전장치가 늘었습니다. 동작마다 따로 붙이면 언젠가 빠뜨리는 곳이 생길 것이라, 모든 입력이 하나의 함수를 거치게 하고, 그 함수가 아래 규칙을 한꺼번에 지키게 했습니다.

  • 입력 전에 맨 앞 앱을 확인하고, 대상 앱이 이미 맨 앞이면 사용자가 쓰는 중으로 보고 미룹니다.
  • 입력 직후와 짧은 간격으로 몇 번 더 맨 앞 앱을 확인하고, 다른 앱이 앞에 오면 즉시 중단합니다.
  • 입력하는 동안 활성화 알림을 듣고, 대상 앱이 잠깐이라도 올라오면 후속 입력을 하지 않습니다.
  • 미룸·중단·실패를 서로 다른 종료 코드로 돌려줍니다.
  • 전역 키 입력, 실제 마우스 이동, 클립보드는 쓰지 않습니다.

마지막 줄은 규칙이라기보다 경계에 가깝습니다. 전역 키나 클립보드를 한 번이라도 쓰면 «사람과 공유하는 자원»을 건드리게 되고, 그 순간 화면 뒤에서 움직인다는 전제가 무너집니다. 접근성 API 로 안 되는 동작이 있으면 그 동작은 자동화하지 않는 쪽을 택했습니다. 조금 불편해도, 경계가 흐려지는 것보다는 낫다는 생각이 들었습니다.

한계: 접근성 트리에서 사라지는 창들

접근성 API 가 만능은 아니었습니다. 확인한 한계는 세 가지입니다.

첫째, 창을 다른 데스크톱(Space)으로 옮기면 그 창이 앱의 창 목록(AXWindows)에서 사라질 수 있습니다. 창이 살아 있어도 트리에 없으면 누를 수 없습니다. 둘째, 닫힌 창은 당연히 목록에 없고, 다시 열면 함정 2 로 돌아갑니다. 셋째, 화면이 잠긴 상태에서 이 동작들이 되는지는 아직 확인하지 않았습니다. 된다고도 안 된다고도 말할 수 없는 상태입니다.

그리고 트리 구조 자체가 앱 업데이트마다 바뀔 수 있습니다. 경로 대신 역할과 제목으로 찾는 이유가 여기에도 있지만, 제목마저 바뀌면 찾기가 0건이 됩니다. 이때 «못 찾았으니 멈춘다»가 기본 동작이라는 점이 오히려 다행이었습니다. 엉뚱한 것을 누르는 대신 조용히 멈추고 사람을 부르기 때문입니다.

마치며: 자동화의 예의

처음에는 «앱을 화면 뒤에서 조작할 수 있는가»라는 기술 질문으로 시작했습니다. 답은 생각보다 쉽게 «된다»였습니다. AXPress 한 줄이면 버튼이 눌렸습니다. 시간이 오래 걸린 쪽은 그다음 질문, «조작하는 동안 사람의 화면을 정말 한 번도 건드리지 않았는가»를 증명하는 일이었습니다.

곰곰이 생각해 보니, 같은 컴퓨터를 사람과 나눠 쓰는 자동화에게 필요한 건 능력보다 예의에 가깝다는 생각이 들었습니다. 사람이 쓰는 중이면 기다리고, 화면이 예상과 다르면 멈추고, 확신이 없으면 누르지 않는 것입니다. 이 글의 코드 대부분이 동작이 아니라 멈추는 조건으로 채워져 있는 것도 그 때문입니다. 비슷한 자동화를 만드실 분이 있다면, 동작을 거는 코드보다 멈추는 코드를 먼저 써 보시길 권합니다.

참고 자료

Apple Developer Documentation 의 AXUIElement(ApplicationServices 프레임워크)와 NSWorkspace.didActivateApplicationNotification(AppKit) 항목을 함께 보시면 위 코드의 각 호출이 무엇을 돌려주는지 확인할 수 있습니다.