Claude Code의 'Import other agent setup'은 CLI에서도 쓸 수 있나?

아니다. Import other agent setup은 Codex Mac 데스크톱 앱 전용 UI 버튼으로, CLI에는 동일한 명령이 없다. CLI 사용자는 CLAUDE.md를 직접 분류해서 AGENTS.md와 config.toml로 옮겨야 한다.

CLAUDE.md를 Codex로 그대로 복사해도 되나?

그대로 복사하는 것은 권장되지 않는다. CLAUDE.md 안의 권한 지시(allow/deny), hooks 설정은 Codex의 sandbox_mode·approval_policy·Rules 체계와 1:1로 맞지 않는다. 팀 컨벤션과 개인 취향만 AGENTS.md로 옮기고, 나머지는 config.toml과 .rules 파일로 재설정하는 것이 안전하다.

Smoke Test는 어떻게 시작하면 좋은가?

먼저 AGENTS.md 파일이 올바른 위치(~/.codex/AGENTS.md 또는 프로젝트 루트 AGENTS.md)에 있는지 확인한 뒤, read-only sandbox 모드로 Codex를 실행해 간단한 설명 요청을 해본다. 파일을 변경하지 않는 작업으로 sandbox와 approval 정책이 의도대로 작동하는지 검증하는 것이 핵심이다.

AI/Codex 기초 사용방법

Codex CLI 입문(7) : Claude Code 사용자를 위한 Codex 전환 가이드 - CLAUDE.md·슬래시 명령·MCP 완전 마이그레이션

안녕하세요! 갓대희 입니다.

Claude Code를 쓰다가 Codex로 갈아타려는 분을 위한 실전 이사 가이드입니다. Mac 데스크톱 앱의 자동 import 경로와 CLI 수동 경로 중 하나를 고른 뒤, CLAUDE.md를 세 줄기로 나눠 옮기고 5분 Smoke Test로 확인하는 흐름으로 설명합니다.

한 줄 결론

Mac 데스크톱 앱이면 "Import other agent setup" 한 번 클릭으로 시작한다.
CLI라면 CLAUDE.md를 개인 취향 / 팀 컨벤션 / 위험 지시 세 줄기로 나눠 옮긴 뒤, Smoke Test로 확인한다.

OpenAI Codex 개발자 시리즈

Part 1: CLI 빠른 시작 Part 2: 핵심 개념 4가지 Part 3: Subagents · Workflows Part 4: AGENTS.md · Rules Part 5: MCP · Plugins · Skills Part 6: 자동화 Part 7: 마이그레이션 (현재 글) Part 8: 슬래시 명령어 정리(예정)

이 글은 2026년 5월 15일 기준 OpenAI Codex 공식 문서와 Anthropic Claude Code 공식 문서를 바탕으로 작성되었다. 기능 이름과 설정 키는 계속 바뀔 수 있으므로 실제 이전 전에는 각 도구의 최신 문서를 다시 확인하자.

1. 먼저 경로를 고른다

마이그레이션 경로는 두 가지이다.

경로	언제 쓰나	무엇을 해주나	한계
경로 A Mac 앱 자동 import	Codex Mac 데스크톱 앱을 쓰는 경우	instructions·config·skills·MCP·hooks·subagents까지 일괄 가져오기 시도	tool 제한·MCP custom auth·plugins는 import 후 수동 검토 필요
경로 B CLI 수동 마이그레이션	CLI만 쓰거나 세밀하게 제어하고 싶은 경우	CLAUDE.md를 직접 분류해서 AGENTS.md + config.toml로 옮김	자동 변환 없음, 모든 매핑을 수동으로 해야 함

경로 A — Mac 앱 "Import other agent setup"

⚠ Mac 데스크톱 앱 전용

"Import other agent setup"은 Codex Mac 데스크톱 앱에만 있는 UI 버튼이다. CLI(codex 명령어)에는 동일한 import 명령이 없다. (출처: Codex Mac 앱 가이드 §9 — 같은 시리즈 본문 직접 확인)

사용 방법:

