Codex

벤더: OpenAI 설치 이름: codex 상태: 베타 네이티브 구성: ~/.codex/AGENTS.md, ~/.codex/hooks.json, ~/.codex/hooks/, ~/.codex/agents/*.toml, 그리고 ~/.agents/skills/

설치Copy Anchor Link

apothem install --harness codex

어댑터는 Codex 네이티브 지침과 훅을 설치하고, Apothem 에이전트를 Codex TOML 에이전트로 변환하며, 재사용 가능한 커맨드 프롬프트를 Codex 스킬로 래핑합니다.

작성되는 파일: ~/.codex/AGENTS.md, ~/.codex/hooks.json, ~/.codex/hooks/, ~/.codex/agents/*.toml, ~/.agents/skills/*/SKILL.md, 사용자 호출 스킬용 ~/.agents/skills/*/agents/openai.yaml, 그리고 ~/.config/apothem/{rules,templates}/ 아래의 지원 파일.

훅 인터프리터. 설치는 어떤 파일도 쓰기 전에 CPython 3.10+ 인터프리터를 찾습니다. Windows에서는 hooks.json의 각 훅 commandWindows 항목이 py -3 런처 대신 해당 인터프리터의 절대 경로를 실행합니다. POSIX command 항목은 python3을 그대로 유지합니다. 인터프리터가 이동하거나 제거된 뒤에는 apothem update --harness codex를 다시 실행하세요. CPython 3.10+를 찾지 못하면 설치는 어떤 파일도 쓰기 전에 중단됩니다.

AGENTS.md의 Apothem 블록은 Apothem 지원 파일 섹션으로 끝나며, 이 섹션은 설치된 스킬과 규칙에 있는 저장소 스타일의 각 인용이 해석되는 기준 절대 디렉터리를 명시합니다. rules/<name>.md와 templates/...는 ~/.config/apothem/ 아래, hooks/...는 ~/.codex/hooks/ 아래입니다. Codex 설치는 schemas/나 conformity/ 트리를 제공하지 않으므로, 이 섹션은 둘 다 나열하지 않습니다.

사용자 호출 스킬. Codex는 disable-model-invocation 키를 무시합니다. 소스에서 disable-model-invocation: true를 설정한 모든 스킬 또는 커맨드에 대해, 어댑터는 해당 SKILL.md 옆에 policy.allow_implicit_invocation: false를 담은 agents/openai.yaml을 작성하므로 Codex가 스스로 그 스킬을 선택하지 않습니다. $skill-name으로 명시적으로 실행하는 것은 여전히 가능합니다. Codex 스킬 문서를 참조하세요.

프로필-네이티브 구성 매핑Copy Anchor Link

어댑터는 Apothem의 공유 코호트를 읽고 각 코호트를 알맞은 Codex 표면에 설치합니다. 지침은 AGENTS.md로, 훅은 hooks.json과 hooks/로, 에이전트는 TOML로, 스킬은 ~/.agents/skills/로, 네이티브가 아닌 Markdown 규칙/템플릿은 지원 자료로 ~/.config/apothem/에 설치됩니다.

변환된 각 도우미는 name, description, 그리고 도우미의 본문을 담는 developer_instructions를 설정합니다. 모델이나 추론 노력은 설정하지 않으므로 각 도우미는 세션의 선택을 상속합니다. Codex에는 도우미별 도구 목록이나 턴 제한이 없으므로, 도우미의 tools와 maxTurns는 이어지지 않습니다.

읽기 전용 도우미(에이전트 참조 참조)는 지침에서 아무것도 편집하지 않는다고 말합니다. 읽기 전용은 도우미의 TOML 파일이 아니라 부모 세션의 샌드박스가 강제합니다. 모든 도우미는 자신을 시작한 세션의 샌드박스 및 승인 설정 아래에서 실행됩니다. 도우미 파일은 세션의 샌드박스 모드, 승인 정책, 모델 공급자, MCP 서버를 재정의할 수 없으므로 어댑터는 그중 어느 것도 작성하지 않으며, 도우미의 지침은 별도의 읽기 전용 샌드박스를 만들지 않고도 편집을 피하라고 요청할 수 있습니다. 읽기 전용 제한을 구속력 있게 만들려면 Codex 세션 자체에 샌드박스 및 승인 제어를 설정하세요. 이 제한을 추가한 릴리스보다 오래된 Codex 빌드는 도우미 파일의 sandbox_mode를 여전히 따를 수 있습니다. Apothem은 그것이 어느 릴리스인지 확인하지 않았으며, 어느 쪽이든 sandbox_mode를 작성하지 않습니다.

호환성 참고 사항Copy Anchor Link

~/.agents/skills/는 Codex가 소유하는 공유 루트입니다. 지원되는 다른 도구 아홉 개도 이 루트를 로드하므로(하니스 레지스트리에 나열됨), Codex 설치가 그곳에 작성하는 Apothem 스킬은 그 도구들에도 나타납니다. 그 도구 중 네 개는 설치할 때 이 폴더에 직접 작성하기도 하며(레지스트리는 이들을 공동 설치자로 나열합니다), Codex 설치가 작성하는 것과 같은 파일을 작성하므로 Codex 설치가 없는 머신에도 스킬이 있게 됩니다. ~/.config/apothem/의 규칙과 템플릿도 마찬가지이며, 프로젝트 범위 어댑터 일곱 개도 이를 작성합니다. 이 폴더는 CODEX_HOME이 무엇이든 항상 사용자 홈에 있습니다. Codex는 $HOME/.agents/skills를 읽으므로, ~/.codex가 아닌 CODEX_HOME은 Codex 파일을 옮기지만 스킬은 옮기지 않습니다. 이 폴더를 사용하는 모든 Apothem 설치는 그곳에 같은 파일을 작성하며, 설치는 어느 설치가 이 폴더를 사용하는지 기록하므로 설치 순서는 중요하지 않습니다. Codex 제거는 다른 Apothem 설치가 더 이상 사용하지 않을 때만 스킬을 제거합니다. 그렇지 않으면 스킬을 유지하고 어느 설치가 사용 중인지 알려 줍니다(제거 참조). 등록된 소유자는 벤더가 그 경로를 문서화한 도구입니다. 파일을 배치한 설치는 그 파일을 여전히 사용하는 설치이며, 설치 안내가 그 설치를 명시합니다. Apothem이 작성하지 않았고 Apothem 스킬과 같은 이름을 가진 스킬 폴더는 그대로 두며, 그 폴더를 명시하는 경고를 출력합니다. 설치는 해당 도구들을 명시하는 안내를 출력합니다. ~/.codex/agents/는 두 번째 공유 루트입니다. 지원되는 다른 도구 하나가 이 폴더를 호환성 위치로 나열하며(레지스트리가 그 도구를 명시합니다), 그 도구의 문서는 Codex 설치가 그곳에 작성하는 TOML 파일을 읽는지 밝히지 않습니다.

Codex는 ~/.codex/rules/를 .rules 실행 정책용으로 예약합니다. Apothem은 그곳에 Markdown 동작 규칙을 두지 않으며, 이를 ~/.config/apothem/에 두고 AGENTS.md와 설치된 스킬에서 참조합니다.

Codex 플러그인Copy Anchor Link

Apothem은 저장소의 플러그인 마켓플레이스에서 추가하는 Codex 플러그인도 제공합니다(설치 가이드의 채널 7 아래에 명령이 나열되어 있습니다). 플러그인은 부트스트랩입니다. 엔진을 실행하는 진입 스킬 하나를 번들하며, apothem install --harness codex가 위에 나열된 모든 것을 작성합니다.

플러그인은 plugins/apothem/에 있습니다. 매니페스트는 루트 plugin.json으로, Codex가 새 패키지용으로 문서화한 위치입니다. Codex는 플러그인 루트에서 플러그인의 skills/ 디렉터리를 찾으므로 매니페스트는 스킬 경로를 명시하지 않습니다. .codex-plugin/plugin.json 파일은 그 이전 위치만 읽는 Codex 빌드를 위한 호환성 대체 수단으로 그 옆에 남아 있습니다. Codex는 여전히 이를 지원하며, 플러그인의 신원에 대해서는 루트 매니페스트를 정식으로 취급합니다. 두 파일 모두 릴리스 버전을 담으며, 테스트가 이를 엔진의 버전과 일치하도록 유지합니다.

플러그인은 에이전트, 훅, MCP 서버를 번들하지 않습니다. Codex는 플러그인용 사용자 정의 에이전트 구성 요소를 문서화하지 않으므로, 엔진은 계속 에이전트를 ~/.codex/agents/*.toml에 작성합니다. 플러그인에 번들된 훅은 Codex 데스크톱에서 수동으로 설치한 플러그인으로 제한되며 자동으로 신뢰되지 않으므로, 엔진은 계속 훅을 ~/.codex/hooks.json에 작성합니다.

마켓플레이스 항목은 Codex가 작성자에게 항상 포함하라고 안내하는 policy 블록을 설정합니다. policy.installation은 AVAILABLE이고 policy.authentication은 ON_INSTALL이며, 이는 Codex가 새 항목에 대해 문서화한 기본값입니다.

검증Copy Anchor Link

apothem verify --harness codex

verify 명령은 다음을 확인합니다.

1. 네이티브 구성이 예상 경로에 존재합니다.
2. 각 관리 대상이 존재하고, 관리되는 파일은 비어 있지 않으며, JSON 또는 YAML 구성은 파싱됩니다. 설치된 파일이 그 프로필과도 일치하는지 확인하려면 --profile PATH를 추가하세요.
3. 어댑터별 검증 루틴이 성공을 보고합니다.

업데이트Copy Anchor Link

apothem update --harness codex

Codex 부트스트랩, 변환된 에이전트, 스킬, 지원 코호트를 새로 고칩니다.

~/.agents/skills/의 스킬 폴더는 그 폴더에 대한 모든 Apothem 설치가 공유하는 하나의 형식으로 작성됩니다. SKILL.md 헤더 키 version, updated, archetype, portability는 metadata 맵 아래에 놓이며, userInvocable은 user-invocable로 작성됩니다. 업그레이드 후 첫 업데이트는 Codex 설치가 이전에 작성한 폴더를 그 형식으로 다시 작성하고, 변경하는 각 폴더를 백업합니다. apothem rollback --harness codex가 그 폴더들을 복원합니다.

제거Copy Anchor Link

apothem uninstall --harness codex

~/.codex/AGENTS.md에서 Apothem 블록을 제거하고 그 바깥의 텍스트는 그대로 두며, ~/.codex/hooks.json에서 Apothem의 항목을 제거하고 여러분이 추가한 항목은 그대로 둡니다. 또한 ~/.codex/hooks/, ~/.codex/agents/, ~/.agents/skills/, ~/.config/apothem/{rules,templates}/에 있는 Apothem 파일을 제거하되, 다른 Apothem 설치가 여전히 사용하는 파일은 제외합니다(제거는 그 파일들을 유지하고 나열합니다). 그 폴더들의 다른 파일은 그대로 남습니다. ~/.agents/skills/에서 제거된 스킬은 이 폴더를 로드하는 다른 도구에서도 사라집니다 (호환성 참고 사항 참조). CODEX_HOME을 ~/.codex가 아닌 폴더로 설정하고 이전 릴리스로 설치했다면, 그 릴리스가 그 폴더 옆에 작성한 사본(<CODEX_HOME>/../.agents/skills/ 및 <CODEX_HOME>/../.config/apothem/)은 제거되지 않으므로 직접 삭제하세요. 각 파일은 변경 또는 제거되기 전에 ~/.apothem/backups/ 아래에 백업됩니다. 공유 프로필 YAML과 Apothem 엔진은 영향을 받지 않습니다.

적합성 게이트Copy Anchor Link

python -m apothem.conformity.gate --all .

문제 해결Copy Anchor Link

구성 노브Copy Anchor Link

함께 보기Copy Anchor Link

• 전체 하니스 — 지원되는 도구의 전체 카탈로그
• 설치 가이드 — 이 하니스에 Apothem 설치
• apothem harnesses 참조 — CLI에서 어댑터를 나열하고 검사