feat(vlm): add Codex OAuth-backed VLM setup and docs

[ehz0ah]

Description

Add Codex as an OAuth-backed VLM provider for OpenViking, so users can configure and use Codex vision/text generation through the normal OV setup flow instead of wiring credentials manually.

This change integrates Codex across provider resolution, interactive setup, diagnostics, and CLI auth management. It also keeps Codex auth under an OV-owned store, with bootstrap/import support from existing Codex CLI state when available.

Related Issue

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• openviking/models/vlm/backends/codex_auth.py: Add Codex OAuth storage, bootstrap/import, status inspection, token refresh, and OV-owned credential persistence.
• openviking/models/vlm/backends/codex_vlm.py: Add the Codex VLM backend and Responses API adapter for text, vision, tool-call, and streaming-compatible flows.
• openviking_cli/codex_cli.py: Add ov codex login, status, and logout commands for managing OV-side Codex auth.
• openviking_cli/setup_wizard.py: Add Codex as an interactive VLM choice in cloud setup and support device-login/bootstrap during init.
• openviking_cli/doctor.py and openviking_cli/utils/config/vlm_config.py: Extend provider normalization, readiness checks, and diagnostics so Codex resolves like other supported VLMs.
• Docs / examples / tests: Update English and Chinese docs, config examples, and add coverage for auth, config resolution, setup, and Codex VLM behavior.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published

Screenshots (if applicable)

macOS setup flow for Codex OAuth-backed VLM initialization:

$ openviking-server init

  OpenViking Setup
  ================

  Choose setup mode:

    [1] Local models via Ollama  (recommended for macOS / Apple Silicon)
    [2] Cloud / hosted models  (OpenAI, Volcengine, etc.)
    [3] Custom  (manual editing)

  Select [1]: 2

  Cloud provider:

    [1] OpenAI
    [2] Volcengine (Doubao)
    [3] Other (manual)

  Select [1]: 2

  Embedding configuration
  API Key: <redacted>
  Model [doubao-embedding-vision-250615]: doubao-embedding-vision-251215
  Dimension [1024]: 1024
  API Base [https://ark.cn-beijing.volces.com/api/v3]: https://ark.cn-beijing.volces.com/api/v3

  VLM provider:

    [1] Volcengine (Doubao)  (API key)
    [2] OpenAI Codex  (Subscription)

  Select [1]: 2

  Checking Codex OAuth... not ready
  Sign in to Codex now? [Y/n]: y
  Open this URL in your browser:
    https://auth.openai.com/codex/device
  Enter this code:
    <redacted>
  Waiting for sign-in...
    OK Codex OAuth stored in /Users/bytedance/.openviking/codex_auth.json

  Codex VLM configuration
  Model: gpt-5.3-codex
  Using default API Base: https://chatgpt.com/backend-api/codex
  Using default Workspace: /Users/bytedance/.openviking/data

  Summary:
    Embedding:  volcengine / doubao-embedding-vision-251215 (1024d)
    VLM:        openai-codex / gpt-5.3-codex
    Workspace:  /Users/bytedance/.openviking/data
    Config:     /Users/bytedance/.openviking/ov.conf

  Save configuration? [Y/n]: y
    OK Configuration written to /Users/bytedance/.openviking/ov.conf

  Next steps:
    Start the server:  openviking-server
    Validate setup:    openviking-server doctor
    Check Codex auth:  ov codex status

Additional Notes

Auth ownership: OpenViking keeps its own Codex auth store at ~/.openviking/codex_auth.json, while still supporting bootstrap/import from existing Codex CLI auth when present.

Runtime behavior: Codex provider resolution is shared across setup, doctor, CLI status, and runtime VLM initialization so the same readiness rules apply in all entry points.

Follow-up fixes: Added AGPL headers to the new Codex files, added Windows byte-range locking for the shared auth store, and deferred async credential/client setup into the worker-thread execution path.

Validation: Ran uv run python -m pytest tests/cli/test_codex_cli.py tests/cli/test_doctor.py tests/cli/test_setup_wizard.py tests/unit/test_codex_vlm.py -q with 58 passing tests.

[CLAassistant]

All committers have signed the CLA.

[github-actions]

PR Reviewer Guide 🔍

(Review updated until commit 7a88033)

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🏅 Score: 90

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 Multiple PR themes Sub-PR theme: Add Codex VLM backend and auth core Relevant files: openviking/models/vlm/backends/codex_auth.py openviking/models/vlm/backends/codex_vlm.py openviking/models/vlm/init.py openviking/models/vlm/registry.py openviking/models/vlm/base.py tests/unit/test_codex_vlm.py Sub-PR theme: Add CLI integration for Codex auth and setup Relevant files: openviking_cli/codex_cli.py openviking_cli/setup_wizard.py openviking_cli/doctor.py openviking_cli/utils/config/vlm_config.py openviking_cli/rust_cli.py tests/cli/test_codex_cli.py tests/cli/test_setup_wizard.py tests/cli/test_doctor.py Sub-PR theme: Update documentation for Codex VLM Relevant files: README.md README_CN.md docs/zh/getting-started/02-quickstart.md

⚡ No major issues detected

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[github-actions]

Persistent review updated to latest commit 7a88033

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.