Codex Mac 앱 실행 → 설정(⚙) 열기
"다른 에이전트 설정 가져오기" 항목 확인 — Codex가 로컬 에이전트(Claude, Cursor, Continue 등)를 자동 감지해서 목록을 표시한다
가져오기 버튼 클릭 → 해당 도구의 시스템 프롬프트·규칙이 Codex 맞춤형 지침으로 전환된다
결과 검토: 자동 변환 내용이 의도와 맞는지 맞춤형 지침 화면에서 직접 확인한다

자동 import 후 반드시 검토해야 하는 것

자동 import가 시도되지만 그대로 신뢰하면 안 되는 항목이다. (출처: OpenAI Codex — Migrate to Codex)

import된 skills·subagents의 tool restrictions / permissions — Codex의 sandbox·approval·Rules와 의도대로 맞는지 검토 (§4 함정 ① 참고)
MCP 서버의 custom authentication · headers · env vars · transports — import 후 ~/.codex/config.toml 에서 직접 확인 (§5 접힘 박스 참고)
Claude Code 전용 plugins · marketplaces — Codex에 대응 기능 없으면 수동 후속 작업 필요

경로 B — CLI 수동 마이그레이션 핵심 매핑

CLI만 쓰거나 Mac 앱이 없는 환경이면 경로 A를 건너뛰고 아래 매핑 표만 참고한 뒤 §2로 이동하면 된다. CLI 경로는 아래 표를 기준으로 파일을 옮긴다.

Claude Code	Codex	한 줄 설명
`~/.claude/CLAUDE.md`	`~/.codex/AGENTS.md`	개인 전역 지침 (이름 호칭, 응답 스타일 등)
`.claude/CLAUDE.md`	`AGENTS.md` (프로젝트 루트)	팀 컨벤션, 코드 스타일 (Git 추적)
`~/.claude/settings.json`	`~/.codex/config.toml`	전역 설정 (sandbox, approval, model 등)
`.mcp.json`	`[mcp_servers.*]` in config.toml	MCP 서버 목록 (§5 접힘 박스 참고)
`hooks` in settings.json	`hooks` in config.toml	이벤트 훅 (§4 함정 ② + §5 접힘 박스 참고)
permission mode `default / acceptEdits / plan / auto`	`sandbox_mode` + `approval_policy` sandbox_mode: `read-only` / `workspace-write` / `danger-full-access` approval_policy: `untrusted` / `on-request` / `never` / `{ granular = {...} }`	§4 함정 ① 참고 — 1:1 대응 안 됨

2. CLAUDE.md를 세 줄기로 나눈다

CLAUDE.md를 한꺼번에 복사하지 말고 내용 유형별로 세 줄기로 분류한 뒤 각자 다른 곳으로 보낸다.

Step 1 — 개인 취향 → `~/.codex/AGENTS.md`

해당하는 내용: 이름 호칭, 응답 언어, 설명 스타일, "마지막 줄에 요약 추가해줘" 같은 개인 습관

목적지: 전역 사용자 지침 파일 — 내 모든 Codex 세션에 적용된다

# 터미널에서 실행
ls ~/.claude/CLAUDE.md # 없으면 이 단계 건너뜀
mkdir -p ~/.codex
cat ~/.claude/CLAUDE.md
# 개인 취향 부분만 복사해서 아래 파일에 붙여넣기
nano ~/.codex/AGENTS.md

💡 개인 취향 예시

응답은 한국어로 해줘
코드 변경 전에 한 줄로 계획 먼저 말해줘
파일 수정 후 변경 요약을 마지막에 덧붙여줘

Step 2 — 팀 컨벤션 → 프로젝트 루트 `AGENTS.md`

해당하는 내용: 코드 스타일, 브랜치 전략, 테스트 방침, 프레임워크 컨벤션

목적지: 프로젝트 루트 AGENTS.md — Git에 커밋해서 팀과 공유한다

# 프로젝트 루트에서 실행
ls .claude/CLAUDE.md # 없으면 이 단계 건너뜀
cat .claude/CLAUDE.md
# 팀 컨벤션 부분만 복사 → 아래 파일에 작성
nano AGENTS.md
git add AGENTS.md && git commit -m "chore: add Codex AGENTS.md"

