Add user guide for setting OPENCODEX_ADMIN_AUTH_TOKEN

[Tao-Yida]

Area

Dashboard

What are you trying to accomplish?

For users updating Opencodex to v2.40.0, add a brief guide to set an authentication token, not just ask users to provide one which they might not know what it is.

What prevents this today?

Today I updated Opencodex to v2.40.0, and was prohibited from accessing the dashboard. At first I thought it was a critical bug/config loss during update, but later I used a LLM to scan the codebase and was told it is a new security feature. Thus I asked the LLM to generate a token and save it to config.
But those who do not carefully read changelogs might not be able to figure out how to configure an OPENCODEX_ADMIN_AUTH_TOKEN when seeing the panel popped up in dashboard. Thus I believe a brief guide would help for clarification and better user experience.

What should OpenCodex do?

Add user guide for setting OPENCODEX_ADMIN_AUTH_TOKEN in Opencodex dashboard.

Example usage or interface

1. Start OpenCodex
2. Open Opencodex dashboard
3. Asked to filling OPENCODEX_ADMIN_AUTH_TOKEN
4. Know how to generate one and save it to config
5. Do not need to provide token every time when opening dashboard

Alternatives or workarounds

No response

Additional context

No response

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.

[lidge-jun]

리뷰 · 우선순위 48 / 80

이 이슈는 대시보드가 관리자 토큰을 물을 때, 이름만 보여 주고 “어디서 만들고 어디에 넣는지”는 안 알려 줘서 v2.40.0 업데이트 후 막힌 사용자가 LLM으로 우회했다는 UX/안내 요청입니다. 보안 모델 자체를 바꾸자는 말은 아닙니다. 지금 dev(78c630a93)를 기준으로 보면, 관리 평면 인증은 이미 src/server/management-auth.ts와 src/lib/admin-secrets.ts에 있습니다. 토큰 출처는 (1) 환경변수 OPENCODEX_ADMIN_AUTH_TOKEN, (2) 없으면 설정 디렉터리의 admin-api-token 파일(보통 ~/.opencodex/admin-api-token, 형태는 ocx_admin_…) 입니다. GUI 쪽 입력창은 gui/src/admin-token-dialog.ts이고, 제목 문자열만 i18n 키 auth.adminTokenTitle로 환경변수 이름을 보여 줍니다. 계정 칸은 비밀번호 관리자 호환용으로 “OpenCodex” 고정, 토큰은 password 필드이며, 앱은 메모리에만 두고 localStorage에는 안 씁니다.

문서에는 이미 같은 이야기가 있습니다. docs-site/src/content/docs/guides/web-dashboard.md(및 ko/ja/zh 등 번역) Sign-in 절에, loopback(localhost/127.0.0.1)에서는 짧은 GUI 세션이 자동이라 보통 토큰을 안 묻고, loopback이 아닌 호스트로 공개할 때만 관리자 토큰이 필요하다고 적혀 있습니다. 즉 “토큰을 매번 새로 만들어야 한다”가 기본 동작은 아닙니다. 제보자가 업데이트 직후 막혔다면, (a) 비-loopback으로 대시보드를 연 경우, (b) GUI 세션 발급/갱신이 실패한 경우, (c) 파일 ACL 하드닝 실패로 env 토큰을 강제하는 경우 같은 왜 프롬프트가 떴는지를 먼저 가르는 게 맞습니다. 안내는 그다음에 붙이면 됩니다.

요청의 핵심은 다이얼로그 안에 “생성·저장 방법”을 짧게 넣자는 것입니다. 지금 다이얼로그에는 how-to 문단·문서 링크·파일 경로 힌트가 없습니다. 그래서 changelog를 안 읽은 사용자는 환경변수 이름만 보고 멈춥니다. 반대로 문서를 길게 복제하거나, 토큰을 브라우저에 자동 저장하거나, 인증을 느슨하게 만드는 방향은 현재 설계(세션·Origin/CSRF·관리 평면 분리)와 충돌합니다. 좋은 범위는 다이얼로그에 2~4줄 안내 + 문서 앵커 링크, 그리고 가능하면 “loopback이면 보통 자동 로그인” 한 줄을 같이 넣는 것입니다.

