有朋友最近问过我一个很有意思的场景能不能在直播间里直接用语音指挥 AI 写代码让观众看到“说话就能生成软件”的过程其实这就是把 OpenAI Codex 和语音智能体组合起来做一次技术演示。Codex 本身是 OpenAI 推出的编程智能体不只是补全代码的插件而是能接管终端、读写文件、执行命令的自动化编码工具。配上语音识别和语音合成就能实现“用嘴写代码”的直播效果。这篇文章会完整拆解这套演示方案从 Codex 是什么、环境怎么搭到语音智能体怎么设计、代码怎么写、常见报错怎么排查最后给出适合直播场景的工程建议。内容偏向实操新手可以跟着一步步搭有经验的开发者可以直接跳到代码和排错部分。1. 背景与核心概念在搭建演示之前先把几个关键概念梳理清楚避免后面混淆。1.1 Codex 是什么Codex 是 OpenAI 推出的 AI 编程智能体和传统的代码补全工具有本质区别。传统工具比如早期的 Copilot 补全主要根据光标上下文给建议而 Codex 更像一个能独立执行任务的“AI 程序员”它能读取项目目录结构。它能创建、修改、删除代码文件。它能执行终端命令比如安装依赖、运行测试。它能根据你的自然语言描述直接完成一套功能闭环。2025 年之后OpenAI 已经把 Codex 的 Harness控制台运行框架开源到了 GitHub地址是github.com/openai/codex。这意味着你可以查看它如何在沙箱中执行任务也可以基于它做二次开发。很多第三方的 Codex 桌面版、IDE 插件本质都是把 Codex 引擎封装成更友好的界面。1.2 语音智能体是什么语音智能体是能“听懂人话并做出动作”的 AI 系统典型链路包含三部分ASR自动语音识别把麦克风采集的语音转成文字例如 Whisper API。LLM Agent大模型智能体理解文字指令拆解步骤调用工具。Codex 在这里扮演的就是“行动大脑”。TTS语音合成把结果转成语音播报例如 OpenAI TTS、Edge TTS、CosyVoice。这套架构本身不复杂难点在于把 Codex 的输出稳定地汇入语音链路并且让演示过程不“翻车”。1.3 为什么要在直播中演示这个组合代码生成类直播最大的问题是“过程不可见”。如果只在屏幕前敲一段提示词观众看 30 秒就失去兴趣。而语音智能体天然具备表演张力声音指令能让观众直观感觉到“AI 在听”。Codex 执行命令、创建文件的过程相当于把 AI 的思考过程可视化。观众能随时提出新需求增加互动感。所以这套系统的核心目标不是做出一个完美的生产级产品而是让“语音 → 代码 → 运行结果”这条链路在直播中延迟可接受、失败率低、演示效果好。2. 环境准备与版本说明在动手写代码之前先准备好基础环境。下面以 Windows 11 加 WSL2 Ubuntu 22.04 为例因为 Codex CLI 在 Linux 环境下运行最稳WSL2 能兼顾开发和直播推流的便利性。2.1 基础环境清单组件推荐版本/工具说明操作系统Windows 11 WSL2 Ubuntu 22.04生产建议直接用 Linux 服务器Node.js 18Codex CLI 基于 Node.js 构建npm 9安装 Codex 的包管理工具Codex CLI最新稳定版通过 npm 全局安装Python 3.10用于语音处理和调用脚本麦克风普通 USB 麦克风直播场景建议用降噪麦克风FFmpeg最新版处理音频流可选版本说明Codex 迭代很快安装时建议以官方或npm上的最新稳定版为准。技术栈不适合写死版本本文重点是配置思路和代码逻辑。2.2 安装 Codex CLI在 WSL2 终端里执行npm install -g openai/codex安装完成后验证codex --version如果显示版本号说明安装成功。接着配置认证codex login这里会引导你登录 OpenAI 账号并生成 API Key。登录成功后在用户目录下会出现~/.codex/config.toml ~/.codex/auth.json其中auth.json保存了认证凭据config.toml是 Codex 的主配置。2.3 配置 API Key 的两种方式方式一使用环境变量export OPENAI_API_KEY你的API Key这种方式适合临时演示每次打开终端都要重新设置。方式二写入config.tomlmodel gpt-5-codex model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY注意具体模型名要以你账号实际可用的模型为准。如果你使用的是第三方兼容接口则把base_url改成对应服务商地址即可。2.4 准备语音识别与合成环境语音部分使用 Python 来实现。先创建虚拟环境并安装依赖python3 -m venv voice_env source voice_env/bin/activate pip install openai sounddevice numpy scipy这里用sounddevice是为了从麦克风采集音频openai用来调用语音识别和语音合成模型。3. Codex 控制台的核心机制理解 Codex 的工作原理才能更好设计语音智能体。这节拆解 Codex CLI 的核心机制。3.1 Codex 是一个 Agent而不是补全工具Codex 的工作方式如下接收用户的自然语言任务。在沙箱或当前目录中分析文件。规划执行步骤。调用工具读写文件、执行 shell 命令。输出结果等待用户确认或自动继续。这种“规划—执行—观察”的循环和传统代码补全完全不同更接近一个自主 Agent。3.2 Codex Harness 开源意味着什么Codex Harness 开源后开发者可以直接在本地运行git clone https://github.com/openai/codex.git cd codex npm install npm run build开源 Harness 让我们能看到 Codex 的底层执行逻辑比如终端命令如何被解析和过滤。文件编辑如何被应用。沙箱如何隔离危险操作。善用这些源码对于排查“为什么 Codex 不执行某条命令”非常有帮助。3.3 Codex 与第三方 API 的兼容问题Codex 支持 OpenAI API 协议。这意味着任何实现相同协议的第三方服务理论上都能作为 Codex 的模型提供商比如接入 DeepSeek 或其他兼容接口。配置方式是在config.toml中新增一个 provider[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY但要注意Codex 的部分特性比如某些模型专有的推理字段依赖特定接口实现切换第三方 API 后很可能出现兼容性问题。后面“常见问题”一节会专门讲。4. 完整实战语音驱动的 Codex 演示系统现在进入核心部分。我们要构建一个语音智能体演示系统架构是麦克风 → ASR语音识别 → 意图理解 → 调用Codex CLI → 执行结果 → TTS语音播报 → 扬声器把任务拆成三步语音采集与识别。调用 Codex 执行编程任务。将结果转为语音播报。4.1 创建项目结构voice-codex-demo/ ├── main.py ├── asr.py ├── tts.py ├── codex_runner.py ├── requirements.txt └── workspace/ └── demo_project/其中main.py主控逻辑。asr.py语音识别封装。tts.py语音合成封装。codex_runner.py调用 Codex CLI 的封装。workspace/Codex 实际操作的工程目录。4.2 编写语音识别模块先写asr.py负责把麦克风语音转成文字。这里使用 OpenAI Whisper 接口它能把本地录制的音频文件转成文本。# 文件asr.py import sounddevice as sd import numpy as np import tempfile import scipy.io.wavfile as wavfile from openai import OpenAI SAMPLE_RATE 16000 DURATION 5 # 每次录音时长单位秒 client OpenAI() def record_audio(duration: int DURATION) - str: 录制麦克风音频返回临时 WAV 文件路径 print(f请开始说话共 {duration} 秒...) audio sd.rec(int(duration * SAMPLE_RATE), samplerateSAMPLE_RATE, channels1, dtypeint16) sd.wait() temp_file tempfile.NamedTemporaryFile(suffix.wav, deleteFalse) wavfile.write(temp_file.name, SAMPLE_RATE, audio) print(f录音完成{temp_file.name}) return temp_file.name def speech_to_text(audio_path: str) - str: 调用 Whisper 识别音频文字 with open(audio_path, rb) as f: transcript client.audio.transcriptions.create( modelwhisper-1, filef, languagezh ) return transcript.text解释几个关键点sounddevice直接采集麦克风音频采样率设为 16000 是语音识别的常见配置。录制时长先固定为 5 秒属于演示简化方案。真实场景建议使用 VAD语音活动检测检测到静音就自动停止录音。Whisper 的languagezh是为了提高中文识别准确率如果观众说英文可以去掉这个参数。4.3 编写调用 Codex 的模块这里有两种方式调用 Codex方式一直接用subprocess调用codex命令。方式二Codex 官方提供 Rust 核心库但 Python 调用更简单的方式是命令行。我们使用方式一稳定且易理解。# 文件codex_runner.py import subprocess import os def run_codex_task(task_description: str, workspace: str) - str: 在指定工作区中执行 Codex 任务 command [ codex, exec, task_description, --skip-git-repo-check, --sandbox, read-only, ] env os.environ.copy() result subprocess.run( command, capture_outputTrue, textTrue, envenv, cwdworkspace, timeout120, ) output result.stdout if result.stderr: output \n[STDERR]\n result.stderr return output这里说明几个参数codex exec非交互式执行任务适合脚本调用。--skip-git-repo-check跳过 Git 仓库检查允许在非 Git 目录执行。--sandbox read-only沙箱模式设为只读不会真正修改文件适合演示安全性更高的场景。如果希望 Codex 真的写入文件可以改用--sandbox workspace-write。timeout120防止任务卡死。但是只读沙箱意味着 Codex 不能真正创建文件在演示中可能显得“不够炫”。如果想让观众看到真实文件生成可以用command [ codex, exec, task_description, --skip-git-repo-check, --sandbox, workspace-write, ]这样 Codex 就能在工作区内创建和修改文件。演示时要提前把工作区备份好。4.4 编写语音合成模块然后写tts.py把 Codex 的执行结果转成语音播报。这里使用 OpenAI 的 TTS 模型。# 文件tts.py from openai import OpenAI import tempfile import subprocess client OpenAI() def text_to_speech(text: str, voice: str alloy) - str: 将文本转为语音并播放 if not text.strip(): text 任务已完成 # 控制播报文本长度避免念完全部日志 if len(text) 120: # 提取关键信息优先播报最后几行 lines [line for line in text.splitlines() if line.strip()] text lines[-1][:120] if lines else 执行完成 audio_path tempfile.mktemp(suffix.mp3) response client.audio.speech.create( modeltts-1, voicevoice, inputtext ) response.stream_to_file(audio_path) # 在 Linux/WSL 下用 ffplay 或 mpv 播放 subprocess.run([ffplay, -nodisp, -autoexit, audio_path], capture_outputTrue) return audio_path这里需要注意直播场景不能让 TTS 念完整日志那会非常冗长。所以只取末尾一行核心信息。ffplay是 FFmpeg 自带的播放器如果系统没有安装可以改用mpv或者aplay。4.5 编写主控逻辑主控逻辑main.py把这些模块串起来# 文件main.py import os from asr import record_audio, speech_to_text from tts import text_to_speech from codex_runner import run_codex_task WORKSPACE os.path.join(os.path.dirname(__file__), workspace, demo_project) def main(): print(语音 Codex 演示系统已启动) print(请说出你要让 AI 完成的任务例如创建一个计算器程序) while True: try: # 1. 录音 audio_file record_audio() # 2. 语音识别 text speech_to_text(audio_file) print(f识别结果{text}) # 3. 检测退出 if 退出 in text or 结束 in text: text_to_speech(演示结束感谢观看) break # 4. 调用 Codex print(正在调用 Codex请稍候...) result run_codex_task(text, WORKSPACE) print(result[-500:]) # 5. 语音播报 text_to_speech(任务已完成) except KeyboardInterrupt: print(\n手动终止) break except Exception as e: print(f发生错误{e}) text_to_speech(抱歉执行过程出现错误) if __name__ __main__: main()这里我选择只播报“任务已完成”而不是播报日志内容是为了让直播流程更干净。如果你想播报更详细的结果可以把text_to_speech(任务已完成)替换成实际的日志摘要。4.6 运行与验证先运行一次非语音的 Codex 命令确认基础链路可用cd voice-codex-demo python -c from codex_runner import run_codex_task; print(run_codex_task(创建一个 hello.py 文件, workspace/demo_project))确认 Codex 能正常执行后再启动语音主程序python main.py预期流程请说出你要让 AI 完成的任务例如创建一个计算器程序 请开始说话共 5 秒... 录音完成/tmp/tmp123.wav 识别结果创建一个计算器程序 正在调用 Codex请稍候... 任务已完成如果录音识别正常、Codex 执行正常、语音播报正常整套演示系统就通了。5. 常见问题与排查思路这套系统在直播中最大的风险是“链路长环节多”任何一环出问题都会导致冷场。下面整理高频问题。5.1 语音识别没有结果或识别错误问题现象常见原因解决思路识别结果为空麦克风权限未开启检查系统麦克风权限设置识别文字乱码采样率不正确确保使用 16kHz 采样率环境噪音大无降噪直播使用降噪耳机或外接麦克风中文识别不准未指定语言Whisper 请求加languagezh最有效的排查方法是先录音到本地人工听一遍音频是否清晰再调用识别接口逐层定位问题。5.2 Codex 执行报错model not supported在直播中如果突然看到这样的报错the gpt-5.6-sol model is not supported when using codex with a chatgpt acc原因是当前账号类型或模型名与 Codex 不匹配。解决步骤检查config.toml中的model参数。登录 OpenAI 账号确认当前账号可用的模型列表。把模型名改成账号实际支持的版本。如果用的是 ChatGPT 账号而非 API 账号注意某些模型只能通过特定方式访问。5.3 cc switch local proxy failed这是使用第三方工具切换代理时常见的错误cc switch local proxy failed while handling codex endpoint /responses. provider: deepseek; model: deepseek-v4-flash; upstream_status: http 400; cause: the reasoning_content in the thinking mode must be passed back to the api.这个报错信息很典型说明你配置了第三方模型提供商如 DeepSeek并且开启了思考模式。DeepSeek 的 API 要求如果请求中带出了reasoning_content字段那么后续请求必须把它原样传回否则返回 400。解决思路关闭 Codex 中的 thinking 模式或关闭带推理内容的请求。修改第三方接口配置确保reasoning_content被正确传递。更换为官方 OpenAI 模型兼容性最好。对于直播演示我强烈建议优先使用官方模型不要为了省一点费用在演示中切换到第三方接口因为兼容性问题可能随时打断流程。5.4 Codex 在沙箱中无法写入文件如果你使用--sandbox read-onlyCodex 不会真正修改文件。这会导致观众看到“AI 说做完了但文件没有任何变化”。解决方案演示现场改成--sandbox workspace-write。每次演示前备份workspace目录。在config.toml中设置白名单机制允许 Codex 访问指定目录。5.5 TTS 播报卡顿或无声音问题现象常见原因解决思路播放器报错FFmpeg/ffplay 未安装安装 FFmpeg音频延迟大网络请求慢提前把 TTS 音频生成好或使用本地 TTS声音断断续续音频驱动冲突使用独立声卡或用 HDMI 音频输出直播场景建议使用本地 TTS 引擎比如 Edge TTS 的本地封装或者提前预热网络连接避免临场延迟。5.6 排查清单直播前按这个清单检查[ ]codex --version能正常执行。[ ]codex exec 输出hello能返回结果。[ ] 麦克风能录音ffplay播放录音有声音。[ ] Whisper 接口能识别中文。[ ] TTS 接口能正常播报。[ ] workspace 目录已备份。[ ] 网络连接稳定。6. 最佳实践与工程建议6.1 语音交互设计限定任务范围直播中最怕观众随便说一个太复杂的任务Codex 执行几分钟观众流失。解决办法是做一个“意图过滤层”# 在调用 Codex 之前对文本做简单校验 ALLOWED_KEYWORDS [创建, 写一个, 开发, 实现, 生成, 修复, 添加] def is_allowed_task(text: str) - bool: return any(keyword in text for keyword in ALLOWED_KEYWORDS)如果任务不在允许范围内就直接语音回复“这个任务太复杂了请换一个简单的编程任务”然后重新录音。6.2 执行目录隔离每次演示都要在干净的目录中执行避免上次运行留下的文件干扰判断。可以在主程序中加入import shutil def reset_workspace(workspace: str): if os.path.exists(workspace): shutil.rmtree(workspace) os.makedirs(workspace, exist_okTrue)每次演示开始前调用reset_workspace确保 Codex 从零开始。6.3 日志缓冲与可视化直播时观众看不到终端里的日志最好把 Codex 的输出实时投射到屏幕上。可以在主程序中把结果也写入一个 HTML 文件用 OBS 读取该文件作为字幕层def write_log_html(log_text: str, html_path: str): html fhtmlbody stylebackground:black;color:white pre{log_text[-1000:]}/pre /body/html with open(html_path, w) as f: f.write(html)OBS 添加“浏览器源”指向这个本地 HTML 文件就能实现日志实时滚动显示。6.4 安全边界Codex 会执行终端命令因此安全边界非常重要类别建议沙箱模式演示用workspace-write正式环境用read-only目录隔离只允许 Codex 操作指定 workspace命令过滤审查 Codex 配置禁止危险命令网络控制不让 Codex 访问内网和生产环境密钥管理不把 API Key 写入代码库使用环境变量执行超时设置timeout120防止无限执行6.5 演示节奏控制语音驱动 Codex 的直播演示节奏比代码本身更重要。建议这样安排开场 2 分钟展示语音识别让 Codex 完成一个极小的任务比如输出 Hello World。中间 5 分钟展示完整任务——创建一个计算器程序并运行。结尾 2 分钟展示文件生成结果、代码内容。不要一开始就让 Codex 创建完整项目一旦超时或报错就很难收场。7. 演进方向当前演示系统的链路是“语音指令 → Codex 编程 → 语音播报”仍有一些局限不支持多轮对话观众无法追问“改成加法”并让 Codex 记住上下文。不支持实时打断录音时长固定不支持边说边改。不支持流式输出必须等 Codex 全部执行完才播报。这几个方向都可以继续深入。想进阶的读者可以重点研究多轮对话状态管理在 Codex 之外维护对话历史把历史摘要传给模型。语音活动检测VAD用webrtcvad或 Silero VAD 实现自适应停止录音。流式 TTS用 WebSocket 实时合成语音降低延迟。Codex Harness 二次开发既然 Harness 已经开源可以深入修改它的执行逻辑实现定制化 tool 调用。这些内容如果展开每一块都够一篇独立博客。建议先把本文的链路跑通再按需要选一个方向深入。动手搭一遍比看十篇文章更有价值。如果这篇教程帮你跑通了第一版语音 Codex 演示欢迎在评论区分享你的直播效果和踩坑经历。后面我再根据大家的问题写 Codex 多轮对话和 VAD 中断录音的进阶实现。 语音驱动Codex：搭建“用嘴写代码”的直播演示系统
有朋友最近问过我一个很有意思的场景能不能在直播间里直接用语音指挥 AI 写代码让观众看到“说话就能生成软件”的过程其实这就是把 OpenAI Codex 和语音智能体组合起来做一次技术演示。Codex 本身是 OpenAI 推出的编程智能体不只是补全代码的插件而是能接管终端、读写文件、执行命令的自动化编码工具。配上语音识别和语音合成就能实现“用嘴写代码”的直播效果。这篇文章会完整拆解这套演示方案从 Codex 是什么、环境怎么搭到语音智能体怎么设计、代码怎么写、常见报错怎么排查最后给出适合直播场景的工程建议。内容偏向实操新手可以跟着一步步搭有经验的开发者可以直接跳到代码和排错部分。1. 背景与核心概念在搭建演示之前先把几个关键概念梳理清楚避免后面混淆。1.1 Codex 是什么Codex 是 OpenAI 推出的 AI 编程智能体和传统的代码补全工具有本质区别。传统工具比如早期的 Copilot 补全主要根据光标上下文给建议而 Codex 更像一个能独立执行任务的“AI 程序员”它能读取项目目录结构。它能创建、修改、删除代码文件。它能执行终端命令比如安装依赖、运行测试。它能根据你的自然语言描述直接完成一套功能闭环。2025 年之后OpenAI 已经把 Codex 的 Harness控制台运行框架开源到了 GitHub地址是github.com/openai/codex。这意味着你可以查看它如何在沙箱中执行任务也可以基于它做二次开发。很多第三方的 Codex 桌面版、IDE 插件本质都是把 Codex 引擎封装成更友好的界面。1.2 语音智能体是什么语音智能体是能“听懂人话并做出动作”的 AI 系统典型链路包含三部分ASR自动语音识别把麦克风采集的语音转成文字例如 Whisper API。LLM Agent大模型智能体理解文字指令拆解步骤调用工具。Codex 在这里扮演的就是“行动大脑”。TTS语音合成把结果转成语音播报例如 OpenAI TTS、Edge TTS、CosyVoice。这套架构本身不复杂难点在于把 Codex 的输出稳定地汇入语音链路并且让演示过程不“翻车”。1.3 为什么要在直播中演示这个组合代码生成类直播最大的问题是“过程不可见”。如果只在屏幕前敲一段提示词观众看 30 秒就失去兴趣。而语音智能体天然具备表演张力声音指令能让观众直观感觉到“AI 在听”。Codex 执行命令、创建文件的过程相当于把 AI 的思考过程可视化。观众能随时提出新需求增加互动感。所以这套系统的核心目标不是做出一个完美的生产级产品而是让“语音 → 代码 → 运行结果”这条链路在直播中延迟可接受、失败率低、演示效果好。2. 环境准备与版本说明在动手写代码之前先准备好基础环境。下面以 Windows 11 加 WSL2 Ubuntu 22.04 为例因为 Codex CLI 在 Linux 环境下运行最稳WSL2 能兼顾开发和直播推流的便利性。2.1 基础环境清单组件推荐版本/工具说明操作系统Windows 11 WSL2 Ubuntu 22.04生产建议直接用 Linux 服务器Node.js 18Codex CLI 基于 Node.js 构建npm 9安装 Codex 的包管理工具Codex CLI最新稳定版通过 npm 全局安装Python 3.10用于语音处理和调用脚本麦克风普通 USB 麦克风直播场景建议用降噪麦克风FFmpeg最新版处理音频流可选版本说明Codex 迭代很快安装时建议以官方或npm上的最新稳定版为准。技术栈不适合写死版本本文重点是配置思路和代码逻辑。2.2 安装 Codex CLI在 WSL2 终端里执行npm install -g openai/codex安装完成后验证codex --version如果显示版本号说明安装成功。接着配置认证codex login这里会引导你登录 OpenAI 账号并生成 API Key。登录成功后在用户目录下会出现~/.codex/config.toml ~/.codex/auth.json其中auth.json保存了认证凭据config.toml是 Codex 的主配置。2.3 配置 API Key 的两种方式方式一使用环境变量export OPENAI_API_KEY你的API Key这种方式适合临时演示每次打开终端都要重新设置。方式二写入config.tomlmodel gpt-5-codex model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY注意具体模型名要以你账号实际可用的模型为准。如果你使用的是第三方兼容接口则把base_url改成对应服务商地址即可。2.4 准备语音识别与合成环境语音部分使用 Python 来实现。先创建虚拟环境并安装依赖python3 -m venv voice_env source voice_env/bin/activate pip install openai sounddevice numpy scipy这里用sounddevice是为了从麦克风采集音频openai用来调用语音识别和语音合成模型。3. Codex 控制台的核心机制理解 Codex 的工作原理才能更好设计语音智能体。这节拆解 Codex CLI 的核心机制。3.1 Codex 是一个 Agent而不是补全工具Codex 的工作方式如下接收用户的自然语言任务。在沙箱或当前目录中分析文件。规划执行步骤。调用工具读写文件、执行 shell 命令。输出结果等待用户确认或自动继续。这种“规划—执行—观察”的循环和传统代码补全完全不同更接近一个自主 Agent。3.2 Codex Harness 开源意味着什么Codex Harness 开源后开发者可以直接在本地运行git clone https://github.com/openai/codex.git cd codex npm install npm run build开源 Harness 让我们能看到 Codex 的底层执行逻辑比如终端命令如何被解析和过滤。文件编辑如何被应用。沙箱如何隔离危险操作。善用这些源码对于排查“为什么 Codex 不执行某条命令”非常有帮助。3.3 Codex 与第三方 API 的兼容问题Codex 支持 OpenAI API 协议。这意味着任何实现相同协议的第三方服务理论上都能作为 Codex 的模型提供商比如接入 DeepSeek 或其他兼容接口。配置方式是在config.toml中新增一个 provider[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY但要注意Codex 的部分特性比如某些模型专有的推理字段依赖特定接口实现切换第三方 API 后很可能出现兼容性问题。后面“常见问题”一节会专门讲。4. 完整实战语音驱动的 Codex 演示系统现在进入核心部分。我们要构建一个语音智能体演示系统架构是麦克风 → ASR语音识别 → 意图理解 → 调用Codex CLI → 执行结果 → TTS语音播报 → 扬声器把任务拆成三步语音采集与识别。调用 Codex 执行编程任务。将结果转为语音播报。4.1 创建项目结构voice-codex-demo/ ├── main.py ├── asr.py ├── tts.py ├── codex_runner.py ├── requirements.txt └── workspace/ └── demo_project/其中main.py主控逻辑。asr.py语音识别封装。tts.py语音合成封装。codex_runner.py调用 Codex CLI 的封装。workspace/Codex 实际操作的工程目录。4.2 编写语音识别模块先写asr.py负责把麦克风语音转成文字。这里使用 OpenAI Whisper 接口它能把本地录制的音频文件转成文本。# 文件asr.py import sounddevice as sd import numpy as np import tempfile import scipy.io.wavfile as wavfile from openai import OpenAI SAMPLE_RATE 16000 DURATION 5 # 每次录音时长单位秒 client OpenAI() def record_audio(duration: int DURATION) - str: 录制麦克风音频返回临时 WAV 文件路径 print(f请开始说话共 {duration} 秒...) audio sd.rec(int(duration * SAMPLE_RATE), samplerateSAMPLE_RATE, channels1, dtypeint16) sd.wait() temp_file tempfile.NamedTemporaryFile(suffix.wav, deleteFalse) wavfile.write(temp_file.name, SAMPLE_RATE, audio) print(f录音完成{temp_file.name}) return temp_file.name def speech_to_text(audio_path: str) - str: 调用 Whisper 识别音频文字 with open(audio_path, rb) as f: transcript client.audio.transcriptions.create( modelwhisper-1, filef, languagezh ) return transcript.text解释几个关键点sounddevice直接采集麦克风音频采样率设为 16000 是语音识别的常见配置。录制时长先固定为 5 秒属于演示简化方案。真实场景建议使用 VAD语音活动检测检测到静音就自动停止录音。Whisper 的languagezh是为了提高中文识别准确率如果观众说英文可以去掉这个参数。4.3 编写调用 Codex 的模块这里有两种方式调用 Codex方式一直接用subprocess调用codex命令。方式二Codex 官方提供 Rust 核心库但 Python 调用更简单的方式是命令行。我们使用方式一稳定且易理解。# 文件codex_runner.py import subprocess import os def run_codex_task(task_description: str, workspace: str) - str: 在指定工作区中执行 Codex 任务 command [ codex, exec, task_description, --skip-git-repo-check, --sandbox, read-only, ] env os.environ.copy() result subprocess.run( command, capture_outputTrue, textTrue, envenv, cwdworkspace, timeout120, ) output result.stdout if result.stderr: output \n[STDERR]\n result.stderr return output这里说明几个参数codex exec非交互式执行任务适合脚本调用。--skip-git-repo-check跳过 Git 仓库检查允许在非 Git 目录执行。--sandbox read-only沙箱模式设为只读不会真正修改文件适合演示安全性更高的场景。如果希望 Codex 真的写入文件可以改用--sandbox workspace-write。timeout120防止任务卡死。但是只读沙箱意味着 Codex 不能真正创建文件在演示中可能显得“不够炫”。如果想让观众看到真实文件生成可以用command [ codex, exec, task_description, --skip-git-repo-check, --sandbox, workspace-write, ]这样 Codex 就能在工作区内创建和修改文件。演示时要提前把工作区备份好。4.4 编写语音合成模块然后写tts.py把 Codex 的执行结果转成语音播报。这里使用 OpenAI 的 TTS 模型。# 文件tts.py from openai import OpenAI import tempfile import subprocess client OpenAI() def text_to_speech(text: str, voice: str alloy) - str: 将文本转为语音并播放 if not text.strip(): text 任务已完成 # 控制播报文本长度避免念完全部日志 if len(text) 120: # 提取关键信息优先播报最后几行 lines [line for line in text.splitlines() if line.strip()] text lines[-1][:120] if lines else 执行完成 audio_path tempfile.mktemp(suffix.mp3) response client.audio.speech.create( modeltts-1, voicevoice, inputtext ) response.stream_to_file(audio_path) # 在 Linux/WSL 下用 ffplay 或 mpv 播放 subprocess.run([ffplay, -nodisp, -autoexit, audio_path], capture_outputTrue) return audio_path这里需要注意直播场景不能让 TTS 念完整日志那会非常冗长。所以只取末尾一行核心信息。ffplay是 FFmpeg 自带的播放器如果系统没有安装可以改用mpv或者aplay。4.5 编写主控逻辑主控逻辑main.py把这些模块串起来# 文件main.py import os from asr import record_audio, speech_to_text from tts import text_to_speech from codex_runner import run_codex_task WORKSPACE os.path.join(os.path.dirname(__file__), workspace, demo_project) def main(): print(语音 Codex 演示系统已启动) print(请说出你要让 AI 完成的任务例如创建一个计算器程序) while True: try: # 1. 录音 audio_file record_audio() # 2. 语音识别 text speech_to_text(audio_file) print(f识别结果{text}) # 3. 检测退出 if 退出 in text or 结束 in text: text_to_speech(演示结束感谢观看) break # 4. 调用 Codex print(正在调用 Codex请稍候...) result run_codex_task(text, WORKSPACE) print(result[-500:]) # 5. 语音播报 text_to_speech(任务已完成) except KeyboardInterrupt: print(\n手动终止) break except Exception as e: print(f发生错误{e}) text_to_speech(抱歉执行过程出现错误) if __name__ __main__: main()这里我选择只播报“任务已完成”而不是播报日志内容是为了让直播流程更干净。如果你想播报更详细的结果可以把text_to_speech(任务已完成)替换成实际的日志摘要。4.6 运行与验证先运行一次非语音的 Codex 命令确认基础链路可用cd voice-codex-demo python -c from codex_runner import run_codex_task; print(run_codex_task(创建一个 hello.py 文件, workspace/demo_project))确认 Codex 能正常执行后再启动语音主程序python main.py预期流程请说出你要让 AI 完成的任务例如创建一个计算器程序 请开始说话共 5 秒... 录音完成/tmp/tmp123.wav 识别结果创建一个计算器程序 正在调用 Codex请稍候... 任务已完成如果录音识别正常、Codex 执行正常、语音播报正常整套演示系统就通了。5. 常见问题与排查思路这套系统在直播中最大的风险是“链路长环节多”任何一环出问题都会导致冷场。下面整理高频问题。5.1 语音识别没有结果或识别错误问题现象常见原因解决思路识别结果为空麦克风权限未开启检查系统麦克风权限设置识别文字乱码采样率不正确确保使用 16kHz 采样率环境噪音大无降噪直播使用降噪耳机或外接麦克风中文识别不准未指定语言Whisper 请求加languagezh最有效的排查方法是先录音到本地人工听一遍音频是否清晰再调用识别接口逐层定位问题。5.2 Codex 执行报错model not supported在直播中如果突然看到这样的报错the gpt-5.6-sol model is not supported when using codex with a chatgpt acc原因是当前账号类型或模型名与 Codex 不匹配。解决步骤检查config.toml中的model参数。登录 OpenAI 账号确认当前账号可用的模型列表。把模型名改成账号实际支持的版本。如果用的是 ChatGPT 账号而非 API 账号注意某些模型只能通过特定方式访问。5.3 cc switch local proxy failed这是使用第三方工具切换代理时常见的错误cc switch local proxy failed while handling codex endpoint /responses. provider: deepseek; model: deepseek-v4-flash; upstream_status: http 400; cause: the reasoning_content in the thinking mode must be passed back to the api.这个报错信息很典型说明你配置了第三方模型提供商如 DeepSeek并且开启了思考模式。DeepSeek 的 API 要求如果请求中带出了reasoning_content字段那么后续请求必须把它原样传回否则返回 400。解决思路关闭 Codex 中的 thinking 模式或关闭带推理内容的请求。修改第三方接口配置确保reasoning_content被正确传递。更换为官方 OpenAI 模型兼容性最好。对于直播演示我强烈建议优先使用官方模型不要为了省一点费用在演示中切换到第三方接口因为兼容性问题可能随时打断流程。5.4 Codex 在沙箱中无法写入文件如果你使用--sandbox read-onlyCodex 不会真正修改文件。这会导致观众看到“AI 说做完了但文件没有任何变化”。解决方案演示现场改成--sandbox workspace-write。每次演示前备份workspace目录。在config.toml中设置白名单机制允许 Codex 访问指定目录。5.5 TTS 播报卡顿或无声音问题现象常见原因解决思路播放器报错FFmpeg/ffplay 未安装安装 FFmpeg音频延迟大网络请求慢提前把 TTS 音频生成好或使用本地 TTS声音断断续续音频驱动冲突使用独立声卡或用 HDMI 音频输出直播场景建议使用本地 TTS 引擎比如 Edge TTS 的本地封装或者提前预热网络连接避免临场延迟。5.6 排查清单直播前按这个清单检查[ ]codex --version能正常执行。[ ]codex exec 输出hello能返回结果。[ ] 麦克风能录音ffplay播放录音有声音。[ ] Whisper 接口能识别中文。[ ] TTS 接口能正常播报。[ ] workspace 目录已备份。[ ] 网络连接稳定。6. 最佳实践与工程建议6.1 语音交互设计限定任务范围直播中最怕观众随便说一个太复杂的任务Codex 执行几分钟观众流失。解决办法是做一个“意图过滤层”# 在调用 Codex 之前对文本做简单校验 ALLOWED_KEYWORDS [创建, 写一个, 开发, 实现, 生成, 修复, 添加] def is_allowed_task(text: str) - bool: return any(keyword in text for keyword in ALLOWED_KEYWORDS)如果任务不在允许范围内就直接语音回复“这个任务太复杂了请换一个简单的编程任务”然后重新录音。6.2 执行目录隔离每次演示都要在干净的目录中执行避免上次运行留下的文件干扰判断。可以在主程序中加入import shutil def reset_workspace(workspace: str): if os.path.exists(workspace): shutil.rmtree(workspace) os.makedirs(workspace, exist_okTrue)每次演示开始前调用reset_workspace确保 Codex 从零开始。6.3 日志缓冲与可视化直播时观众看不到终端里的日志最好把 Codex 的输出实时投射到屏幕上。可以在主程序中把结果也写入一个 HTML 文件用 OBS 读取该文件作为字幕层def write_log_html(log_text: str, html_path: str): html fhtmlbody stylebackground:black;color:white pre{log_text[-1000:]}/pre /body/html with open(html_path, w) as f: f.write(html)OBS 添加“浏览器源”指向这个本地 HTML 文件就能实现日志实时滚动显示。6.4 安全边界Codex 会执行终端命令因此安全边界非常重要类别建议沙箱模式演示用workspace-write正式环境用read-only目录隔离只允许 Codex 操作指定 workspace命令过滤审查 Codex 配置禁止危险命令网络控制不让 Codex 访问内网和生产环境密钥管理不把 API Key 写入代码库使用环境变量执行超时设置timeout120防止无限执行6.5 演示节奏控制语音驱动 Codex 的直播演示节奏比代码本身更重要。建议这样安排开场 2 分钟展示语音识别让 Codex 完成一个极小的任务比如输出 Hello World。中间 5 分钟展示完整任务——创建一个计算器程序并运行。结尾 2 分钟展示文件生成结果、代码内容。不要一开始就让 Codex 创建完整项目一旦超时或报错就很难收场。7. 演进方向当前演示系统的链路是“语音指令 → Codex 编程 → 语音播报”仍有一些局限不支持多轮对话观众无法追问“改成加法”并让 Codex 记住上下文。不支持实时打断录音时长固定不支持边说边改。不支持流式输出必须等 Codex 全部执行完才播报。这几个方向都可以继续深入。想进阶的读者可以重点研究多轮对话状态管理在 Codex 之外维护对话历史把历史摘要传给模型。语音活动检测VAD用webrtcvad或 Silero VAD 实现自适应停止录音。流式 TTS用 WebSocket 实时合成语音降低延迟。Codex Harness 二次开发既然 Harness 已经开源可以深入修改它的执行逻辑实现定制化 tool 调用。这些内容如果展开每一块都够一篇独立博客。建议先把本文的链路跑通再按需要选一个方向深入。动手搭一遍比看十篇文章更有价值。如果这篇教程帮你跑通了第一版语音 Codex 演示欢迎在评论区分享你的直播效果和踩坑经历。后面我再根据大家的问题写 Codex 多轮对话和 VAD 中断录音的进阶实现。