trusted project 필수

프로젝트 루트 AGENTS.md는 trusted project에서만 자동 적용된다. 외부에서 clone한 프로젝트는 untrusted로 간주되어 프로젝트 설정이 무시된다. 자세한 신뢰 설정은 Part 4: AGENTS.md · Rules를 참고한다.

Step 3 — 위험 지시는 보류 또는 폐기

해당하는 내용: 권한 우회 지시, 자동 승인 설정, subagent 위임 설정, 실험적 플래그

처리 방침: 복사하지 말고 Codex의 sandbox·approval·Rules 체계로 새로 설계한다 (§4 함정 ① ③ 참고)

보류해야 할 지시 예시

allowedTools 목록 전체 (→ Codex Rules의 prefix_rule로 재설계)
bypassPermissions: true (→ Codex에선 sandbox 모드로 대응)
"subagent에게 모든 파일 접근 권한 줘" 류의 지시 (→ §4 함정 ③ 참고)

3. 5분 Smoke Test — 설정이 작동하는지 확인

설정을 옮긴 뒤 바로 실제 코드를 맡기지 말고, 아래 항목을 순서대로 확인한다.

파일을 바꾸지 않는 작업으로 sandbox와 approval 정책이 의도대로 작동하는지 검증하는 게 핵심이다.

전제: 2번 섹션의 결과물(~/.codex/AGENTS.md, 프로젝트 루트 AGENTS.md, ~/.codex/config.toml) 이 준비된 상태에서 시작한다.

Smoke Test 체크리스트

[ ] 1. AGENTS.md 위치 확인

ls ~/.codex/AGENTS.md            # 개인 지침
ls ./AGENTS.md                # 프로젝트 지침 (프로젝트 루트에서)

기대 결과: 두 파일 모두 존재하면 Codex가 세션 시작 시 자동으로 읽는다

[ ] 2. 첫 실행(읽기 작업만)

# 프로젝트 루트에서 실행해야 ./AGENTS.md가 적용됨
cd <프로젝트-루트>
codex # 실행 후 AGENTS.md 내용 요약해줘라고 요청

기대 결과: Codex가 AGENTS.md를 읽어 내용을 요약해 응답한다. 응답 스타일이 개인 지침을 따르는지 확인한다. 루트가 아닌 곳에서 실행하면 프로젝트 AGENTS.md가 적용되지 않으므로 응답에서 빠지면 위치를 다시 확인한다.

[ ] 3. sandbox 모드 확인

~/.codex/config.toml에 sandbox_mode = "workspace-write"가 있다면, 세션에서 파일 쓰기 요청 시 approval_policy대로 멈추는지 확인한다

# ~/.codex/config.toml 예시
sandbox_mode = "workspace-write"
approval_policy = "on-request"

기대 결과: 파일 쓰기 도구 호출 전에 "허용할까요?" 승인 요청이 뜬다

[ ] 4. MCP 연결 확인 (MCP를 옮긴 경우만)

# TUI 안에서 입력
/mcp # 연결된 MCP 서버 목록과 상태 확인
# 그 다음 MCP 도구 하나를 자연어로 호출 (예: "filesystem MCP로 현재 폴더 ls 해줘")

기대 결과: 정상이면 도구 응답이 반환된다. 실패하면 보통 auth · headers · env_vars · transport 중 하나의 import 누락이다 — config.toml의 [mcp_servers.*] 섹션을 §5 접힘 박스 기준으로 다시 점검한다.

[ ] 5. 첫 실제 작업 1개 완료

5-A (read-only 환경): "현재 디렉토리 구조 설명해줘" 같은 읽기 전용 탐색 1개
5-B (workspace-write 환경): 단순 파일 생성 1개 (예: test.md에 'hello' 한 줄 써줘) — approval 요청이 §3-3 기대대로 뜨는지 확인

4. 빠지기 쉬운 함정 3가지

마이그레이션 과정에서 자주 만나는 실수를 정리했다. 세 가지 모두 "Claude Code 방식을 그대로 이식하려는" 데서 생긴다.

