Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

feat(voice): explain the missing OpenAI key where it can be fixed

Chaitanya Giri9e5cc522367d
diff --git a/src/main/realtime.ts b/src/main/realtime.ts
index 86840ce3..fadaaf00 100644
--- a/src/main/realtime.ts
+++ b/src/main/realtime.ts
@@ -24,8 +24,11 @@ import { getSecret, hasSecret } from './integrations';
const OPENAI_KEY_REF = 'apikey:openai';
/** GA speech-to-speech model for the voice orchestrator (v0.3.4: bumped to the
- * July 2026 gpt-realtime-2.1 — 25% p95 latency cut, better interruption handling). */
-export const REALTIME_MODEL = 'gpt-realtime-2.1';
+ * July 2026 gpt-realtime-2.1 — 25% p95 latency cut, better interruption handling).
+ * Defined in shared/ and re-exported here: Settings names this model in copy the
+ * user reads, so main and the UI must not be able to disagree about it. */
+export { REALTIME_MODEL } from '../shared/realtimePricing';
+import { REALTIME_MODEL } from '../shared/realtimePricing';
/** GA ephemeral-secret mint endpoint. If an account/tier still answers the legacy
* beta shape, we fall back to /v1/realtime/sessions on a 404 and normalize both
@@ -51,7 +54,7 @@ export function hasOpenAiKey(): boolean {
export async function mintRealtimeToken(model: string = REALTIME_MODEL): Promise<MintResult> {
const key = getSecret(OPENAI_KEY_REF);
if (!key) {
- return { ok: false, error: 'no OpenAI API key set — add one in Settings → AI Engines', code: 'no_key' };
+ return { ok: false, error: 'no OpenAI API key set — add one in Settings → Voice', code: 'no_key' };
}
const post = async (url: string, body: unknown) => {
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 9ac4f7ff..b7a28a14 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -17,7 +17,7 @@ import { CompletionToast } from '@/realtime/CompletionToast';
import { UpdateToast } from '@/components/UpdateToast';
import { UpdateBadge } from '@/components/UpdateBadge';
import { useAppTheme, toggleAppTheme } from '@/design/theme';
-import { SettingsModal } from '@/components/SettingsModal';
+import { SettingsModal, type Section as SettingsSection } from '@/components/SettingsModal';
import { PixelPanel } from '@/components/PixelPanel';
import { PixelButton } from '@/components/PixelButton';
import { Icon } from '@/components/Icon';
@@ -63,10 +63,28 @@ export function App() {
return false;
});
const [settingsOpen, setSettingsOpen] = useState(false);
+ /** Which tab Settings opens on. Set by a `cth:open-settings` deep link, reset
+ * to undefined (→ General) whenever the modal is opened the normal way. */
+ const [settingsSection, setSettingsSection] = useState<SettingsSection | undefined>(undefined);
const [quitWarn, setQuitWarn] = useState<{ ptyCount: number } | null>(null);
const [closing, setClosing] = useState<ClosingTimeState | null>(null);
const [vpWidth, setVpWidth] = useState<number>(window.innerWidth);
+ // Deep link into Settings from anywhere in the tree. Settings' open state is
+ // local to App, so a nested control (e.g. "set it now" beside a disabled Talk
+ // button) has no path to it without threading a prop through every layer
+ // between; a window event keeps that plumbing out of the components in
+ // between, matching the existing `cth:` CustomEvent convention.
+ useEffect(() => {
+ const onOpenSettings = (e: Event): void => {
+ const section = (e as CustomEvent<{ section?: SettingsSection }>).detail?.section;
+ setSettingsSection(section);
+ setSettingsOpen(true);
+ };
+ window.addEventListener('cth:open-settings', onOpenSettings);
+ return () => window.removeEventListener('cth:open-settings', onOpenSettings);
+ }, []);
+
// Initial config load
useEffect(() => {
let cancelled = false;
@@ -314,7 +332,7 @@ export function App() {
(sidebar detail, god Command Center, fullscreen) carries it. */}
<button
className="cth-titlebar-nodrag cth-settings-btn"
- onClick={() => setSettingsOpen(true)}
+ onClick={() => { setSettingsSection(undefined); setSettingsOpen(true); }}
title="Settings"
aria-label="Settings"
style={{
@@ -426,7 +444,11 @@ export function App() {
)}
{settingsOpen && (
- <SettingsModal config={config} onClose={() => setSettingsOpen(false)} />
+ <SettingsModal
+ config={config}
+ initialSection={settingsSection}
+ onClose={() => { setSettingsOpen(false); setSettingsSection(undefined); }}
+ />
)}
{quitWarn && (
diff --git a/src/renderer/src/components/RealtimeMichaelToggle.tsx b/src/renderer/src/components/RealtimeMichaelToggle.tsx
index ab54d3b0..0dd75bc5 100644
--- a/src/renderer/src/components/RealtimeMichaelToggle.tsx
+++ b/src/renderer/src/components/RealtimeMichaelToggle.tsx
@@ -16,6 +16,8 @@
* Rendered in two places (AgentCard for the god card, FullscreenTerminal header when
* Michael is fullscreen). It is intentionally state-only / hook-only so both can mount it.
*/
+import { useEffect, useRef, useState, type MouseEvent } from 'react';
+import { createPortal } from 'react-dom';
import { PixelButton } from './PixelButton';
import { Icon } from './Icon';
import { useStore } from '@/store/store';
@@ -83,17 +85,26 @@ export interface RealtimeMichaelToggleProps {
export function RealtimeMichaelToggle({ compact = false }: RealtimeMichaelToggleProps) {
const hasOpenAiKey = useStore((s) => s.hasOpenAiKey);
const { status, error, connect, disconnect } = useRealtimeMichael();
+ // Measured viewport coords, not a CSS offset. The agent dock clips its
+ // children, so a popover positioned inside the card gets sliced at the card's
+ // edge no matter how it is anchored — which is exactly what happened. A portal
+ // to <body> with fixed coordinates leaves that clipping context entirely.
+ const [hint, setHint] = useState<{ left: number; top: number } | null>(null);
+ const hintRef = useRef<HTMLSpanElement | null>(null);
+ const iconRef = useRef<HTMLButtonElement | null>(null);
+ const panelRef = useRef<HTMLDivElement | null>(null);
+ const hintOpen = hint !== null;
const view = STATE_VIEW[status];
const noKey = !hasOpenAiKey;
// Without a BYOK OpenAI key: stay visible but disabled (matches FreeFlowButton).
// Talk mints an ephemeral token from the OpenAI key (apikey:openai) — the SAME
- // OpenAI provider key set under AI Engines, used for the Realtime voice API. The
- // tooltip carries the full WHY; the inline chip below gives a discoverable cue so
- // the user never just hits a silently-dead button on connect.
+ // OpenAI provider key set under Agents & Models, used for the Realtime voice API.
+ // The tooltip carries the full WHY; the quiet info affordance below gives a
+ // discoverable cue so the user never just hits a silently-dead button.
const title = noKey
- ? 'Talk needs your OpenAI API key (used for the Realtime voice API). Add it in Settings → AI Engines.'
+ ? 'Talk needs your OpenAI API key (used for the Realtime voice API). Add it in Settings → Voice.'
: error
? `${view.help} — ${error}`
: view.help;
@@ -104,13 +115,78 @@ export function RealtimeMichaelToggle({ compact = false }: RealtimeMichaelToggle
else disconnect();
};
+ // Jump straight to the tab that holds the key. App owns the Settings modal's
+ // open state, so this goes through the `cth:` window-event convention rather
+ // than threading a callback down through AgentCard/FullscreenTerminal.
+ // Target is VOICE, not Agents & Models: the key is settable in both, but only
+ // one of them explains what it is for.
+ const openKeySettings = (e: MouseEvent): void => {
+ e.stopPropagation();
+ setHint(null);
+ window.dispatchEvent(
+ new CustomEvent('cth:open-settings', { detail: { section: 'Voice' } })
+ );
+ };
+
+ const HINT_W = 210;
+ const HINT_GAP = 8;
+
+ /** Place the popover against the icon in VIEWPORT space, preferring above and
+ * flipping below only when there is genuinely no room — the agent dock sits on
+ * the bottom edge, so "above" is almost always right. Both axes are clamped to
+ * the viewport so it can never hang off an edge. */
+ const toggleHint = (e: MouseEvent): void => {
+ e.stopPropagation();
+ if (hint) { setHint(null); return; }
+ const r = iconRef.current?.getBoundingClientRect();
+ if (!r) return;
+ // Height is content-dependent; this is the two-line + link case, and the
+ // clamp below absorbs the error if it wraps to three.
+ const estH = 78;
+ const above = r.top - HINT_GAP - estH;
+ const top = above >= 8 ? above : Math.min(r.bottom + HINT_GAP, window.innerHeight - estH - 8);
+ const left = Math.max(8, Math.min(r.left, window.innerWidth - HINT_W - 8));
+ setHint({ left, top: Math.max(8, top) });
+ };
+
+ // Click-to-open explanation. A hover title would do for a mouse, but this sits
+ // on a disabled control — the one thing people click when nothing happens — so
+ // the answer belongs behind that click.
+ useEffect(() => {
+ if (!hintOpen) return;
+ const onDown = (ev: globalThis.MouseEvent): void => {
+ const t = ev.target as Node;
+ // The popover is portalled out of this subtree, so an inside-click has to
+ // be tested against BOTH the anchor and the floating panel.
+ if (hintRef.current?.contains(t) || panelRef.current?.contains(t)) return;
+ setHint(null);
+ };
+ const onKey = (ev: KeyboardEvent): void => { if (ev.key === 'Escape') setHint(null); };
+ // A dock that scrolls or a window that resizes leaves fixed coords stale, and
+ // a popover stranded away from its icon is worse than one that closed.
+ const onReflow = (): void => setHint(null);
+ document.addEventListener('mousedown', onDown);
+ document.addEventListener('keydown', onKey);
+ window.addEventListener('resize', onReflow);
+ window.addEventListener('scroll', onReflow, true);
+ return () => {
+ document.removeEventListener('mousedown', onDown);
+ document.removeEventListener('keydown', onKey);
+ window.removeEventListener('resize', onReflow);
+ window.removeEventListener('scroll', onReflow, true);
+ };
+ }, [hintOpen]);
+
// Wrap in a (non-disabled) span so the native title tooltip still shows on hover even
// when the inner button is disabled — Chromium suppresses tooltips on a disabled button.
return (
<span
title={title}
className="cth-titlebar-nodrag"
- style={{ display: 'inline-flex', alignItems: 'center', gap: noKey ? 6 : 0 }}
+ // minWidth:0 is what actually stops the overflow: without it this inline-flex
+ // keeps its max-content width and pushes past the card's edge no matter what
+ // the label inside does.
+ style={{ display: 'inline-flex', alignItems: 'center', gap: noKey ? 4 : 0, minWidth: 0 }}
// Stop the click bubbling to a parent card's onClick (selecting the agent).
onClick={(e) => e.stopPropagation()}
>
@@ -145,28 +221,77 @@ export function RealtimeMichaelToggle({ compact = false }: RealtimeMichaelToggle
)}
</span>
</PixelButton>
- {/* Inline, non-blocking caution chip — a discoverable cue for WHY the disabled
- button won't connect (the native tooltip is hover-only). Only when no key is
- set; once a key is added the store signal flips and this disappears. Compact
- form (fullscreen toolbar) keeps it short to avoid crowding the header. */}
+ {/* Missing key is a SETUP STATE, not a failure — so this is a quiet info mark
+ and a way to fix it, never a warning chip. The old lemon chip spelled the
+ whole problem out inline ("needs OpenAI key · Settings") and, being
+ nowrap + flex-shrink:0, pushed itself past the agent card's edge instead
+ of wrapping. The explanation now lives in the hover tooltip; what stays on
+ screen is one 16px glyph plus a two-word action.
+
+ In compact mode (fullscreen toolbar) the icon alone carries it — the
+ tooltip still explains, and Settings is a click away in the same header. */}
{noKey && (
- <span
- aria-label="Talk needs an OpenAI key"
- style={{
- display: 'inline-flex',
- alignItems: 'center',
- whiteSpace: 'nowrap',
- fontFamily: 'var(--cth-font-ui)',
- fontSize: 10,
- lineHeight: '14px',
- padding: '1px 5px 0',
- background: 'var(--cth-lemon)',
- color: 'var(--cth-ink-900)',
- boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)',
- flexShrink: 0
- }}
- >
- {compact ? 'needs OpenAI key' : 'needs OpenAI key · Settings'}
+ <span ref={hintRef} style={{ display: 'inline-flex', flexShrink: 0 }}>
+ <button
+ ref={iconRef}
+ type="button"
+ aria-label="Why is Talk disabled?"
+ aria-expanded={hintOpen}
+ onClick={toggleHint}
+ style={{
+ border: 'none', background: 'none', padding: 0, cursor: 'pointer',
+ display: 'inline-flex', alignItems: 'center',
+ opacity: hintOpen ? 1 : 0.75
+ }}
+ >
+ <Icon name="info" />
+ </button>
+
+ {hint && createPortal(
+ <div
+ ref={panelRef}
+ role="dialog"
+ onClick={(e) => e.stopPropagation()}
+ style={{
+ position: 'fixed',
+ left: hint.left,
+ top: hint.top,
+ zIndex: 460,
+ width: HINT_W,
+ padding: '8px 10px',
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 5,
+ boxSizing: 'border-box',
+ background: 'var(--cth-paper-100)',
+ // Matches the note editor's portalled popover: hairline + a hard
+ // drop shadow, so it reads as floating above the dock rather than
+ // as part of whichever card it happens to cover.
+ boxShadow: 'inset 0 0 0 1.5px var(--cth-ink-500), 4px 4px 0 rgba(26,19,32,0.25)',
+ fontFamily: 'var(--cth-font-ui)',
+ fontSize: 11,
+ lineHeight: '15px',
+ color: 'var(--cth-ink-900)',
+ textAlign: 'left',
+ whiteSpace: 'normal'
+ }}
+ >
+ <span>An <strong>OpenAI API key</strong> is needed to use this feature.</span>
+ <button
+ type="button"
+ onClick={openKeySettings}
+ style={{
+ border: 'none', background: 'none', padding: 0, cursor: 'pointer',
+ alignSelf: 'flex-start',
+ fontFamily: 'var(--cth-font-ui)', fontSize: 11, lineHeight: '15px',
+ color: 'var(--cth-ink-900)', textDecoration: 'underline'
+ }}
+ >
+ set it up now
+ </button>
+ </div>,
+ document.body
+ )}
</span>
)}
</span>
diff --git a/src/renderer/src/components/SettingsModal.tsx b/src/renderer/src/components/SettingsModal.tsx
index 48f7ef89..c2cd90e7 100644
--- a/src/renderer/src/components/SettingsModal.tsx
+++ b/src/renderer/src/components/SettingsModal.tsx
@@ -17,12 +17,17 @@ import { OfficeThemePicker } from './OfficeThemePicker';
import { McpDefaultsSettings } from './McpDefaultsSettings';
import { IntegrationsRegistry } from './IntegrationsRegistry';
import { AiEnginesSettings } from './AiEnginesSettings';
+import { REALTIME_MODEL } from '@shared/realtimePricing';
import { RealtimeDevicePicker } from '@/realtime/DevicePicker';
import { CostHud } from '@/realtime/CostHud';
export interface SettingsModalProps {
config: HarnessConfig;
onClose: () => void;
+ /** Open straight to a section instead of General. Used by deep links from
+ * elsewhere in the UI — "set it now" beside a disabled Talk button lands on
+ * the tab that actually holds the field, rather than making the user hunt. */
+ initialSection?: Section;
}
/**
@@ -148,7 +153,7 @@ function clearLocalState(): void {
// v0.3.4 redesign: six tabs, one topic each. 'AI Engines' folded into
// Agents & Models; MCP + Slack + webhook + REST live together in Connections;
// voice gets its own tab; Danger Zone became a red row at the bottom of General.
-type Section = 'General' | 'Agents & Models' | 'Autonomy & Budgets' | 'Connections' | 'Voice' | 'Memory & Knowledge';
+export type Section = 'General' | 'Agents & Models' | 'Autonomy & Budgets' | 'Connections' | 'Voice' | 'Memory & Knowledge';
const NAV_SECTIONS: Section[] = ['General', 'Agents & Models', 'Autonomy & Budgets', 'Connections', 'Voice', 'Memory & Knowledge'];
/** One labelled on/off row. The surrounding settings pane repeats this
@@ -183,10 +188,10 @@ function SettingRow({ title, blurb, on, onClick, disabled }: {
);
}
-export function SettingsModal({ config, onClose }: SettingsModalProps) {
+export function SettingsModal({ config, onClose, initialSection }: SettingsModalProps) {
const [confirming, setConfirming] = useState(false);
const [busy, setBusy] = useState(false);
- const [activeSection, setActiveSection] = useState<Section>('General');
+ const [activeSection, setActiveSection] = useState<Section>(initialSection ?? 'General');
// Change-home flow: null until the user picks a new folder, then the sub-modal
// confirms move-vs-fresh. Pre-selects 'move' (recommended - keeps the data).
@@ -427,6 +432,26 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {
// Talk (Realtime Michael) is gated on the OpenAI key — read the live presence
// boolean so the Realtime Michael section can show its enabled/disabled status.
const hasOpenAiKey = useStore((s) => s.hasOpenAiKey);
+ // Voice-tab entry for the SAME broker slot Agents & Models writes (apikey:openai).
+ // Mirroring presence into the store on save is what makes the Talk button light up
+ // immediately instead of on next launch.
+ const setHasOpenAiKey = useStore((s) => s.setHasOpenAiKey);
+ const [openAiVoiceKey, setOpenAiVoiceKey] = useState('');
+ const [openAiVoiceNote, setOpenAiVoiceNote] = useState('');
+ const saveOpenAiVoiceKey = async (): Promise<void> => {
+ const key = openAiVoiceKey.trim();
+ if (!key) return;
+ try {
+ const r = await window.cth.providerKeySet({ backend: 'openai', key });
+ if (r.ok) {
+ setOpenAiVoiceKey('');
+ setHasOpenAiKey(true);
+ setOpenAiVoiceNote('Key saved — Talk is ready.');
+ } else setOpenAiVoiceNote(r.error ?? 'Could not save the key.');
+ } catch (e) {
+ setOpenAiVoiceNote(e instanceof Error ? e.message : String(e));
+ }
+ };
// v0.3.4 fix: the config default is ON ('now on by default', 0.2.7) — seeding
// with `?? false` displayed OFF while the feature was actually running.
const [freeflowEnabled, setFreeflowEnabled] = useState(config.freeflowEnabled !== false);
@@ -1889,12 +1914,15 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {
</span>
</div>
- {/* OpenAI Realtime key — its own documented requirement. Talk mints an
- ephemeral token from your OpenAI key (the same OpenAI provider key
- under AI Engines), distinct from your Anthropic key. The status line
- reads the live presence boolean (key value never leaves main). */}
+ {/* OpenAI Realtime key — settable HERE, not just described here.
+ This is where someone looking for voice actually lands (the Talk
+ button deep-links to it), so sending them to another tab to type
+ the key was a dead end dressed up as documentation. Same broker
+ slot as Agents & Models (apikey:openai) — one key, two doorways,
+ and saving in either flips the same gate. The value never leaves
+ main; only the presence boolean comes back. */}
<div style={{
- display: 'flex', flexDirection: 'column', gap: 6,
+ display: 'flex', flexDirection: 'column', gap: 8,
padding: 10,
background: 'var(--cth-paper-100)',
boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)'
@@ -1903,28 +1931,51 @@ export function SettingsModal({ config, onClose }: SettingsModalProps) {
fontFamily: 'var(--cth-font-display)', fontSize: 8, lineHeight: '12px',
color: 'var(--cth-ink-500)', textTransform: 'uppercase'
}}>
- OpenAI Realtime key
+ OpenAI API key · voice
</span>
<span style={{ fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-700)' }}>
- Talk uses OpenAI&rsquo;s Realtime voice API, so it needs your <strong>OpenAI API key</strong> —
- the same key you set under <strong>AI Engines → OpenAI</strong>. It is a separate provider
- key from your Anthropic key. Main mints a short-lived token from it for each session; the
- key itself never leaves your machine. <strong>Without an OpenAI key the Talk button stays
- disabled.</strong>
+ Talking to Michael runs on OpenAI&rsquo;s Realtime API — speech in, speech out, over a
+ live connection to <strong style={{ fontFamily: 'var(--cth-font-mono)' }}>{REALTIME_MODEL}</strong>.
+ That is a different service from the Claude subscription your agents run on, so it needs
+ its own <strong>OpenAI API key</strong>.
</span>
+ <span style={{ fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-700)' }}>
+ Paste it once below. It is encrypted on this machine and never shown again — each voice
+ session mints its own short-lived token from it, and the key itself never leaves your
+ computer. It is the same OpenAI key listed under <strong>Agents &amp; Models</strong>;
+ setting it in either place is enough.
+ </span>
+ <div style={{ display: 'flex', gap: 6, alignItems: 'center' }}>
+ <input
+ type="password"
+ value={openAiVoiceKey}
+ onChange={(e) => setOpenAiVoiceKey(e.target.value)}
+ onKeyDown={(e) => { if (e.key === 'Enter') void saveOpenAiVoiceKey(); }}
+ placeholder={hasOpenAiKey ? 'key saved — paste a new one to replace it' : 'sk-…'}
+ style={{ ...slackInputStyle, flex: 1, fontFamily: 'var(--cth-font-mono)' }}
+ />
+ <PixelButton
+ variant="secondary"
+ size="sm"
+ onClick={() => void saveOpenAiVoiceKey()}
+ disabled={!openAiVoiceKey.trim()}
+ >
+ Save
+ </PixelButton>
+ </div>
<span style={{
display: 'inline-flex', alignItems: 'center', gap: 6,
fontSize: 12, lineHeight: '16px',
- color: hasOpenAiKey ? 'var(--cth-ink-900)' : '#6E1423'
+ color: hasOpenAiKey ? 'var(--cth-ink-900)' : 'var(--cth-ink-500)'
}}>
<span aria-hidden style={{
width: 8, height: 8, flexShrink: 0,
- background: hasOpenAiKey ? 'var(--cth-mint)' : 'var(--cth-lemon)',
+ background: hasOpenAiKey ? 'var(--cth-mint)' : 'var(--cth-ink-300)',
boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)'
}} />
- {hasOpenAiKey
- ? 'OpenAI key detected — Talk is enabled.'
- : 'No OpenAI key set — Talk is disabled. Add it under AI Engines → OpenAI.'}
+ {openAiVoiceNote || (hasOpenAiKey
+ ? 'Key saved — Talk is ready. Start it from Michael’s card.'
+ : 'No key yet — Talk stays disabled until one is saved.')}
</span>
</div>
diff --git a/src/shared/realtimePricing.ts b/src/shared/realtimePricing.ts
index a07a31d1..12d8347c 100644
--- a/src/shared/realtimePricing.ts
+++ b/src/shared/realtimePricing.ts
@@ -14,6 +14,15 @@
* raw token counts are surfaced alongside the dollar figure so it stays auditable.
*/
+/**
+ * The realtime voice model Talk connects to. Lives HERE, in shared, because it is
+ * named in user-facing Settings copy as well as used by the main-process mint —
+ * a model string duplicated across a process boundary is one that eventually
+ * disagrees with itself, and the half users read is the half nobody notices is
+ * stale. `src/main/realtime.ts` re-exports this as its own REALTIME_MODEL.
+ */
+export const REALTIME_MODEL = 'gpt-realtime-2.1';
+
/** USD per 1,000,000 audio tokens (gpt-realtime-2). */
export const REALTIME_AUDIO_INPUT_PER_MTOK = 32;
export const REALTIME_AUDIO_OUTPUT_PER_MTOK = 64;