Codex Handoff 상세 가이드 — 로컬, Worktree, 원격 호스트 간 채팅 이동 시 포함되는 항목 (2026)

Handoff는 두 단계에 걸쳐 도입되었습니다. 먼저 2026년 3월 초에 로컬과 Worktree 간의 채팅 이동 기능이 추가되었습니다. OpenAI의 주간 요약에 따르면 이 기능은 "컨텍스트를 유지하면서 활성 채팅을 이동할 수 있게" 해주었습니다. 이어서 6월에는 호스트 간 채팅 이동 기능이 추가되었습니다: "채팅 handoff는 로컬 컴퓨터와 연결된 원격 호스트 간에 채팅과 Git 상태를 이동시킵니다."

로컬과 Worktree

worktree는 저장소의 두 번째 체크아웃입니다. OpenAI의 worktree 페이지는 이 관계를 다음과 같이 설명합니다: "로컬을 포그라운드로, Worktree를 백그라운드로 생각할 수 있습니다. Handoff를 통해 이 둘 사이에서 채팅을 이동할 수 있습니다."

채팅을 포그라운드로 가져오려면 채팅 헤더에서 Hand off를 선택하고 로컬로 이동합니다. 반대로 로컬에서 worktree로 채팅을 이동하여 사용자가 다른 작업을 하는 동안 Codex가 계속 작업하도록 할 수도 있습니다.

Handoff가 중요한 이유 중 하나는 Git의 규칙 때문입니다. worktree 페이지의 설명에 따르면: "Git은 한 번에 한 곳에서만 브랜치를 체크아웃할 수 있도록 허용합니다." Handoff는 Git 단계를 대신 처리해주므로, 로컬에서 작업을 확인하고 싶을 때 이러한 제약에 부딪히지 않게 해줍니다.

한 가지 디테일 덕분에 왕복 이동이 간편해집니다: "각 채팅은 시간이 지나도 동일한 관련 worktree를 유지합니다. 나중에 채팅을 다시 worktree로 넘기면, Codex는 해당 백그라운드 환경으로 채팅을 되돌려 중단했던 지점부터 다시 시작할 수 있게 합니다."

호스트 간 이동

원격 호스트는 SSH 호스트와 같이 데스크톱 앱이 연결되는 다른 컴퓨터입니다. 원격 연결 페이지에서는 다음과 같은 사용 사례를 설명합니다: "로컬에서 작업을 시작하고, 원격 컴퓨터의 worktree에서 계속 진행한 다음, 나중에 채팅을 다시 가져올 때 사용하세요."

채팅을 열고 채팅 푸터에서 현재 실행 위치를 선택한 다음, 대상 호스트를 선택하고 대상 및 브랜치를 확인한 후 Hand off를 선택합니다. OpenAI에 따르면, 반대편에서 "Codex는 대상 호스트에 worktree를 생성하거나 재사용하고, 채팅 및 Git 상태를 전송하며, 채팅을 해당 호스트로 전환합니다."

대화 내용. 채팅 자체가 이동하므로 다음 메시지에서 동일한 스레드를 이어갈 수 있습니다. 작업을 다시 설명할 필요가 없습니다.

Git 상태. Handoff는 두 체크아웃 간의 Git 작업을 처리합니다. 원격 호스트의 경우 OpenAI는 "채팅과 Git 상태"를 전송한다고 명시합니다.

되돌아가는 링크. worktree의 경우 각 채팅은 동일한 worktree를 유지하므로, 다시 넘기면 해당 환경으로 돌아갑니다.

이 섹션은 첫 번째 handoff를 수행하기 전에 반드시 읽어볼 가치가 있습니다.

무시된 파일 (Ignored files)

Handoff는 Git을 사용하기 때문에 Git이 무시하는 파일은 함께 이동하지 않습니다. worktree 페이지에는 다음과 같이 명시되어 있습니다: "Handoff는 Git 작업을 사용하므로, Codex가 .worktreeinclude를 통해 로컬 관리형 worktree로 복사하지 않는 한 .gitignore 파일에 포함된 모든 파일은 채팅과 함께 이동하지 않습니다."

여기에는 .env 파일이나 로컬 비밀 키 등이 포함됩니다. 저장소 루트에 있는 .worktreeinclude 파일은 Codex가 관리형 worktree를 생성할 때 복사해야 할 무시된 경로들을 나열합니다. OpenAI는 이 동작이 "원격 worktree나 명령줄에서 직접 생성한 Git worktree가 아닌, 로컬 ChatGPT 데스크톱 앱 관리형 worktree에만 적용된다"고 언급합니다. 원격 호스트의 경우, 해당 파일들을 직접 설정해야 합니다.

한 가지 예외가 내장되어 있습니다: "Codex는 무시된 AGENTS.override.md 파일을 로컬 관리형 worktree로 자동으로 복사하므로, .worktreeinclude에 나열할 필요가 없습니다."

다른 머신의 설정