함정 ① — permissions allow/deny를 AGENTS.md에 그대로 적지 말 것

잘못된 이식	Codex 방식
AGENTS.md에 `"파일 쓰기는 항상 허용"` 적기	config.toml에 `sandbox_mode = "workspace-write"` `approval_policy = "on-request"`
AGENTS.md에 `"git push는 금지"` 적기	`~/.codex/rules/default.rules`에 `prefix_rule(pattern=["git","push"], decision="forbidden")` (Part 4 참고)

왜?

Codex는 권한 제어를 자연어 지시로 처리하지 않고, sandbox(파일·네트워크 범위)와 approval(승인 시점)을 config.toml로, 명령별 허용·차단을 Rules로 분리한다.

AGENTS.md에 적은 권한 지시는 무시되거나 의도치 않게 작동할 수 있다.

함정 ② — hooks를 1:1로 이식하지 말 것

Claude Code	Codex	주의
`PreToolUse`	`PreToolUse`	이름 같음, 설정 위치 다름
`PostToolUse`	`PostToolUse`	이름 같음, 설정 위치 다름
`PreToolUse`로 도구 실행 차단	Codex도 가능 — PreToolUse hook이 `permissionDecision: "deny"` 반환 시 차단됨. 단, Rules가 정책 우선순위	⚠ hooks는 enforcement 경계가 아니라 보조 — 정책성 차단은 Rules에 두는 것이 안전

왜? Codex에서도 PreToolUse hook이 permissionDecision: "deny" 또는 exit code 2를 반환해 차단할 수 있다.

그러나 공식 문서는 hooks를 "단일 enforcement 경계로 의존하지 말 것"이라고 명시한다.

(출처: OpenAI Codex — Hooks)

역할 분리 — 이 두 줄만 기억하면 된다

Hook: 알림·로그·임시 검사 (예: PostToolUse에서 "테스트 자동 실행")
Rules: 영구·정책성 차단 (예: git push forbidden, 외부 도메인 접근 prompt)

hooks 상세는 §5 접힘 박스 참고.

함정 ③ — subagent의 tool 권한을 그대로 옮기지 말 것

먼저: Codex에도 Subagents가 있다. Mac 앱 import는 Claude의 subagent를 Codex의 subagent로 자동 가져온다. 다만 가져온 subagent의 tool restrictions·permissions는 import 후 반드시 검토해야 한다. (출처: OpenAI Codex — Migrate)

그대로 신뢰	검토 후 적용
import된 subagent의 allowedTools 목록을 그대로 신뢰하기	Codex Mac 앱: 설정 → Subagents 화면에서 열기. CLI: `~/.codex/agents/.toml` 또는 프로젝트 `.codex/agents/.toml` 파일을 열어 tool 권한과 sandbox 범위가 의도와 맞는지 확인
subagent가 임의로 외부 서비스를 호출하도록 두기	외부 서비스 호출은 MCP 서버로 옮기고 (Part 5), subagent는 작업 분담에만 사용

왜? Mac 앱 import는 subagent를 옮기지만, Claude Code와 Codex의 권한 모델이 다르기 때문에 import된 subagent가 의도보다 넓은 권한을 가질 수 있다.

import 후 Codex Subagents 설정을 열어 tool 권한·sandbox 범위를 직접 확인하는 절차가 필수다.

5. MCP · hooks · Rules — 이미 쓰는 팀만 열어보기

아래 세 섹션은 이미 Claude Code에서 MCP·hooks·규칙을 쓰고 있는 팀만 참고한다. 처음 마이그레이션하는 분은 §1~§4만으로 충분하다.

▶ MCP 서버 옮기기 (config.toml 형식)

.mcp.json (Claude Code) → config.toml [mcp_servers.*] (Codex)

# ~/.codex/config.toml 예시

[mcp_servers.filesystem]
  command = "npx"
  args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

[mcp_servers.github]
  command = "npx"
  args = ["-y", "@modelcontextprotocol/server-github"]
  env_vars = ["GITHUB_TOKEN"]