gui/src/admin-token-dialog.ts - 제목/필드만 있고 how-to 없음. 여기에 짧은 안내 DOM(또는 i18n 문단)을 넣는 게 이 이슈의 본진.
gui/src/i18n/*.ts (auth.adminTokenTitle 근처) - 안내 문장을 키로 추가해야 다국어 다이얼로그가 같이 감. 제목에 env 이름만 있는 상태는 유지해도 됨.
docs-site/.../guides/web-dashboard.md - Sign-in 절에 이미 설명이 있음. 다이얼로그에서 여기로 링크하면 중복 장문 복붙을 피할 수 있음.
src/lib/admin-secrets.ts / src/server/management-auth.ts - 토큰 생성·ACL 로직은 이미 있음. 이 이슈 때문에 인증 게이트를 약화하거나 “토큰 없이 통과”를 넣지 말 것.
제보 재현 조건 - loopback인지, 원격 바인드인지, 업데이트 직후 세션 유실인지가 본문에 없음. 가이드만 넣고 원인을 안 가르면 “왜 갑자기 묻냐” 혼란이 남음.

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

• 안내를 다이얼로그 인라인만 할지, 문서 링크만 할지, 둘 다 할지.
• “파일에 자동 생성된 토큰을 보여 주기 / 복사 버튼”까지 갈지(편리 vs 스크린 공유·원격 노출 위험).
• v2.40 업그레이드 노트에 한 줄 경고를 추가로 넣을지, GUI 수정만으로 충분한지.

너의 추천
help wanted로 두고, 범위는 gui/src/admin-token-dialog.ts + i18n 키에 짧은 설정 안내(환경변수 또는 ~/.opencodex/admin-api-token) 와 docs-site web-dashboard Sign-in 링크를 추가하는 PR이 좋습니다. 인증 로직·토큰 저장 정책은 건드리지 마세요. 가능하면 이슈 작성자에게 loopback 여부/접속 URL을 한 줄 확인받아, “원래 안 물어야 하는 경우”면 세션 버그 쪽으로 라벨을 나누는 게 맞습니다.

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

[lidge-jun]

Landed via #3496 at 3e65218

dev now only prompts for an admin token when the bind actually requires one (isApiAuthRequired); plain loopback gets an actionable Host/Origin notice instead of an unfillable password box.

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

[lidge-jun]

Already on dev via #3496 (3e65218). Closing.

[lidge-jun]

Fixed on dev in #3496 (3e65218ba), with the documentation half in #3493.

Your report turned out to describe two separate defects, and the more serious one is that you should never have seen that prompt at all.

A loopback install mints its own dashboard session, so it needs no typed credential — the Sign-in guide already promised "on the default loopback bind the dashboard never asks for a token". But the client treated any definitive session refusal as "ask the human for a token". On loopback the only ways to get that refusal are a Host or Origin mismatch, which no admin token can repair. So the box you were shown could not have helped even with the right value in it, which is exactly why reading the source was the only way forward. That prompt is now reserved for a bind that genuinely requires a credential; otherwise the dashboard names the real cause.

The second half is your original request. When the prompt is legitimate, it now says what the credential is (the management admin token, not a provider API key), that the proxy already wrote it to ~/.opencodex/admin-api-token — or $OPENCODEX_HOME/admin-api-token — and that OPENCODEX_ADMIN_AUTH_TOKEN overrides it, with a link to a new "Finding the admin token" section. That section is explicit that there is no CLI which prints the token, since ocx doctor deliberately reports presence without revealing a value; that absence is worth stating outright, because looking for such a command is the natural next step.

Copy landed in all nine locales.

Thanks for filing this. Framing it as "users might not be able to figure out how" is what surfaced the deeper bug.