feat(ocx): native token injection for Codex without the wrapper shim (systemd --user drop-in or equivalent)

[rrmlima]

Area

CLI; Authentication and account pool; Service lifecycle; Platform (Linux).

What are you trying to accomplish?

I need Codex CLI processes launched on a Linux server to reach an OpenCodex provider configured with:

[model_providers.opencodex]
base_url = "http://127.0.0.1:10100/v1"
env_key = "OPENCODEX_API_AUTH_TOKEN"

without depending on a wrapper installed at the same filesystem path as the Codex binary. The token must remain outside config.toml, and Codex upgrades must not silently remove the credential injection mechanism.

What prevents this today?

env_key tells Codex which process environment variable to read; it does not create that variable. OpenCodex's current solution, ocx codex-shim install, replaces the Codex launcher with a POSIX wrapper that reads the service token and exports OPENCODEX_API_AUTH_TOKEN.

Codex upgrades can replace that path with a symlink or a fresh binary. After that, codex exec fails before reaching the proxy:

ERROR: Missing environment variable: `OPENCODEX_API_AUTH_TOKEN`.

Validated on OpenCodex 2.33.0 and Codex CLI 0.149.1:

Launch state	Result
OpenCodex shim installed	HTTP 200; turn.completed; request recorded in usage.jsonl
Direct symlink to the real Codex binary, env absent	Immediate missing-variable error; no proxy request
Direct binary with token manually exported	Works, confirming the missing environment is the only blocker

The current workaround is to reinstall the shim after every Codex update or maintain an external cron that detects and repairs it.

What should OpenCodex do?

Provide and document a shim-independent credential injection mode while preserving the current secure default:

1. A first-class Linux environment integration, such as ocx codex-env install, that installs a user-scoped environment generator/drop-in and can be audited/uninstalled; or
2. A provider credential-file directive supported by the Codex integration, allowing the launcher to read /root/.opencodex/service-api-token without storing the secret in config.toml or inheriting it through a shell wrapper.

At minimum, ocx doctor should detect the invalid combination "provider uses env_key + environment variable absent + shim absent" and print an actionable repair command.

The behavior should be idempotent, never print the token, create files with restrictive permissions, and survive Codex upgrades.

Example usage or interface

# Proposed first-class alternative
ocx codex-env install --mode systemd-user
ocx codex-env status
ocx codex-env uninstall

# Expected diagnostic
ocx doctor
# ERROR: model_providers.opencodex uses env_key=OPENCODEX_API_AUTH_TOKEN,
# but the variable is unavailable and no credential injector is active.
# Run: ocx codex-env install

Before/after behavior:

# Current, after a Codex upgrade overwrites the shim
codex exec "reply OK"
# ERROR: Missing environment variable: OPENCODEX_API_AUTH_TOKEN

# Expected after native environment integration
codex exec "reply OK"
# request reaches OpenCodex and completes

Alternatives or workarounds

• ocx codex-shim install: works, but shares the executable path with Codex and is overwritten by upgrades.
• Exporting the token manually in shell profiles: incomplete for GUI/systemd/non-interactive launches and spreads secret handling across user files.
• systemctl --user set-environment: process-session scoped and not durable by itself.
• External daily repair script: effective locally but duplicates lifecycle logic that belongs in OpenCodex.

Additional context

Environment tested:

• OpenCodex 2.33.0
• Codex CLI 0.149.1
• Linux, root-owned server deployment
• OpenCodex proxy at 127.0.0.1:10100

Related shim work: #1441.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.

[github-actions]

Issue reopened

The report now contains the information required by the automated check. Thanks for updating it.

[rrmlima]

Updated the report to use the repository's recognized issue-template headings and filled every required field requested by the quality bot. The reproduction and all examples are redacted. Please re-evaluate/reopen automatically.

[rrmlima]

Follow-up: corrected headings to the exact GitHub issue-form rendering (). For #2717 I also added the literal Bug-template fields , , , , and because the quality bot classified the existing issue as kind=bug. All requested fields are now present.

[rrmlima]

