feat(codex-ui): surface cliproxy setup guidance

ui/src/components/compatible-cli/codex-docs-tab.tsx

@@ -44,6 +44,13 @@ const DEFAULT_PROVIDER_DOCS: CompatibleCliProviderDocLink[] = [
   },
 ];
 
+const CLIPROXY_NATIVE_CODEX_RECIPE = `model_provider = "cliproxy"
+
+[model_providers.cliproxy]
+base_url = "http://127.0.0.1:8317/api/provider/codex"
+env_key = "CLIPROXY_API_KEY"
+wire_api = "responses"`;
+
 function renderTextWithLinks(text: string): ReactNode[] {
   const urlPattern = /https?:\/\/[^\s)]+/g;
   const nodes: ReactNode[] = [];
@@ -98,6 +105,36 @@ export function CodexDocsTab({ diagnostics }: CodexDocsTabProps) {
   return (
     <ScrollArea className="h-full">
       <div className="space-y-4 pr-1">
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="flex items-center gap-2 text-base">
+              <ShieldCheck className="h-4 w-4" />
+              CCS bridge recipe
+            </CardTitle>
+          </CardHeader>
+          <CardContent className="space-y-3 text-sm text-muted-foreground">
+            <p>
+              Use <code>ccsxp</code> if you want the built-in CCS Codex provider shortcut on native
+              Codex. Use the saved recipe below if you want plain <code>codex</code> or a personal
+              alias like <code>cxp</code> to default to CLIProxy.
+            </p>
+            <pre className="overflow-x-auto rounded-md border bg-muted/20 p-3 text-xs text-foreground">
+              {CLIPROXY_NATIVE_CODEX_RECIPE}
+            </pre>
+            <div className="space-y-1">
+              <p>
+                1. Save the <code>cliproxy</code> provider in your user config.
+              </p>
+              <p>
+                2. Set top-level <code>model_provider</code> to <code>cliproxy</code>.
+              </p>
+              <p>
+                3. Export <code>CLIPROXY_API_KEY</code> in your shell before launching native Codex.
+              </p>
+            </div>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader className="pb-2">
             <CardTitle className="flex items-center gap-2 text-base">

ui/src/components/compatible-cli/codex-model-providers-card.tsx

@@ -33,6 +33,16 @@ const EMPTY_MODEL_PROVIDER_DRAFT: CodexModelProviderEntry = {
   supportsWebsockets: false,
 };
 
+const CLIPROXY_CODEX_PROVIDER_PRESET: CodexModelProviderEntry = {
+  name: 'cliproxy',
+  displayName: 'CLIProxy Codex',
+  baseUrl: 'http://127.0.0.1:8317/api/provider/codex',
+  envKey: 'CLIPROXY_API_KEY',
+  wireApi: 'responses',
+  requiresOpenaiAuth: false,
+  supportsWebsockets: false,
+};
+
 interface ModelProviderEditorProps {
   initialDraft: CodexModelProviderEntry;
   isNew: boolean;
@@ -56,6 +66,23 @@ function ModelProviderEditor({
 
   return (
     <>
+      {isNew && (
+        <div className="flex flex-wrap items-center justify-between gap-2 rounded-md border border-dashed px-3 py-2 text-xs text-muted-foreground">
+          <p>
+            Quick start: apply the CLIProxy Codex preset here, then set{' '}
+            <strong>Default provider</strong> to <code>cliproxy</code> in Top-level settings.
+          </p>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => setDraft(CLIPROXY_CODEX_PROVIDER_PRESET)}
+            disabled={disabled}
+          >
+            Use CLIProxy Codex preset
+          </Button>
+        </div>
+      )}
+
       <div className="grid gap-3 sm:grid-cols-2">
         <Input
           value={draft.name}
@@ -146,6 +173,12 @@ function ModelProviderEditor({
           Save provider
         </Button>
       </div>
+
+      <p className="text-xs text-muted-foreground">
+        If you want plain native <code>codex</code> to default to CLIProxy, save a provider named{' '}
+        <code>cliproxy</code> with <code>CLIPROXY_API_KEY</code> here, then pick{' '}
+        <code>cliproxy</code> in the <strong>Default provider</strong> control above.
+      </p>
     </>
   );
 }

ui/src/components/compatible-cli/codex-overview-tab.tsx

@@ -24,6 +24,13 @@ import {
 import type { CodexDashboardDiagnostics } from '@/hooks/use-codex-types';
 import { cn } from '@/lib/utils';
 
+const CLIPROXY_NATIVE_CODEX_RECIPE = `model_provider = "cliproxy"
+
+[model_providers.cliproxy]
+base_url = "http://127.0.0.1:8317/api/provider/codex"
+env_key = "CLIPROXY_API_KEY"
+wire_api = "responses"`;
+
 function formatTimestamp(value: number | null | undefined): string {
   if (!value || !Number.isFinite(value)) return 'N/A';
   return new Date(value).toLocaleString();
@@ -70,6 +77,17 @@ export function CodexOverviewTab({ diagnostics }: CodexOverviewTabProps) {
           </CardHeader>
           <CardContent className="space-y-2 text-sm text-muted-foreground">
             <p>Codex is a first-class runtime target in CCS, but it stays runtime-only in v1.</p>
+            <p>
+              <code>ccs-codex</code> and <code>ccsx</code> launch native Codex against your saved
+              native config, while <code>ccsxp</code> is the opinionated shortcut for{' '}
+              <code>ccs codex --target codex</code>.
+            </p>
+            <p>
+              Plain <code>codex</code> or a personal alias like <code>cxp</code> needs{' '}
+              <code>model_provider = "cliproxy"</code> plus a matching{' '}
+              <code>[model_providers.cliproxy]</code> entry if you want CLIProxy as the saved native
+              default.
+            </p>
             <p>
               Saved default targets for API profiles and variants still remain on Claude or Droid.
             </p>
@@ -103,7 +121,8 @@ export function CodexOverviewTab({ diagnostics }: CodexOverviewTabProps) {
               mono
             />
             <DetailRow label="Version" value={diagnostics.binary.version || 'Unknown'} mono />
-            <DetailRow label="Alias commands" value="ccs-codex, ccsx" mono />
+            <DetailRow label="Native aliases" value="ccs-codex, ccsx" mono />
+            <DetailRow label="CCS provider shortcut" value="ccsxp" mono />
             <div className="flex items-center justify-between rounded-md border px-3 py-2">
               <span className="text-sm text-muted-foreground">--config override support</span>
               <Badge variant={diagnostics.binary.supportsConfigOverrides ? 'default' : 'secondary'}>
@@ -113,6 +132,40 @@ export function CodexOverviewTab({ diagnostics }: CodexOverviewTabProps) {
           </CardContent>
         </Card>
 
+        <Card>
+          <CardHeader className="pb-2">
+            <CardTitle className="flex items-center gap-2 text-base">
+              <Route className="h-4 w-4" />
+              CLIProxy-backed native Codex
+            </CardTitle>
+          </CardHeader>
+          <CardContent className="space-y-3 text-sm text-muted-foreground">
+            <p>
+              There are two supported paths. Use <code>ccsxp</code> if you want the built-in CCS
+              Codex provider shortcut. Use the saved recipe below if you want plain{' '}
+              <code>codex</code> or a personal alias like <code>cxp</code> to default to CLIProxy.
+            </p>
+            <div className="rounded-md border bg-muted/20 p-3">
+              <p className="font-medium text-foreground">Saved native Codex recipe</p>
+              <pre className="mt-2 overflow-x-auto rounded-md bg-background p-3 text-xs text-foreground">
+                {CLIPROXY_NATIVE_CODEX_RECIPE}
+              </pre>
+            </div>
+            <div className="space-y-1">
+              <p>
+                1. Save a provider named <code>cliproxy</code> with the base URL and env key above.
+              </p>
+              <p>
+                2. In <strong>Top-level settings</strong>, set <strong>Default provider</strong> to{' '}
+                <code>cliproxy</code>.
+              </p>
+              <p>
+                3. Export <code>CLIPROXY_API_KEY</code> in your shell before launching native Codex.
+              </p>
+            </div>
+          </CardContent>
+        </Card>
+
         <Card>
           <CardHeader className="pb-2">
             <CardTitle className="flex items-center gap-2 text-base">
@@ -213,19 +266,19 @@ export function CodexOverviewTab({ diagnostics }: CodexOverviewTabProps) {
         <QuickCommands
           snippets={[
             {
-              label: 'Native Codex',
-              command: 'ccs-codex',
-              description: 'Launch the native Codex runtime alias.',
-            },
-            {
-              label: 'Short alias',
+              label: 'Native short alias',
               command: 'ccsx',
-              description: 'Launch the short Codex runtime alias.',
+              description: 'Launch the short native Codex runtime alias.',
             },
             {
-              label: 'Target override',
+              label: 'CCS Codex shortcut',
+              command: 'ccsxp "your prompt"',
+              description: 'Run the built-in CCS Codex provider on native Codex.',
+            },
+            {
+              label: 'Explicit provider route',
               command: 'ccs codex --target codex "your prompt"',
-              description: 'Run a CCS profile on the native Codex target.',
+              description: 'Use the explicit built-in Codex provider route.',
             },
             {
               label: 'Workspace trust',
@@ -246,17 +299,16 @@ export function CodexOverviewTab({ diagnostics }: CodexOverviewTabProps) {
             <div className="rounded-md border p-3 text-sm">
               <p className="font-medium">Native Codex runtime</p>
               <p className="mt-1 text-muted-foreground">
-                Use <code>ccs-codex</code>, <code>ccsx</code>, or <code>--target codex</code>. CCS
-                launches the local Codex CLI and depends on native Codex capabilities such as{' '}
-                <code>--config</code> overrides.
+                Use <code>ccs-codex</code>, <code>ccsx</code>, or <code>--target codex</code> when
+                you want the local Codex CLI to honor your saved native user config.
               </p>
             </div>
             <div className="rounded-md border p-3 text-sm">
-              <p className="font-medium">Codex provider / bridge</p>
+              <p className="font-medium">CCS Codex provider / bridge</p>
               <p className="mt-1 text-muted-foreground">
-                CCS can route provider credentials transiently through CLIProxy. That is not the
-                same as editing local <code>config.toml</code>, and some routed values may never
-                persist here.
+                Use <code>ccsxp</code> or <code>ccs codex --target codex</code> when you want the
+                built-in CCS Codex provider on native Codex. That path uses transient CCS-managed
+                overrides and is separate from the saved <code>cliproxy</code> recipe above.
               </p>
             </div>
           </CardContent>