채팅이 원격 호스트로 이동하면 해당 호스트의 환경에서 실행됩니다. 원격 연결 페이지는 이것이 일반적으로 무엇을 의미하는지 명확히 설명합니다: "원격 액세스는 연결된 호스트의 프로젝트, 채팅, 파일, 자격 증명, 권한, 플러그인, Computer Use, 브라우저 설정 및 로컬 도구를 사용합니다."

따라서 handoff 이후에 사용할 수 있는 플러그인, 자격 증명 및 도구는 노트북에 있는 것이 아니라 대상 호스트에 있는 것들입니다.

기억(Memories) 및 개인 지침

Codex의 기억(memories)은 머신에 종속됩니다. 기억 페이지에서는 이 설정을 "선택한 머신에 대해 기능을 켜거나 끄는 것"으로 설명하며, 기억 파일은 해당 머신의 ~/.codex/memories/ 아래에 저장됩니다. IDE 확장 프로그램도 동일한 패턴을 따릅니다: "연결된 Codex 호스트의 로컬 기억 저장소를 사용합니다."

전역 지침(global instructions)도 같은 방식으로 작동합니다. Codex는 실행 중인 머신의 Codex 홈 디렉토리(기본값 ~/.codex)에서 전역 가이드를 읽습니다.

Handoff 문서에는 호스트 간에 기억이나 전역 AGENTS.md를 복사하는 것에 대한 설명이 없습니다. 따라서 채팅이 원격 호스트로 이동한 후에는 해당 호스트의 기억과 전역 지침(있는 경우)에 따라 작동할 것으로 예상해야 합니다. Git에 커밋된 저장소의 AGENTS.md는 양쪽 모두에 존재합니다.

문서에는 몇 가지 제한 사항이 나열되어 있습니다.

• 일치하는 프로젝트가 필요합니다. "채팅을 넘기기 전에 대상 호스트를 연결하고 해당 호스트의 동일한 Git 저장소에 대한 프로젝트를 저장하세요." 프로젝트가 하위 디렉토리인 경우 양쪽 호스트에 동일한 하위 디렉토리를 저장해야 합니다. "Codex는 일치하는 저장된 프로젝트가 있는 대상만 표시합니다."
• 실행 중인 작업을 중단합니다. "채팅이 실행 중인 경우, handoff는 전송 전에 현재 응답을 중단합니다."
• 클라우드로 이동하지 않습니다. 다른 채팅에서 Codex에게 특정 채팅을 넘겨달라고 요청할 수 있지만, "Codex는 요청을 하는 채팅 자체를 넘길 수는 없으며, Codex 클라우드 환경으로의 handoff는 지원되지 않습니다."
• 하나의 브랜치는 한 곳에서만. '여기에서 브랜치 생성'으로 worktree에서 브랜치를 생성하면 로컬에서 동시에 체크아웃할 수 없습니다. OpenAI의 조언: "브랜치를 로컬에서 체크아웃할 계획이라면, 동일한 브랜치를 양쪽에서 동시에 체크아웃하려고 시도하는 대신 Handoff를 사용하여 채팅을 로컬로 이동하세요."

OpenAI의 클라우드에서 작업을 실행하고 싶다면, 프로젝트 컨텍스트를 포함하여 Codex 클라우드 환경을 준비하는 가이드를 참고하세요.

다른 머신에서 새 채팅 시작하기. 작동은 하지만 대화의 흐름을 잃게 되고 처음 몇 개의 메시지를 상황 설명에 소비하게 됩니다.

worktree의 브랜치를 로컬에서 체크아웃하기. 브랜치가 이미 worktree에서 체크아웃되어 있기 때문에 Git이 거부합니다. Handoff가 권장되는 경로입니다.

원격 호스트가 로컬 설정을 가지고 있을 것이라 기대하기. 원격 호스트에서 채팅은 노트북의 설정이 아닌 해당 호스트의 파일, 플러그인, 자격 증명 및 기억을 사용합니다.

작업 도중에 실행 중인 채팅 넘기기. Handoff는 현재 응답을 먼저 중단하므로, 작업이 멈출 수 있는 지점까지 기다리는 것이 좋습니다.

1단계: 넘기기 전에 대상 환경 준비하기

worktree의 경우, .env 파일과 같이 새 체크아웃에 필요한 무시된 파일들을 나열한 .worktreeinclude 파일을 추가하세요. 원격 호스트의 경우, 호스트를 연결하고 동일한 저장소에 대한 프로젝트를 저장한 다음 환경(무시된 파일, 자격 증명, 플러그인 및 의존하는 전역 지침)을 설정하세요. 기억 기능을 사용하는 경우 해당 호스트에서도 사용할지 결정하세요. 기억 페이지에서 머신별로 기능을 켜는 방법을 확인할 수 있습니다.

2단계: 채팅이 중단 지점에 도달했을 때 넘기기

현재 응답이 끝날 때까지 기다리세요. 그런 다음 Codex에게 현재 상황(완료된 작업, 다음 단계, 진행 과정에서 내린 결정 사항)에 대한 짧은 요약을 요청하세요. 이 요약은 채팅 내용에 포함되어 함께 이동하므로, 반대편 머신의 채팅에 명확한 시작점을 제공합니다. 그 다음 Hand off를 사용하세요.

