lidge-jun · lidge-jun · Sep 7, 2026 · Sep 7, 2026
@@ -216,6 +216,18 @@ ocx codex-shim uninstall
 常時オンのバックグラウンド プロキシには `ocx service` を使用します (推奨)。デーモンを使用しない軽量のオンデマンド起動には、`ocx codex-shim` を使用します。プロキシは、`codex` が起動された場合にのみ起動します。
 :::
 
+#### Codex へのトークン注入
+
+非ループバックアドレスにバインドする場合、注入されるプロバイダーには `env_key = "OPENCODEX_API_AUTH_TOKEN"` が含まれます。この行は、読み取る変数を Codex に指定するだけで、変数を作成するものではありません。変数が存在しない場合、Codex はリクエストの開始を拒否し（`Missing environment variable: OPENCODEX_API_AUTH_TOKEN`）、プロキシには到達しません。値は `$OPENCODEX_HOME/service-api-token` に保存されており、起動元のプロセスが Codex の環境にその値を渡す必要があります。
+
+`ocx codex-shim install` でインストールされる、保守対象のシムを使用してください。起動コンテキストでこのシムが選択されると、シムは OpenCodex が作成したトークンファイルを読み取り、変数を Codex に渡します。デスクトップ、cron、サービスから起動する場合は、このシムが選択される PATH またはランチャーパスを使用する必要があります。インストールによって、それらの環境が自動的に設定されるわけではありません。Codex 自身の子プロセスにも、トークンが継承される可能性があります。
+
+この Bearer トークンをシェルの起動ファイルからエクスポートしたり、`config.toml` にコピーしたりしないでください。`service-api-token` ファイルに含まれるのは `NAME=value` 形式の代入ではなくトークンそのものなので、systemd の `EnvironmentFile=` として直接使用することはできません。
+
+`opencodex-proxy.service` の `EnvironmentFile=` または `OCX_API_TOKEN_FILE` は、プロキシプロセスだけを設定するものであり、独立して起動された `codex exec` に渡されることはありません。
+
+ランチャーを置き換える Codex のアップグレードによって、シムは削除されます。次に通常の `ocx` コマンドを実行すると復元されますが（上記参照）、その前に実行された `codex exec` は失敗します。`ocx doctor` は、この状態（env_key が設定済み、変数が未設定、シムが存在しないか正常でない、トークンファイルは存在する）を修復コマンドとともに "Codex env_key launch readiness" の項目で報告し、トークンを表示することはありません。トークンファイルの読み取りは、注入された `env_key` の契約には含まれません。起動元のプロセスがその変数を渡す必要があります。
+
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 Windows ステータス トレイ アイコンをインストールして制御します。 Windows ログイン時に開始され、ワンクリックでプロキシ コントロールを提供します。 `start` および `stop` はアイコンのみを制御します。そのメニューを使用してプロキシを制御します。 `--no-start` は `install` に適用され、トレイをすぐに起動せずにインストールします。

@@ -298,6 +298,18 @@ ocx codex-shim uninstall
 때만 시작하려면 `ocx codex-shim`을 사용합니다. 이 경우 프록시는 `codex`를 실행할 때만 시작됩니다.
 :::
 
