배경지식
1.
OpenClaw 문서는 provider, model, runtime을 분리해서 설명한다. 가령openai는 provider prefix이고, codex는 OpenAI agent turn을 Codex app-server로 실행하는 runtime이다. openai/gpt-*는 “OpenAI provider의 GPT 모델을 쓰겠다”는 model ref이고, 그 turn을 실제로 실행하는 runtime은 별도로 정해진다. “provider와 runtime이 분리되어 있다”는 말은 아무 provider나 아무 runtime에 꽂을 수 있다는 뜻이 아니다. model ref는 모델/인증/카탈로그의 canonical name이고, runtime은 그 turn을 실행할 수 있는 호환 executor다(OpenClaw는 runtime selection에서 model-scoped policy, provider-scoped policy, plugin runtime claim 순서로 고른다고 설명한다). Codex app-server runtime은 OpenAI/Codex 계열 agent turn 전용이다.
2.
OpenClaw에서는 OpenAI agent turn만 예외적으로 기본 runtime(unset/auto)이 Codex app-server 쪽으로 잡혀 있다. 그래서 agent turn이 openai/gpt-*이고, runtime을 따로 openclaw로 강제하지 않았다면 OpenClaw는 Codex app-server harness로 보낸다. Hermes에서는 반대다. openai/* 또는 openai-codex/* turn을 Codex app-server로 넘길 수 있지만, 이건 opt-in이다. 문서가 “This is opt-in only. Default Hermes behavior is unchanged unless you flip the flag. Hermes never auto-routes you onto this runtime.”라고 못 박고 있다.
Codex CLI → Codex app-server → GPT
Codex profile이라고 불리는 Codex app-server 설정과 인증 등을 여러 폴더에 분리하려면 CODEX_HOME을 사용해야 한다.
설정의 기본 전역 위치는 ~/.codex/config.toml이다. 이때 CODEX_HOME을 명시하여 config file을 $CODEX_HOME/profile-name.config.toml 경로로 잡고 Codex profile-specific config file을 둘 수 있다.
Codex는 로그인 정보를 캐시하고, CLI와 IDE extension이 같은 cached login details를 공유한다. 로그인 정보의 기본 저장 위치는 OS credential store 이다. cli_auth_credentials_store를 keyring 또는 auto로 두면 OS credential store가 사용되지만 cli_auth_credentials_store = "file"을 쓰면 로그인 정보도 $CODEX_HOME/auth.json에 저장된다.
# $CODEX_HOME/config.toml
cli_auth_credentials_store = "file"
TOML
복사
Codex credential store를 file이 아닌 keyring 또는 auto로 두면 OS credential store가 사용되므로, ~ 을 공유하는 같은 OS user 안에서 여러 계정을 사용하기 어려울 수 있다. OpenAI 문서상 file은 CODEX_HOME 아래 auth.json에 저장하고, keyring은 OS credential store에 저장하며, auto는 가능한 경우 OS credential store를 쓰고 아니면 auth.json으로 fallback한다고 언급한다.
그럼 이제 이렇게 된다. 예를 들어:
# Hermes personal profile에서 Codex를 부를 때
CODEX_HOME="$HOME/.hermes/profiles/personal/codex" codex
Plain Text
복사
# Hermes work profile에서 Codex를 부를 때
CODEX_HOME="$HOME/.hermes/profiles/work/codex" codex
Plain Text
복사
Hermes → Hermes native harness → GPT
이 경로에서는 CODEX_HOME이 아무 영향을 주지 않는다. CODEX_HOME에 저장되는 정보들은 Codex app-server 런타임에 영향을 주는 상태값인데, 애초에 Hermes native harness을 사용하면서 Codex app-server가 LLM runtime으로 개입하지 않기 때문이다.
Hermes native harness의 openai-codex 인증은 CODEX_HOME이 아닌 Hermes auth store, HERMES_HOME/auth.json에 저장된다. 따라서 Hermes profile별로 Hermes native harness가 사용하는 인증을 분리하려면 각 profile마다 HERMES_HOME을 지정한 상태에서 Hermes OAuth 로그인을 따로 수행해야 한다.
예를 들어 personal profile은 이렇게 로그인한다.
PROFILE_HOME="$HOME/.hermes/profiles/personal"
HERMES_HOME="$PROFILE_HOME" \
hermes auth add openai-codex --type oauth --label personal
TOML
복사
work profile도 별도로 로그인한다.
PROFILE_HOME="$HOME/.hermes/profiles/work"
HERMES_HOME="$PROFILE_HOME" \
hermes auth add openai-codex --type oauth --label work
TOML
복사
이렇게 하면 각 Hermes profile은 자기 자신의 auth.json을 사용한다. 로그인 상태는 profile별로 확인한다.
HERMES_HOME="$HOME/.hermes/profiles/personal" \
hermes auth status openai-codex
HERMES_HOME="$HOME/.hermes/profiles/work" \
hermes auth status openai-codex
TOML
복사
같은 OpenAI 계정으로 로그인하더라도 각 profile에서 OAuth flow를 따로 수행해야 한다. refresh token은 회전/소모될 수 있으므로, 한 profile의 인증 파일을 다른 profile에 복사하면 나중에 refresh_token_reused 같은 문제가 생길 수 있다.
Hermes → Codex app-server → GPT
이 경로에서는 Codex app-server가 LLM runtime으로 개입한다. Hermes는 profile, workflow, gateway, kanban 같은 outer orchestration을 맡고, Codex app-server는 inner runtime으로 thread/turn 실행과 GPT 호출을 담당한다.
하지만 Codex app-server를 쓰는 경우에도 Hermes harness가 완전히 사라지는 것은 아니다. Hermes가 title generation, context compression, review fork, goal judge, structured workflow step 같은 보조 LLM call을 수행할 수 있다면, Hermes own auth도 별도로 필요할 수 있다. 따라서 가장 명확한 설정은 둘 다 profile-local로 두는 것이다.
HERMES_PROFILE_HOME="$HOME/.hermes/profiles/personal"
# 또는 HERMES_PROFILE_HOME="$HOME/.hermes/profiles/work"
CODEX_HOME="$HERMES_PROFILE_HOME/codex"
# Codex app-server / CLI 인증
CODEX_HOME="$CODEX_HOME" \
codex login --device-auth
# Hermes harness 인증
HERMES_HOME="$HERMES_PROFILE_HOME" \
hermes auth add openai-codex --type oauth --label work
TOML
복사
OpenClaw → Codex app-server → GPT
OpenClaw는 agentDir(에이전트의 런타임 상태를 저장하는 내부 디렉터리) 기준으로 Codex app-server home을 agent-local하게 만든다. OpenClaw의 Codex plugin은 Codex app-server 기반 harness/provider를 등록하고, 각 agent 실행을 Codex app-server에 연결한다.
Codex app-server의 CODEX_HOME은 agentDir/codex-home으로 자동으로 지정되며, 이는 Codex runtime의 config/cache/session/plugin 상태를 위한 공간이다. 하지만 인증이 codex-home 안에서 관리되지는 않는다. 인증은 agentDir/auth-profiles.json 에 저장될 수 있다.
openclaw models auth --agent personal login \
--provider openai-codex \
--profile-id openai-codex:personal
openclaw models auth --agent work login \
--provider openai-codex \
--profile-id openai-codex:work
TOML
복사
profile-id는 OpenClaw auth store 안에서 그 인증 프로필을 식별하는 key
또는 기본 에이전트의 fallback 저장소(your-default-agentDir/auth-profiles.json)에 저장되어 전역 fallback처럼 사용될 수 있다.
Codex와 느슨하게 결합된 Hermes와 달리 Codex같은 특이 케이스가 깊이 통합되어있기 때문에 OpenClaw 하네스용 인증을 따로 해 줄 필요도 없으며, CODEX_HOME을 별도로 지정해 줄 필요도 없다. OpenClaw에서 codex harness를 사용하는 것이 훨씬 매끄럽게 느껴질 수 있다.
Sandbox
host/native sandbox와 Docker sandbox가 같은 CODEX_HOME/config.toml을 공유하면 절대경로가 맞지 않아 깨질 수 있다.
Docker 안에서도 host와 같은 absolute path가 보이도록 mount path를 맞추는 것은 호스트 데이터가 /opt/data 로 마운팅되는 패턴을 고려했을 때 조금 억지스러운 경향이 있고, container 시작 시 -e CODEX_HOME=... 같은 runtime env override를 쓰는 방법이 있겠지만 이 또한 Kanban worker나 profile별 gateway까지 고려하면 profile마다 다른 값을 넣어야 하므로 깔끔하지 못하다. 가장 좋은 방법은 Codex home을 environment별로 분리하는 것이다.
# work-native
CODEX_HOME=/Users/janghoo/.hermes/profiles/work-native/codex
# work-docker
CODEX_HOME=/opt/data/profiles/work-docker/codex
JavaScript
복사
언젠가 이 메모에 쓰이면 좋을 것 같은 재료들입니다.
1.
from: 이 메모에 쓰인 생각을 만든 앞의 생각들입니다. 앞의 생각과 연관관계를 설명합니다.
1.
supplementary: 이 메모에 작성된 생각을 뒷받침하는 생각의 새로운 메모입니다.
1.
opposite: 이 메모에 작성된 생각과 대조되는 생각의 새로운 메모입니다.
1.
to: 이 메모에 작성된 생각으로부터 발전된 생각의 새로운 메모입니다.
1.
ref: 생각에 참고한 자료입니다.
1.
프로젝트메모 템플릿 버전 2026.03.20