Apple 문서는 xcodebuild를 Xcode 명령줄 도구로 안내합니다. 다만 명령이 실제로 실행되는 위치부터 판별하세요. OpenCode의 bash 도구는 프로젝트 실행 환경에서 동작하므로, SSH로 원격 Mac에 접속할 수 있다는 사실만으로 프로젝트 파일과 명령이 원격으로 옮겨가지는 않습니다. 원격 Mac에서 Xcode를 쓰려면 작업 공간과 실행 환경을 그곳에 두거나 SSH로 원격 명령을 명시적으로 실행하고, 파일 변경·빌드·테스트 결과를 각각 검증해야 합니다. OpenCode 도구 문서
이 글은 Windows 또는 Linux를 주 개발 환경으로 쓰면서 iOS나 macOS 프로젝트를 빌드하는 엔지니어를 위한 내용입니다.
원격 Mac CI를 운영하며 에이전트와 빌드 노드의 책임을 나눠야 하는 DevOps 엔지니어에게도 유용합니다.
OpenCode를 Apple 도구 체인에 연결하기 전, 권한과 완료 증거를 정리하려는 기술 담당자도 확인해 보세요.
마지막 검토: 2026년 10월 24일. OpenCode 공식 도구 문서와 변경 기록, Apple의 Xcode 명령줄 도구 및 테스트 문서를 기준으로 확인했습니다. OpenCode 변경 기록
01먼저 확인할 기준: 에이전트와 Xcode가 같은 실행 환경에 있는가
OpenCode 문서에서 bash 도구는 프로젝트 실행 환경 안에서 명령을 수행합니다. 따라서 프로젝트를 연 OpenCode가 Windows나 Linux에서 동작한다면, 그 안에서 실행한 명령도 원격 Mac에서 자동으로 실행된다고 가정하면 안 됩니다. SSH 접속 성공은 네트워크 연결을 확인할 뿐입니다. 에이전트의 파일 읽기와 명령 실행이 원격으로 전달되는지는 별도로 확인해야 합니다. OpenCode 도구 동작 안내
| 구성 | OpenCode 작업 공간 | 명령 실행 위치 | Xcode 사용 판단 |
|---|---|---|---|
| 로컬 작업 | Windows 또는 Linux | 로컬 환경 | 원격 Mac 접속만으로는 Xcode 빌드가 실행되지 않습니다 |
| 원격 작업 | 원격 Mac의 프로젝트 경로 | 원격 Mac | 파일과 명령이 같은 작업 환경을 보는지 확인합니다 |
| 명시적 원격 명령 | 로컬 작업 공간일 수 있음 | SSH로 지정한 원격 Mac | 파일 전송과 원격 명령의 대상 경로를 각각 확인합니다 |
OpenCode의 2.x 변경 기록은 공식 페이지에서 확인할 수 있습니다. 다만 특정 릴리스의 변경 내용만으로 네트워크 연결이나 프로젝트 이동 방식이 자동 제공된다고 추정하지 마세요. OpenCode 공식 변경 기록
02OpenCode bash 명령은 로컬과 원격 Mac 중 어디에서 실행됩니까?
OpenCode가 열린 프로젝트 작업 공간에서 간단한 확인 명령을 실행하고, 결과가 어느 호스트에서 나온 것인지 기록하세요. SSH 세션에서 실행한 결과와 OpenCode bash 도구의 결과는 별도로 비교해야 합니다.
예를 들어 OpenCode 도구에서 pwd와 git rev-parse --show-toplevel을 실행한 뒤, 원격 Mac에 SSH 접속해 같은 명령을 실행합니다. 두 결과가 다르면 같은 저장소를 보고 있지 않을 수 있습니다. 저장소 경로만으로 확정하지 말고, 변경 파일과 커밋도 함께 대조하세요.
작업 공간과 명령 위치를 나누어 기록합니다
아래 항목을 한 묶음으로 남기면 실행 위치를 혼동하기 어렵습니다.
- OpenCode가 연 프로젝트의 루트 경로
- OpenCode bash 도구에서 얻은 현재 경로와 호스트 정보
- 원격 Mac의 프로젝트 경로와 현재 커밋
- 각 환경에서 확인한 파일 변경 내역
SSH로 원격 명령을 호출하는 구조라면 그 명령이 읽고 쓰는 경로를 명시합니다. 로컬 파일을 편집하면서 원격 Mac의 오래된 복사본을 빌드하는 구조는 특히 주의해야 합니다. 빌드 성공 여부와 별개로, 결과가 현재 편집 중인 코드에서 나온 것인지 먼저 입증해야 합니다.
03프로젝트 파일이 다른 복사본에서 바뀌는 문제를 막는 방법
다음 점검은 빌드보다 먼저 진행합니다. 표의 결과가 하나라도 어긋나면 xcodebuild를 다시 실행하기보다 작업 공간을 맞추세요.
| 확인 항목 | OpenCode 환경 | 원격 Mac | 불일치 때의 대응 |
|---|---|---|---|
| 저장소 루트 | git rev-parse --show-toplevel 결과 |
같은 명령의 결과 | 의도한 저장소 경로로 작업 환경을 맞춥니다 |
| 커밋 | git rev-parse HEAD 결과 |
같은 명령의 결과 | 동일한 커밋을 체크아웃하거나 명시적으로 전송합니다 |
| 수정 파일 | git status --short 결과 |
같은 명령의 결과 | 편집된 복사본과 빌드 대상 복사본을 일치시킵니다 |
이 비교는 로컬과 원격이 반드시 같은 디렉터리여야 한다는 뜻은 아닙니다. 중요한 것은 빌드에 사용한 저장소가 편집한 변경 내용을 포함하고 있는지입니다. 임시 복사본이나 별도 브랜치를 쓰는 경우에도 커밋과 수정 내역으로 추적할 수 있어야 합니다.
04SSH는 되는데 원격 Mac에서 xcodebuild를 찾지 못할 때
원격 Mac에 접속한 계정에서 직접 도구 체인을 확인하세요. 로컬 개발기에서 xcodebuild가 동작하더라도 원격 계정의 설치 상태를 증명하지는 않습니다.
첫 단계: 원격 실행 계정과 개발자 디렉터리 확인
원격 Mac에서 다음 명령을 실행하고 결과를 작업 기록에 남깁니다.
whoami
pwd
xcode-select -p
xcodebuild -version
xcode-select -p는 현재 선택된 개발자 디렉터리를 확인하는 데 사용합니다. xcodebuild -version으로 원격 환경에서 명령을 찾을 수 있는지와 보고되는 버전을 살펴보세요. Apple은 Xcode 또는 명령줄 도구의 설치와 선택 상태를 별도 문서로 안내합니다. 명령줄 도구 설치 안내
명령이 없거나 기대한 디렉터리가 표시되지 않으면, OpenCode 설정을 바꾸기 전에 원격 Mac의 설치 상태와 실행 계정을 점검합니다. 계정마다 환경 변수나 셸 초기화 결과가 다를 수 있으므로, 관리자 세션에서 확인한 결과를 빌드 계정의 증거로 대신하지 마세요.
다음 단계: 실행 명령과 도구 체인을 연결해 확인
Apple의 명령줄 도구 문서에 xcodebuild가 포함되어 있습니다. Xcode 명령줄 도구 참고 문서와 원격 Mac의 실제 결과를 함께 확인하세요. 대상 프로젝트가 요구하는 SDK, scheme, 설정을 먼저 파악한 뒤 빌드 명령에 반영합니다. 로컬에서 선택된 Xcode 경로를 원격 환경의 상태로 간주하지 않는 것이 핵심입니다.
권한 오류는 저장소 접근, 비밀 정보, 파일 편집을 따로 봅니다
“권한 문제” 하나로 묶으면 필요한 접근 범위를 과하게 넓히기 쉽습니다. 오류 로그가 가리키는 계층을 먼저 나누세요.
- 저장소 읽기·쓰기: 원격 계정이 프로젝트 파일을 읽고 수정할 수 있는지 확인합니다.
- 비공개 의존성 접근: 저장소 접근 권한과 의존성 서버의 인증 정보가 별도로 필요한지 점검합니다.
- 서명 작업: 서명 자산과 키체인 접근은 일반 파일 편집 권한과 분리해 확인합니다.
- OpenCode 도구 권한: 에이전트가 명령을 실행하거나 파일을 편집할 수 있도록 허용된 범위를 확인합니다.
OpenCode는 도구 권한 설정을 문서화하고 있습니다. OpenCode 권한 설정 문서를 참고해 실제 작업에 필요한 도구만 허용하고, 실패 로그와 권한 규칙을 대조하세요. 프로젝트 전체나 사용자 계정의 접근 범위를 한 번에 넓히는 조치는 원인을 찾기 어렵게 만들고, 비밀 정보 노출 위험도 키웁니다.
원격 Mac 개발 환경을 처음 연결하거나 기존 접속 경로를 정리해야 한다면 VpsMesh의 원격 Mac 안내도 참고할 수 있습니다. 단, 안내된 접속 방식과 현재 프로젝트의 권한 정책이 맞는지는 별도로 검증해야 합니다.
06빌드 성공과 시뮬레이터 테스트 성공은 다른 결과입니다
xcodebuild가 빌드 작업을 마쳤다는 사실만으로 테스트가 실행됐다고 볼 수 없습니다. scheme, destination, 설치된 시뮬레이터 런타임이 테스트 대상과 맞는지 확인하세요. Apple은 시뮬레이터와 실제 기기에서 앱을 실행하는 절차를 안내합니다. 시뮬레이터 또는 실제 기기에서 실행하기
| 증상 | 우선 확인할 대상 | 판단 기준 |
|---|---|---|
| 빌드는 통과하지만 테스트가 시작되지 않음 | scheme과 테스트 대상 | 테스트를 포함하는 scheme인지 확인합니다 |
| 지정한 destination을 사용할 수 없음 | 기기 종류와 설치된 런타임 | 원격 Mac에서 해당 대상으로 실행할 수 있는지 확인합니다 |
| 테스트 명령은 끝났지만 결과를 찾지 못함 | 종료 상태와 결과 패키지 | 완료 여부와 결과 보존 여부를 분리합니다 |
테스트 실행 조건과 결과 해석은 Apple의 테스트 실행 및 결과 해석 안내를 기준으로 확인하세요. 시뮬레이터 목록이 비어 있거나 필요한 대상이 없다면 에이전트 실행 실패로 단정하지 말고, 원격 Mac의 설치 상태와 요청한 destination이 일치하는지 살핍니다.
07결과가 저장됐는지 확인하고 재실행을 결정합니다
테스트가 끝났다는 메시지만으로는 재현 가능한 결과를 확보했다고 보기 어렵습니다. 아래 순서로 증거를 모으세요.
- OpenCode가 실행한 명령과 실행 호스트를 기록합니다.
xcodebuild의 종료 상태를 확인하고, 로그에서 빌드와 테스트 단계를 구분합니다.- 테스트 명령에 결과 패키지 경로를 지정하고, 해당 경로가 원격 Mac에 실제로 생성됐는지 확인합니다.
- 결과 패키지를 열어 실행된 테스트와 최종 상태가 기대한 대상과 맞는지 살펴봅니다.
- 같은 커밋과 같은 대상 설정으로 다시 실행해 수정 결과를 판별합니다.
테스트 명령은 프로젝트에 맞는 scheme과 destination을 지정해야 합니다. 예를 들어 아래 형식처럼 결과 패키지 경로를 명시할 수 있지만, 인수와 경로는 실제 프로젝트 설정에 맞춰 바꿔야 합니다.
xcodebuild test \
-scheme "<scheme>" \
-destination "<destination>" \
-resultBundlePath "<결과_경로>"
Apple은 테스트 실행과 결과 해석 방법을 안내합니다. 테스트 결과 문서를 확인하고, 결과 패키지가 생성되지 않았다면 “테스트 통과”로 기록하지 마세요. 명령 종료 상태, 테스트 결과, 결과 파일의 존재가 모두 확인되면 수정 완료로 판단할 수 있습니다. 하나라도 불분명하면 같은 커밋으로 재실행하거나 실행 환경을 다시 점검하세요.
08현재 실행 방식과 원격 Mac 작업 공간의 선택 기준
| 선택 | 장점 | 주의점 | 적합한 경우 |
|---|---|---|---|
| 로컬 작업 공간 유지 | 편집 환경을 바꾸지 않아도 됩니다 | 파일 동기화와 원격 실행 경계를 직접 관리해야 합니다 | 이미 검증된 SSH 실행 및 동기화 절차가 있을 때 |
| 원격 Mac에서 작업 공간 실행 | 프로젝트 파일과 Apple 도구 체인을 같은 환경에서 확인하기 쉽습니다 | 원격 접속, 계정 권한, 편집 지연을 점검해야 합니다 | 반복적인 Xcode 빌드와 macOS CI 작업이 필요할 때 |
| 로컬 빌드만 사용 | 별도 원격 환경을 준비하지 않아도 됩니다 | 로컬에 Apple 도구 체인이 없으면 해당 작업을 수행할 수 없습니다 | Mac을 보유하고 있고 로컬 환경이 프로젝트 요구를 충족할 때 |
로컬에서 Apple 도구 체인을 제공할 수 없고, 반복 작업을 원격에서 재현해야 한다면 원격 Mac을 검토할 수 있습니다. 반대로 물리 기기 연결이나 로컬 장비에 종속된 작업이 핵심이라면 원격 환경이 적합하지 않을 수 있습니다. Mac mini 기반 원격 환경의 선택지를 살펴보려면 VpsMesh Mac mini 안내를 참고하고, 프로젝트의 실행 위치·권한·결과 보존 조건을 먼저 비교하세요.
Windows나 Linux에서 SSH와 별도 스크립트만으로 원격 실행을 이어가면 저장소 복사본 혼선, 계정별 도구 경로 차이, 결과 파일 누락을 계속 관리해야 합니다. 원격 Mac 작업 공간을 두면 이런 경계를 한곳에서 검증하기 쉬워지지만, 물리 기기가 꼭 필요하거나 장기간 상시 부하를 고정 운영해야 한다면 직접 보유하는 편이 더 맞을 수 있습니다. 일시적인 개발이나 테스트 환경이 필요하고 로컬에서 Apple 도구 체인을 제공할 수 없다면, 요구 조건을 확인한 뒤 VpsMesh의 원격 Mac 이용을 검토해 보세요. 먼저 작업 공간과 명령 실행 위치를 맞추고, 같은 커밋에서 xcodebuild와 테스트 결과 패키지까지 확인하는 것이 선택의 기준입니다.