+#### Codex에 토큰 주입
+
+루프백이 아닌 주소에 바인딩하면 주입된 공급자에 `env_key = "OPENCODEX_API_AUTH_TOKEN"`이 포함됩니다. 이 줄은 Codex가 읽을 변수를 지정할 뿐, 변수를 생성하지는 않습니다. 변수가 없으면 Codex는 요청 시작을 거부하며(`Missing environment variable: OPENCODEX_API_AUTH_TOKEN`), 요청은 프록시에 도달하지 않습니다. 값은 `$OPENCODEX_HOME/service-api-token`에 저장되며, 실행을 시작하는 프로세스가 Codex의 환경에 이 값을 제공해야 합니다.
+
+`ocx codex-shim install`로 설치되는 shim을 사용하세요. 실행 환경에서 이 shim이 선택되면 OpenCodex가 생성한 토큰 파일을 읽고 Codex에 변수를 제공합니다. 데스크톱, cron, 서비스에서 실행할 때는 shim을 선택하는 PATH 또는 실행기 경로를 사용해야 합니다. 설치 과정에서 이러한 환경이 자동으로 구성되지는 않습니다. Codex 자체의 자식 프로세스도 토큰을 상속할 수 있습니다.
+
+이 Bearer 토큰을 셸 시작 파일에서 내보내거나 `config.toml`에 복사하지 마세요. `service-api-token` 파일에는 `NAME=value` 형식의 대입문이 아닌 토큰 원문이 들어 있으므로 systemd의 `EnvironmentFile=`로 직접 사용할 수 없습니다.
+
+`opencodex-proxy.service`의 `EnvironmentFile=` 또는 `OCX_API_TOKEN_FILE`은 프록시 프로세스만 구성하며, 별도로 실행된 `codex exec`에 전달되지 않습니다.
+
+실행기를 교체하는 Codex 업그레이드는 shim을 제거합니다. 다음 일반 `ocx` 명령이 shim을 복원하지만(위 내용 참조), 그보다 먼저 실행되는 `codex exec`는 실패합니다. `ocx doctor`는 이 상태(env_key 구성됨, 변수 미설정, shim 누락 또는 비정상, 토큰 파일 존재)를 "Codex env_key launch readiness" 항목에서 복구 명령과 함께 보고하며, 토큰은 출력하지 않습니다. 토큰 파일 읽기는 주입된 `env_key`의 계약에 포함되지 않습니다. 실행을 시작하는 프로세스가 해당 변수를 제공해야 합니다.
+
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 Windows 상태 트레이 아이콘을 설치하고 제어합니다. Windows 로그인 시 시작되며, 프록시를 원클릭으로

