docs: document OPENCODEX_API_AUTH_TOKEN and config recovery behavior

README (EN/KO): add "Remote access" subsection explaining non-loopback
token requirement, and note that invalid config.json is backed up before
fallback.

docs-site configuration reference (EN/KO): add hostname field to config
table, dedicated "Remote access" section with usage examples and security
caution, update opening paragraph to describe backup + warning behavior.

Closes #25, closes #24.

Author: lidge-jun

README.ko.md

@@ -171,7 +171,11 @@ npm uninstall -g @bitkyc08/opencodex   # 또는: bun remove -g @bitkyc08/opencod
 
 ## 설정
 
-설정 파일은 `~/.opencodex/config.json`에 저장됩니다. 최소 설정 예시:
+설정 파일은 `~/.opencodex/config.json`에 저장됩니다. 파일이 깨진 경우(잘못된 JSON 등)
+opencodex는 `config.json.invalid-<timestamp>`로 백업하고 경고를 출력한 뒤 기본값으로 시작합니다.
+원본 파일이 조용히 사라지는 일은 없습니다.
+
+최소 설정 예시:
 
 ```json
 {
@@ -209,6 +213,25 @@ npm uninstall -g @bitkyc08/opencodex   # 또는: bun remove -g @bitkyc08/opencod
 
 WebSocket 전송은 기본적으로 꺼져 있습니다. Codex가 HTTP/SSE 대신 Responses WebSocket 경로를 사용하게 하려면 `"websockets": true`를 설정하세요.
 
+### 원격 접근
+
+기본적으로 opencodex는 `127.0.0.1`(루프백)에 바인딩되며 별도 인증이 필요 없습니다.
+`"hostname": "0.0.0.0"`으로 LAN에 노출할 경우, opencodex는 관리 API(`/api/*`)와 데이터 플레인(`/v1/responses`) 모두에 bearer 토큰을 요구합니다:
+
+```bash
+export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
+ocx start
+```
+
+비루프백 바인딩 시 이 환경 변수가 없으면 프록시 시작이 거부됩니다.
+클라이언트(스크립트, 원격 머신)는 모든 요청에 토큰을 포함해야 합니다:
+
+```
+x-opencodex-api-key: your-secret-token
+```
+
+토큰은 타이밍 공격 방지를 위해 상수 시간으로 비교됩니다.
+
 모든 필드에 대한 자세한 내용은 **[설정 레퍼런스](https://lidge-jun.github.io/opencodex/ko/reference/configuration/)** 를 참고하세요.
 
 ## 문서

README.md

@@ -232,7 +232,11 @@ native Codex config/catalog/history, and deletes `~/.opencodex`.
 
 ## Configuration
 
-Config lives at `~/.opencodex/config.json`. Here's a typical multi-provider setup:
+Config lives at `~/.opencodex/config.json`. If the file cannot be parsed (e.g. truncated or
+manually broken JSON), opencodex backs it up to `config.json.invalid-<timestamp>`, prints a warning,
+and falls back to defaults — so your original file is never silently lost.
+
+Here's a typical multi-provider setup:
 
 ```json
 {
@@ -288,6 +292,26 @@ Local models work too. Point opencodex at any OpenAI-compatible server running o
 
 WebSocket transport is off by default. Set `"websockets": true` only if you want Codex to advertise and use the Responses WebSocket path instead of HTTP/SSE.
 
+### Remote access
+
+By default opencodex binds to `127.0.0.1` (loopback) and requires no extra authentication.
+If you set `"hostname": "0.0.0.0"` to expose the proxy on the LAN, opencodex requires a bearer token
+to protect both the management API (`/api/*`) and the data-plane (`/v1/responses`):
+
+```bash
+export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
+ocx start
+```
+
+The proxy refuses to start without this variable when binding beyond loopback.
+Clients (scripts, remote machines) must include the token in every request:
+
+```
+x-opencodex-api-key: your-secret-token
+```
+
+The token is compared in constant time to prevent timing attacks.
+
 opencodex leaves existing Codex resume history untouched by default. This avoids changing Codex's
 local thread index just because the proxy started, but Codex App may hide old OpenAI-backed project
 threads and opencodex-created `exec` threads while `opencodex` is the active provider. If you want

docs-site/src/content/docs/ko/reference/configuration.md

@@ -4,14 +4,17 @@ description: ~/.opencodex/config.json의 모든 필드 — 최상위 옵션, 프
 ---
 
 opencodex는 `~/.opencodex/config.json`으로 설정됩니다. 이 파일은 `ocx init`과 대시보드가
-작성하지만, 직접 편집할 수도 있습니다. 프록시는 시작 시 이 파일을 다시 읽습니다. 파일이 없거나
-유효하지 않으면 기본값(단일 `openai` 포워드 프로바이더)으로 폴백합니다.
+작성하지만, 직접 편집할 수도 있습니다. 프록시는 시작 시 이 파일을 다시 읽습니다. 파일을 파싱할 수
+없는 경우(잘못된 JSON 등) opencodex는 `config.json.invalid-<timestamp>`로 백업하고 콘솔에 경고를
+출력한 뒤 기본값으로 시작합니다. 파일이 아예 없으면 기본값(단일 `openai` 포워드 프로바이더)으로
+폴백합니다.
 
 ## 최상위 (`OcxConfig`)
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `port` | `number` | `10100` | 프록시가 수신 대기하는 포트. |
+| `hostname?` | `string` | `"127.0.0.1"` | 바인드 주소. LAN에 노출하려면 `"0.0.0.0"` 설정 (`OPENCODEX_API_AUTH_TOKEN` 필수; 아래 [원격 접근](#원격-접근) 참조). |
 | `providers` | `Record<string, OcxProviderConfig>` | — | 프로바이더 이름 → 설정 맵. |
 | `defaultProvider` | `string` | `"openai"` | 라우팅에서 더 나은 매치를 찾지 못했을 때 사용하는 프로바이더. |
 | `subagentModels?` | `string[]` | — | Codex의 서브에이전트 선택기에서 가장 먼저 노출되는 최대 5개의 `provider/model` id. |
@@ -36,6 +39,33 @@ store에 따로 저장됩니다. 기존 thread id는 계정 affinity를 유지
 health를 기준으로 자동 라우팅할 수 있습니다.
 :::
 
+## 원격 접근
+
+기본적으로 opencodex는 `127.0.0.1`(루프백 전용)에 바인딩됩니다. `hostname`을 `0.0.0.0` 같은
+비루프백 주소로 설정하면, opencodex는 관리 API(`/api/*`)와 데이터 플레인(`/v1/responses`) **모두**에
+토큰 인증을 강제합니다.
+
+시작 전에 `OPENCODEX_API_AUTH_TOKEN` 환경 변수를 설정하세요:
+
+```bash
+export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
+ocx start
+```
+
+비루프백 바인딩 시 이 변수가 없으면 프록시 시작이 거부됩니다. 클라이언트는 모든 요청에
+`x-opencodex-api-key` 헤더로 토큰을 포함해야 합니다:
+
+```
+x-opencodex-api-key: your-secret-token
+```
+
+토큰은 타이밍 사이드 채널 방지를 위해 상수 시간(`timingSafeEqual`)으로 비교됩니다.
+
+:::caution[LAN 노출]
+`0.0.0.0`으로 바인딩하면 프록시와 설정된 모든 프로바이더 인증 정보가 로컬 네트워크에 노출됩니다.
+신뢰할 수 있는 네트워크에서만 사용하고, 항상 강력한 `OPENCODEX_API_AUTH_TOKEN`을 설정하세요.
+:::
+
 ## 프로바이더 (`OcxProviderConfig`)
 
 | Field | Type | Meaning |

docs-site/src/content/docs/reference/configuration.md

@@ -4,14 +4,17 @@ description: Every field in ~/.opencodex/config.json — top-level options, prov
 ---
 
 opencodex is configured by `~/.opencodex/config.json`. It's written by `ocx init` and the dashboard,
-but you can edit it directly; the proxy reloads it on start. Missing or invalid files fall back to a
-default (a single `openai` forward provider).
+but you can edit it directly; the proxy reloads it on start. If the file cannot be parsed (e.g.
+truncated or invalid JSON), opencodex backs it up to `config.json.invalid-<timestamp>`, prints a
+console warning, and starts with defaults. Missing files also fall back to a default (a single
+`openai` forward provider).
 
 ## Top level (`OcxConfig`)
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
 | `port` | `number` | `10100` | Port the proxy listens on. |
+| `hostname?` | `string` | `"127.0.0.1"` | Bind address. Set `"0.0.0.0"` to expose on the LAN (requires `OPENCODEX_API_AUTH_TOKEN`; see [Remote access](#remote-access) below). |
 | `providers` | `Record<string, OcxProviderConfig>` | — | Map of provider name → config. |
 | `defaultProvider` | `string` | `"openai"` | Provider used when routing finds no better match. |
 | `subagentModels?` | `string[]` | — | Up to 5 `provider/model` ids featured first in Codex's subagent picker. |
@@ -36,6 +39,33 @@ credential store. Existing thread ids keep account affinity, while new sessions
 on quota, cooldown, and health.
 :::
 
+## Remote access
+
+By default opencodex binds to `127.0.0.1` (loopback only). When `hostname` is set to a non-loopback
+address such as `0.0.0.0`, opencodex enforces token authentication on **both** the management API
+(`/api/*`) and the data-plane (`/v1/responses`).
+
+Set the `OPENCODEX_API_AUTH_TOKEN` environment variable before starting:
+
+```bash
+export OPENCODEX_API_AUTH_TOKEN="your-secret-token"
+ocx start
+```
+
+The proxy refuses to start without this variable when binding beyond loopback. Clients must include
+the token in every request via the `x-opencodex-api-key` header:
+
+```
+x-opencodex-api-key: your-secret-token
+```
+
+The token is compared in constant time (`timingSafeEqual`) to prevent timing side-channels.
+
+:::caution[LAN exposure]
+Binding to `0.0.0.0` exposes your proxy — and all configured provider credentials — to the local
+network. Only do this on trusted networks, and always set a strong `OPENCODEX_API_AUTH_TOKEN`.
+:::
+
 ## Providers (`OcxProviderConfig`)
 
 | Field | Type | Meaning |