fix(openai): clarify auth routes in picker and docs

src/commands/model-picker.test.ts

@@ -88,6 +88,46 @@ beforeEach(() => {
 });
 
 describe("promptDefaultModel", () => {
+  it("adds auth-route hints for OpenAI API and Codex OAuth models", async () => {
+    loadModelCatalog.mockResolvedValue([
+      {
+        provider: "openai",
+        id: "gpt-5.4",
+        name: "GPT-5.4",
+      },
+      {
+        provider: "openai-codex",
+        id: "gpt-5.4",
+        name: "GPT-5.4",
+      },
+    ]);
+
+    const select = vi.fn(async (params) => params.initialValue as never);
+    const prompter = makePrompter({ select });
+
+    await promptDefaultModel({
+      config: { agents: { defaults: {} } } as OpenClawConfig,
+      prompter,
+      allowKeep: false,
+      includeManual: false,
+      ignoreAllowlist: true,
+    });
+
+    const options = select.mock.calls[0]?.[0]?.options ?? [];
+    expect(options).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          value: "openai/gpt-5.4",
+          hint: expect.stringContaining("API key route"),
+        }),
+        expect.objectContaining({
+          value: "openai-codex/gpt-5.4",
+          hint: expect.stringContaining("ChatGPT OAuth route"),
+        }),
+      ]),
+    );
+  });
+
   it("treats byteplus plan models as preferred-provider matches", async () => {
     loadModelCatalog.mockResolvedValue([
       {

src/flows/model-picker.ts

@@ -115,6 +115,17 @@ function normalizeModelKeys(values: string[]): string[] {
   return next;
 }
 
+function resolveModelRouteHint(provider: string): string | undefined {
+  const normalized = normalizeProviderId(provider);
+  if (normalized === "openai") {
+    return "API key route";
+  }
+  if (normalized === "openai-codex") {
+    return "ChatGPT OAuth route";
+  }
+  return undefined;
+}
+
 function addModelSelectOption(params: {
   entry: {
     provider: string;
@@ -146,6 +157,10 @@ function addModelSelectOption(params: {
   if (aliases?.length) {
     hints.push(`alias: ${aliases.join(", ")}`);
   }
+  const routeHint = resolveModelRouteHint(params.entry.provider);
+  if (routeHint) {
+    hints.push(routeHint);
+  }
   if (!params.hasAuth(params.entry.provider)) {
     hints.push("auth missing");
   }