3단계: 반대편에서 채팅이 무엇을 볼 수 있는지 확인하기

handoff 후, Codex에게 현재 따르고 있는 지침을 요약하고 프로젝트를 실행할 수 있는지 확인해달라고 요청하세요. 무언가 빠졌다면 대개 무시된 파일, 자격 증명 또는 다른 머신에 있는 전역 지침인 경우가 많습니다. 대상 환경에서 이를 수정하고 계속 진행하세요. Codex가 AGENTS.md 규칙을 건너뛰지 않도록 하는 가이드에서 지침 확인에 대해 더 자세히 다룹니다.

Handoff는 채팅과 코드를 이동시킵니다. 작업 주변의 컨텍스트, 즉 선호하는 작업 방식, 결정된 사항, 프로젝트 컨벤션 등은 일부는 채팅에, 일부는 특정 머신의 파일에, 그리고 일부는 해당 머신에 남는 기억에 흩어져 있습니다.

MemoryLake는 이러한 컨텍스트를 사용자가 관리하는 하나의 리스트로 유지하여 Codex 및 연결된 다른 어시스턴트(ChatGPT, Claude Code 등)에서 사용할 수 있게 해주는 기억 레이어입니다.

사용자는 자신의 언어로 직접 항목을 작성합니다. Codex 채팅, Codex 기억, worktree, 원격 호스트 또는 공급업체의 저장소에서 데이터를 읽거나 쓰거나 삭제하지 않습니다. 업무용 저장소의 경우, 외부에 보관하는 내용에 대해 조직의 정책을 따르세요.

1단계: API 키 생성

로그인 후 대시보드에서 키를 생성합니다. 이 키는 MemoryLake 워크스페이스에 속하며 ChatGPT 계정과는 별개입니다.

2단계: 첫 번째 기억 업로드

해결책 2단계의 요약 내용과 각 호스트에서 매번 다시 설정해야 했던 컨벤션부터 시작하세요. 항목당 하나의 포인트를 작성하고 날짜를 기입하며 해당되는 저장소 라벨을 붙입니다.

3단계: AI 및 에이전트 연결

Codex와 사용하는 다른 어시스턴트를 연결하세요. 노트북, 원격 호스트, 그리고 채팅이 도달하는 모든 체크아웃에서 동일한 컨텍스트를 사용할 수 있습니다.

첫 번째 차이점은 채팅 이동이 더 이상 도박이 아니라는 점입니다. 대화와 Git 상태가 함께 이동한다는 것을 알고 있으며, 어떤 로컬 요소가 이동하지 않는지도 알고 있습니다.

두 번째는 도착하기 전에 대상 환경이 준비되어 있다는 점입니다. 무시된 파일이 나열되어 있고, 원격 프로젝트가 저장되어 있으며, 의존하는 설정이 이미 갖춰져 있습니다.

세 번째는 중요한 컨텍스트가 채팅이 실행되는 머신에 의존하지 않는다는 점입니다. 채팅을 넘기는 것이 아니라 컴퓨터를 완전히 새로 옮기는 경우라면, Codex 설정을 새 컴퓨터로 마이그레이션하는 가이드에서 전체 이동 과정을 다룹니다.

백그라운드 작업에는 worktree를, 확인 작업에는 로컬을 사용하세요. 이것이 Handoff가 설계된 핵심 방식입니다.

무시된 설정 파일들을 .worktreeinclude에 나열하세요. 그렇지 않으면 원래 위치에 남게 됩니다.

모든 호스트에 일치하는 프로젝트를 저장하세요. Handoff는 프로젝트가 저장된 대상만 표시합니다.

중단 지점에서 넘기세요. 실행 중인 응답은 중단됩니다.

이동하기 전에 요약을 요청하세요. 요약 내용은 채팅과 함께 이동하여 반대편에서 도움이 됩니다.

머신별로 기억을 설정하세요. Codex는 머신별로 기억을 설정합니다. Codex 로컬 기억을 켜는 가이드에서 설정 방법을 확인하세요.

하나의 브랜치를 두 곳에서 체크아웃하지 마세요. 대신 Handoff를 사용하여 채팅을 이동시키세요.

Codex Handoff는 로컬 체크아웃과 worktree 사이, 또는 컴퓨터와 연결된 원격 호스트 사이에서 채팅과 Git 상태를 이동시킵니다. 이는 새로운 대화를 시작하지 않고도 백그라운드 작업을 포그라운드로 가져오거나 작업을 다른 머신으로 보내는 방법입니다.

.worktreeinclude가 로컬 관리형 worktree로 복사하지 않는 한 무시된 파일은 이동하지 않으며, 원격 호스트에서는 해당 호스트의 플러그인, 자격 증명, 기억 및 전역 지침을 사용합니다. Codex 클라우드 환경으로의 handoff는 불가능합니다. 대상 환경을 준비하고, 중단 지점에서 넘기고, 도착 시 채팅이 무엇을 볼 수 있는지 확인하세요. Claude Code도 함께 사용한다면, Claude Code worktree가 기억을 공유하는지에 대한 가이드에서 해당 측면의 내용을 확인해 보세요.