@@ -445,31 +445,32 @@ Use `ocx service` for an always-on background proxy (recommended). Use `ocx code
 lightweight, on-demand startup without a daemon — the proxy starts only when `codex` is launched.
 :::
 
-#### Token injection without the shim
+#### Token injection into Codex
 
 On a non-loopback bind the injected provider carries `env_key = "OPENCODEX_API_AUTH_TOKEN"`. That
 line tells Codex which variable to read; it does not create it. Codex refuses to start a request
 when the variable is missing (`Missing environment variable: OPENCODEX_API_AUTH_TOKEN`), and the
-proxy is never reached. The value lives in `$OPENCODEX_HOME/service-api-token`; only a process that
-exports it into Codex's environment closes the gap.
+proxy is never reached. The value lives in `$OPENCODEX_HOME/service-api-token`; the launching process
+must supply it in Codex's environment.
 
-What does carry the token into a Codex process:
+Use the maintained shim installed by `ocx codex-shim install`. When the launching context resolves
+this shim, it reads the token file created by OpenCodex and supplies the variable to Codex.
+Desktop, cron, and service launches must use a PATH or launcher path that selects the shim;
+installation does not configure those environments automatically. Codex's own child processes
+may still inherit the token.
 
-- the shim installed by `ocx codex-shim install` (reads the token file at launch; the supported path
-  for Codex started from shells, Desktop, cron, or another service);
-- exporting `OPENCODEX_API_AUTH_TOKEN` yourself in the process that starts Codex — a shell profile,
-  the cron line, or an `Environment=`/`EnvironmentFile=` on the systemd unit that launches
-  **Codex** (not the proxy). Point it at the existing token file; do not copy the value into
-  `config.toml`.
+Do not export this bearer token from a shell startup file or copy it into `config.toml`. The
+`service-api-token` file contains the raw token, not `NAME=value` assignments, so it cannot be used
+directly as a systemd `EnvironmentFile=`.
 
-What does not: an `EnvironmentFile=` or `OCX_API_TOKEN_FILE` on `opencodex-proxy.service`. Those
-configure the proxy process only and never flow into an independently launched `codex exec`.
+An `EnvironmentFile=` or `OCX_API_TOKEN_FILE` on `opencodex-proxy.service` configures the proxy process
+only and never flows into an independently launched `codex exec`.
 
 A Codex upgrade that replaces the launcher removes the shim; the next ordinary `ocx` command restores
 it (see above), but a `codex exec` that runs before that fails. `ocx doctor` reports this exact
 state under "Codex env_key launch readiness" (env_key configured, variable unset, shim missing or
 unhealthy, token file present) with the repair command, and never prints the token. Reading the token
-file directly from Codex is not something Codex supports, so there is no OpenCodex directive for it.
+file is not part of the injected `env_key` contract; the launching process must supply that variable.
 
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 

@@ -319,6 +319,18 @@ ocx codex-shim uninstall
 когда запускается `codex`.
 :::
 
+#### Передача токена в Codex
+
+При привязке к адресу, отличному от loopback, внедрённый провайдер содержит `env_key = "OPENCODEX_API_AUTH_TOKEN"`. Эта строка указывает Codex, какую переменную читать, но не создаёт её. Если переменная отсутствует, Codex отказывается начинать запрос (`Missing environment variable: OPENCODEX_API_AUTH_TOKEN`), и запрос не доходит до прокси. Значение хранится в `$OPENCODEX_HOME/service-api-token`; запускающий процесс должен передать его в окружение Codex.
+
+Используйте поддерживаемую обёртку, устанавливаемую командой `ocx codex-shim install`. Если в контексте запуска выбирается эта обёртка, она читает файл токена, созданный OpenCodex, и передаёт переменную Codex. При запуске из настольной среды, cron или службы необходимо использовать PATH либо путь к средству запуска, который выбирает обёртку; установка не настраивает эти окружения автоматически. Собственные дочерние процессы Codex также могут унаследовать токен.
+
+Не экспортируйте этот Bearer-токен из файла запуска оболочки и не копируйте его в `config.toml`. Файл `service-api-token` содержит сам токен, а не присваивания вида `NAME=value`, поэтому его нельзя напрямую использовать как `EnvironmentFile=` в systemd.
+
+`EnvironmentFile=` или `OCX_API_TOKEN_FILE` в `opencodex-proxy.service` настраивает только процесс прокси и никогда не передаётся в независимо запущенный `codex exec`.
+
+Обновление Codex, заменяющее средство запуска, удаляет обёртку; следующая обычная команда `ocx` восстанавливает её (см. выше), но `codex exec`, запущенный до этого, завершается ошибкой. `ocx doctor` сообщает именно об этом состоянии в разделе "Codex env_key launch readiness" (env_key настроен, переменная не задана, обёртка отсутствует или неисправна, файл токена присутствует), приводит команду исправления и никогда не выводит токен. Чтение файла токена не входит в контракт внедрённого `env_key`; запускающий процесс должен передать эту переменную.
+
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 Установить и управлять Windows tray icon со статусом. Иконка стартует при логине в Windows и даёт

@@ -213,6 +213,18 @@ ocx codex-shim uninstall
 将 `ocx service` 用于始终在线的后台代理（推荐）。将 `ocx codex-shim` 用于无需守护进程的轻量按需启动——代理只会在启动 `codex` 时运行。
 :::
 
+#### 向 Codex 注入令牌
+
+绑定到非回环地址时，注入的提供程序包含 `env_key = "OPENCODEX_API_AUTH_TOKEN"`。这一行告诉 Codex 应读取哪个变量，但不会创建该变量。如果变量不存在，Codex 会拒绝发起请求（`Missing environment variable: OPENCODEX_API_AUTH_TOKEN`），请求也不会到达代理。变量值保存在 `$OPENCODEX_HOME/service-api-token` 中；启动进程必须将其传入 Codex 的环境。
+
+请使用通过 `ocx codex-shim install` 安装且受维护的 shim。如果启动上下文选择此 shim，它会读取 OpenCodex 创建的令牌文件，并将变量传给 Codex。从桌面、cron 或服务启动时，必须使用能够选中该 shim 的 PATH 或启动器路径；安装过程不会自动配置这些环境。Codex 自身的子进程也可能继承令牌。
+
+不要在 shell 启动文件中导出此 Bearer 令牌，也不要将其复制到 `config.toml`。`service-api-token` 文件包含的是原始令牌，而不是 `NAME=value` 形式的赋值，因此不能直接用作 systemd 的 `EnvironmentFile=`。
+
+`opencodex-proxy.service` 中的 `EnvironmentFile=` 或 `OCX_API_TOKEN_FILE` 仅配置代理进程，绝不会传入独立启动的 `codex exec`。
+
+替换启动器的 Codex 升级会移除 shim；下一次执行普通的 `ocx` 命令时会将其恢复（见上文），但在此之前运行的 `codex exec` 会失败。`ocx doctor` 会在 "Codex env_key launch readiness" 项下报告这一确切状态（env_key 已配置、变量未设置、shim 缺失或不正常、令牌文件存在），并给出修复命令，且绝不会输出令牌。读取令牌文件不属于注入的 `env_key` 的约定；启动进程必须提供该变量。
+
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 安装并控制 Windows 状态托盘图标。它会在 Windows 登录时启动，并提供一键代理控制。`start` 和 `stop` 只控制图标本身；要控制代理，请使用其菜单。`--no-start` 适用于 `install`，会安装托盘但不会立即启动。