대안: config.toml을 직접 편집하지 않고 CLI로 추가할 수도 있다 — codex mcp add, codex mcp login, TUI에서는 /mcp.

MCP 스코프(읽기 전용·읽기쓰기), HTTP 서버 연결, 헤더 설정 등 상세 옵션은 Part 5: MCP · Plugins · Skills를 참고한다.

▶ hooks 이벤트 매핑 (이름과 위치 변경)

이벤트	Claude Code	Codex
도구 실행 전	`PreToolUse`	`PreToolUse`
도구 실행 후	`PostToolUse`	`PostToolUse`
승인 요청 시	`PermissionRequest`	`PermissionRequest` — 양쪽 공통
프롬프트 제출 시	`UserPromptSubmit`	`UserPromptSubmit`
세션 시작	`SessionStart`	`SessionStart`
세션 종료	`Stop`	`Stop`

# ~/.codex/config.toml — array of tables 구조
[[hooks.PreToolUse]]
  matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
  type = "command"
  command = "/usr/bin/python3 .codex/hooks/check.py"
  timeout = 30

주의: 단일 테이블([hooks.PreToolUse])이 아니라 array of tables([[hooks.PreToolUse]]) 구조다.

하나의 이벤트에 여러 hook을 등록할 수 있도록 설계됐다. (출처: OpenAI Codex — Hooks) hooks 상세 설정과 이벤트 페이로드는 Part 4: AGENTS.md · Rules를 참고한다.

▶ Rules prefix_rule — allow / prompt / forbidden