Follow-up: corrected headings to the exact GitHub issue-form rendering (###). For #2717 I also added the literal Bug-template fields Summary, Reproduction, Version, Operating system, and Provider and model because the quality bot classified the existing issue as kind=bug. All requested fields are now present.

[lidge-jun]

리뷰 · 우선순위 58 / 80

설명: 이 이슈는 리눅스 서버에서 Codex 를 켤 때 쓰는 인증 넣는 방법이 Codex 실행 파일 길을 가로채는 심에 묶여 있어서, Codex 업데이트마다 심이 지워진다는 이야기다. 작성자는 rrmlima 이다. 라벨은 enhancement, cli 다. 보고 버전은 OpenCodex 2.33.0 과 Codex CLI 0.149.1 이다. 지금 CURRENT dev HEAD 는 9b838d0 이다. package.json 은 아직 2.32.1-preview.20260825 다. 이번 시간 origin/dev 는 ab63ded 에서 9b838d0 로 움직였다. 마지막 머지는 2719 프롬프트 패널 그림 다듬기다. 이 이슈와는 무관하다. 이 이슈는 열려 있다. 구현 풀은 아직 없다. 내가 머지하지 않고 구현하지 않는다.

작성자가 원하는 그림은 이렇다. Codex 설정에는 [model_providers.opencodex] 와 env_key = "OPENCODEX_API_AUTH_TOKEN" 가 있다. 비밀은 설정 파일에 안 넣는다. 그런데 Codex 는 그 환경 변수가 없으면 바로 죽는다. 지금 공식 방법은 ocx codex-shim install 이다. 심이 Codex 실행 파일 자리에 앉아 토큰을 읽는다. Codex 업데이트가 그 자리를 심링크나 새 바이너리로 덮으면 codex exec 가 Missing environment variable: OPENCODEX_API_AUTH_TOKEN 로 끝난다. 작성자는 심을 쓰지 않는 리눅스 환경 설치, 예를 들어 ocx codex-env install --mode systemd-user 와, 심이 없고 변수도 없을 때 ocx doctor 가 고치라는 말을 해 주기를 원한다.

HEAD 를 보면 이미 있는 것과 없는 것이 갈린다. src/codex/inject.ts 231-237줄은 Codex 0.146 이후 계약으로 env_key = "OPENCODEX_API_AUTH_TOKEN" 를 넣는다. 변수가 비면 Codex 가 바로 에러를 낸다. 그게 본문 재현이다. 토큰 파일은 이미 있다. src/lib/service-secrets.ts 5-7줄 serviceApiTokenFilePath 는 설정 폴더의 service-api-token 이다. 루트 서버면 /root/.opencodex/service-api-token 과 같다. src/codex/shim.ts 699-701줄은 심이 그 파일을 읽어 환경 변수로 보낸다. src/service.ts 466줄도 서비스 시작 껍질이 같은 파일을 읽는다. 새 비밀 길을 만들 필요가 없다.

심이 덮이면 고치는 길도 이미 있다. src/types/config.ts 536줄 codexShimAutoRestore 기본값은 켜짐이다. src/config.ts 3061-3065줄 codexShimAutoRestoreEnabled 는 설정을 끄거나 OPENCODEX_CODEX_SHIM_AUTO_RESTORE=0 일 때만 꺼진다. src/cli/codex-shim-autorestore.ts 25-46줄은 다음 ocx 명령을 칠 때 심을 되돌린다. codex exec 만 치면 이 복구는 안 돈다. 작성자가 본 구멍은 바로 그 점이다. 심 상태 진단 diagnoseCodexShim 는 src/codex/shim.ts 2187-2218줄에 있다. 그런데 src/cli/doctor.ts 는 그 함수를 안 부른다. doctor 1029줄 근처는 HTTP 프록시 환경만 본다. OPENCODEX_API_AUTH_TOKEN 없음과 env_key 조합을 에러로 안 찍는다. src/cli/registry.ts 73-74줄 명령은 ocx codex-shim 뿐이다. ocx codex-env 는 없다.

작성자가 고른 systemd --user 는 이 환경에 안 맞다. 본문은 루트 소유 브이피에스다. 루트는 보통 시스템 유닛을 쓴다. 사용자 세션이 살아 있지 않으면 --user 드롭인은 안 먹는다. macOS 쪽 claudeCode.systemEnv 는 src/types/config.ts 49-53줄에 있고 launchctl setenv 다. 리눅스 루트와는 다른 길이다. 관련 이슈 1441 은 재귀 심을 고친 뒤 닫혀 있다. 다시 열지 말 것. 2696 은 launchd 가 관리 토큰을 OPENCODEX_API_AUTH_TOKEN 으로 별칭 붙이는 문제라 이 이슈와 겹친다. 토큰 이름을 섞지 말 것. types.ts 와 config.ts 가르기가 진행 중이다. 새 설정 칸을 넣으면 src/types/config.ts 에 넣는다. src/types.ts 를 되살리지 말 것. 프리뷰 배포가 아니다.

라인 231-237 - src/codex/inject.ts 가 env_key 를 넣어서 변수 없으면 Codex 가 바로 죽는다
라인 5-7 - src/lib/service-secrets.ts 토큰 파일 길은 이미 설정 폴더의 service-api-token 이다
라인 699-701 - src/codex/shim.ts 심만 그 파일을 읽어 환경 변수로 보낸다. 심이 없으면 안 읽는다
라인 466 - src/service.ts 서비스 시작 껍질도 같은 파일을 읽는다. Codex 자식에는 안 넘어간다
라인 536 - src/types/config.ts codexShimAutoRestore 기본 켜짐이다
라인 25-46 - src/cli/codex-shim-autorestore.ts 복구는 ocx 명령을 칠 때만 돈다. 바로 codex exec 하면 안 돈다
라인 2187-2218 - diagnoseCodexShim 는 있는데 doctor 가 안 부른다
경로/심볼 - src/cli/doctor.ts 에 env_key 와 토큰 없음과 심 없음 조합 검사가 없다
라인 73-74 - src/cli/registry.ts 에 codex-env 명령이 없다
이슈 1441 - 재귀 심 수정으로 이미 닫혀 있다. 다시 열지 말 것
이슈 2696 - 토큰 환경 변수 별칭 문제와 겹친다. 이름을 섞어 고치지 말 것

메인테이너의 판단이 필요한 지점

• 큰 새 명령 ocx codex-env 를 만들지, doctor 경고만 먼저 넣을지. 경고가 먼저다
• 루트 브이피에스에 systemd --user 를 기본으로 둘지. 두지 말 것. 시스템 유닛 EnvironmentFile 이 맞다
• 토큰 파일을 새로 만들지. 만들지 말 것. 있는 service-api-token 을 쓴다
• Codex 실행 파일 길을 또 가로챌지. 가로채지 말 것. 그게 이번 구멍이다
• 항상 켜진 ocx service install 만으로 충분한지. 프록시만 살아도 Codex 자식은 변수가 필요하다

너의 추천
이 이슈는 연다. 닫지 말 것. 구현 풀을 지금 크게 받지 않는다. 첫 조각은 ocx doctor 가 env_key 가 있는데 변수가 없고 심도 없으면, 있는 토큰 파일과 ocx codex-shim install 또는 시스템 유닛 EnvironmentFile 을 가리키게 하는 것이다. 토큰 값을 출력하지 말 것. systemd --user 기본안은 거절한다. 루트 서버에 안 맞다. 설정 칸을 넣으면 src/types/config.ts 에만 넣는다. 1441 은 다시 열지 말 것. 라벨은 그대로 둔다. 프리뷰 배포가 아니다. 내가 머지하지 않는다.

이 댓글은 grok-bot이 작성했습니다

[rrmlima]

I reproduced and implemented the narrow ocx doctor contribution suggested in the review.

One important boundary for the proposed systemd alternative: EnvironmentFile= only injects the token when Codex itself is launched by that unit. An environment variable loaded by the OpenCodex service cannot flow back into an interactive shell or an independently launched codex exec process.

Controlled production evidence (OpenCodex 2.33.0, Codex CLI 0.149.1):

Launch path	Result
Direct real Codex binary, env_key configured, env absent	Missing environment variable: OPENCODEX_API_AUTH_TOKEN; no request reached the proxy
Same binary with the variable explicitly exported	completed
OpenCodex shim restored	turn.completed; HTTP 200 recorded in usage.jsonl

I prepared a focused, read-only doctor change on clean 2.34.0 main. It diagnoses only when all conditions are true:

1. root model_provider is exactly opencodex;
2. [model_providers.opencodex].env_key is configured;
3. that variable is unset/empty in the doctor process;
4. the OpenCodex shim is missing or unhealthy;
5. a readable, non-empty service-token file exists.

It reports that plain Codex does not read the service token and recommends either ocx codex-shim install or exporting the named variable in the process that launches Codex. It never reads the token into diagnostic output.

Validation:

117 pass, 0 fail
bun x tsc --noEmit: pass

Coverage includes missing vs unhealthy shim, env already set, healthy shim, absent/empty token, another active provider, unrelated/commented env_key, and secret non-disclosure.

The implementation is committed locally and ready for a small standalone PR; no credential lifecycle or shim behavior is changed.

[rrmlima]

What are you trying to accomplish?

Confirm the path forward for the ocx codex-env install --mode systemd-user (or equivalent) request on a root-owned VPS, and acknowledge the review of the doctor diagnostic.

What prevents this today?

ocx codex-shim install is the only first-class mechanism, and it is overwritten by Codex upgrades. The two follow-ups the review asked for are now in place:

• The narrow ocx doctor diagnostic for the broken env_key launch path is implemented in PR fix(doctor): diagnose the broken Codex env_key launch path #2844 (commit 5734a1c).
• The agentrouter openai-chat client identity and shared framing shipped in PR fix(agentrouter): send the Codex client identity on the openai-chat path (#2717) #2843 (commit bb3321c).

What should OpenCodex do?

Per the owner review, the next decision is between a systemd --user drop-in and a systemd EnvironmentFile= on the service unit. One important boundary that the current upstream answer must clarify, and that I want to confirm before this issue is closed:

• An EnvironmentFile= injected into the opencodex-proxy.service unit only lands in the proxy process itself, not in descendants launched by an interactive shell or by an independent codex exec invocation. Validated on a root-owned VPS with OpenCodex 2.33.0 / Codex 0.149.1: a direct real Codex binary with env_key configured and the env absent still fails with Missing environment variable: OPENCODEX_API_AUTH_TOKEN; the proxy was never reached. Restoring the shim made the same call complete and recorded HTTP 200 in usage.jsonl.

So the user-managed choice we are documenting is:

• root + systemd opencodex-proxy.service EnvironmentFile=: good enough for proxied traffic inside the service, but does not protect interactive codex exec from a shell.
• ocx codex-shim install: the only path that survives any Codex invocation, including the codex exec started outside the service. This is what the diagnostic in fix(doctor): diagnose the broken Codex env_key launch path #2844 already recommends.

Could the upstream confirm that the right operator-facing next step is to keep ocx codex-shim install as the recommended path for any host where Codex is launched outside the OpenCodex service, and to consider a systemd EnvironmentFile= only as a non-interactive hardening for the proxy unit itself (with that limitation in the docs)? With that clarification, the issue can move to a documentation update against the doctor diagnostic instead of a new ocx codex-env command.

Example usage or interface

# /etc/systemd/system/opencodex-proxy.service.d/10-service-token.conf
[Service]
EnvironmentFile=/etc/opencodex/service-token.env

# /etc/opencodex/service-token.env
OPENCODEX_API_AUTH_TOKEN_FILE=/root/.opencodex/service-api-token

Then a non-interactive systemctl --user start opencodex-proxy carries the env. Interactive codex exec from a shell still needs the shim, which the doctor now reports.

Alternatives or workarounds

• ocx codex-shim install — the only path that survives all Codex invocation patterns; the doctor in fix(doctor): diagnose the broken Codex env_key launch path #2844 already recommends it.
• Document a per-host step to export OPENCODEX_API_AUTH_TOKEN in /etc/profile.d/opencodex.sh for shells; not durable for systemd-launched children.
• Provide a codex --profile opencodex wrapper in ocx that imports the token at start; the existing fix-F shim already does this without a new command.

Additional context

• 1441 is closed for the recursive-launcher shim and should not be reopened.
• 2696 is the launchd token-aliasing issue; this issue is the Linux analogue and should remain scoped to the opencodex user.
• types.ts and config.ts are in the middle of a split; if a new config field lands, it must go into src/types/config.ts, not the legacy src/types.ts.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.