Codex Rules는 Starlark(Python 유사 안전 실행 언어)로 작성하며 파일은 ~/.codex/rules/*.rules에 둔다. Claude Code의 allowedTools(허용·거부 두 단계) 대신 Codex는 세 단계 결정을 쓴다.

결정값	의미	Claude Code 대응
`allow`	승인 없이 바로 실행	allowedTools 허용
`prompt`	매번 승인 요청	— (없음, Codex 추가 단계)
`forbidden`	완전 차단	allowedTools deny

# ~/.codex/rules/default.rules — Starlark 함수 호출
prefix_rule(
  pattern = ["git", "push"],
  decision = "forbidden",
  justification = "main 푸시는 차단",
)

주의: prefix_rule = "forbidden"처럼 TOML 키값 대입이 아니라 함수 호출 형태로 작성한다. pattern은 문자열 리스트, decision은 "allow" / "prompt" / "forbidden" 중 하나. (출처: OpenAI Codex — Rules)

작성 방법과 패턴 예시는 Part 4: AGENTS.md · Rules를 참고한다.

자주 묻는 질문

"Import other agent setup"은 CLI에서도 쓸 수 있나?

아니다. 이 기능은 Codex Mac 데스크톱 앱 전용 UI 버튼이다. CLI(codex 명령어)에는 동일한 import 명령이 없다. CLI 사용자는 §2의 3분류 단계에 따라 CLAUDE.md를 직접 분류해서 옮겨야 한다.

CLAUDE.md를 통째로 복사해도 되나?

권장하지 않는다. 권한 지시·hooks·subagent 설정은 Codex의 sandbox·approval·Rules 체계와 1:1로 맞지 않아서, 그대로 복사하면 무시되거나 의도치 않게 작동한다. §4 함정 ①②③을 먼저 확인하고 설계한 뒤 옮긴다.

마이그레이션 후 설정이 제대로 적용됐는지 어떻게 확인하나?

§3 Smoke Test 체크리스트를 순서대로 따라한다. AGENTS.md 위치 확인 → 간단한 설명 요청으로 지침 적용 여부 확인 → 파일 쓰기 요청으로 approval 정책 확인 순서다. 설정을 바꿔도 현재 세션에 바로 반영되지 않으므로, Rules·hooks 변경 후에는 새 세션을 열어 재확인해야 한다.

참고 자료

OpenAI Codex 공식 문서

Claude Code 공식 문서

같은 시리즈

작성일: 2026-05-06. 최종 수정: 2026-05-15. 공식 문서 기준. CLI 동작과 설정 키는 버전에 따라 변경될 수 있다.

저작자표시 비영리 변경금지 (새창열림)

'AI > Codex 기초 사용방법' 카테고리의 다른 글

Codex Mac App 가이드(2) : Codex App 원격 제어 방법 : 모바일 제어 부터 다른 기기 제어, SSH 원격 연결까지 (2)	2026.05.26
Codex CLI 입문(8) : 슬래시 명령어 정리 - Codex 슬래시 명령어 사용방법 (1)	2026.05.18
Codex CLI 입문(6) : Codex 자동화 파이프라인 구축 - 사람 없이 돌아가는 Codex (3)	2026.05.13
Codex CLI 입문(5) : Codex에 외부 도구 연결하기 - MCP, Plugin, Skill 사용법 (3)	2026.05.12
Codex CLI 입문(4) : AGENTS.md와 Rules 설정 방법 - Codex에게 팀 규칙과 권한을 알려주는 방법 (3)	2026.05.11

Contents

새소식

Codex CLI 입문(7) : Claude Code 사용자를 위한 Codex 전환 가이드 - CLAUDE.md·슬래시 명령·MCP 완전 마이그레이션

1. 먼저 경로를 고른다

경로 A — Mac 앱 "Import other agent setup"

경로 B — CLI 수동 마이그레이션 핵심 매핑

2. CLAUDE.md를 세 줄기로 나눈다

Step 1 — 개인 취향 → `~/.codex/AGENTS.md`

Step 2 — 팀 컨벤션 → 프로젝트 루트 `AGENTS.md`

Step 3 — 위험 지시는 보류 또는 폐기

3. 5분 Smoke Test — 설정이 작동하는지 확인

4. 빠지기 쉬운 함정 3가지

함정 ① — permissions allow/deny를 AGENTS.md에 그대로 적지 말 것

함정 ② — hooks를 1:1로 이식하지 말 것

함정 ③ — subagent의 tool 권한을 그대로 옮기지 말 것

5. MCP · hooks · Rules — 이미 쓰는 팀만 열어보기

자주 묻는 질문

"Import other agent setup"은 CLI에서도 쓸 수 있나?

CLAUDE.md를 통째로 복사해도 되나?

마이그레이션 후 설정이 제대로 적용됐는지 어떻게 확인하나?

참고 자료

'AI > Codex 기초 사용방법' 카테고리의 다른 글

당신이 좋아할만한 콘텐츠

티스토리툴바

Codex CLI 입문(7) : Claude Code 사용자를 위한 Codex 전환 가이드 - CLAUDE.md·슬래시 명령·MCP 완전 마이그레이션

1. 먼저 경로를 고른다

경로 A — Mac 앱 "Import other agent setup"

경로 B — CLI 수동 마이그레이션 핵심 매핑

2. CLAUDE.md를 세 줄기로 나눈다

Step 1 — 개인 취향 → ~/.codex/AGENTS.md

Step 2 — 팀 컨벤션 → 프로젝트 루트 AGENTS.md

Step 3 — 위험 지시는 보류 또는 폐기

3. 5분 Smoke Test — 설정이 작동하는지 확인

4. 빠지기 쉬운 함정 3가지

함정 ① — permissions allow/deny를 AGENTS.md에 그대로 적지 말 것

함정 ② — hooks를 1:1로 이식하지 말 것

함정 ③ — subagent의 tool 권한을 그대로 옮기지 말 것

5. MCP · hooks · Rules — 이미 쓰는 팀만 열어보기

자주 묻는 질문

"Import other agent setup"은 CLI에서도 쓸 수 있나?

CLAUDE.md를 통째로 복사해도 되나?

마이그레이션 후 설정이 제대로 적용됐는지 어떻게 확인하나?

참고 자료

'AI > Codex 기초 사용방법' 카테고리의 다른 글

당신이 좋아할만한 콘텐츠

티스토리툴바

Step 1 — 개인 취향 → `~/.codex/AGENTS.md`

Step 2 — 팀 컨벤션 → 프로젝트 루트 `AGENTS.md`