过去一年终端里出现了一批能够真正改代码、执行命令的 AI 编码智能体OpenAI Codex 就是其中代表之一。它能读懂工作目录里的文件提出修改方案执行命令甚至自动完成一次“创建文件—运行脚本—修复报错—输出结果”的循环。可是无论智能体多强人的操作仍被键盘绑住敲提示词要键盘确认 diff 要键盘看报错还要切窗口。Codex 语音免提编程演示要解决的正是这最后一段距离——把“手”从键盘上解放出来用语音描述目标让 Codex 完成改动再用语音汇报结果。这篇文章不只是一个预告而是把语音免提编程背后的完整链路、环境准备、最小实现、演示流程和排错路径拆开讲清楚。读完之后你可以在自己的电脑上复现一套“麦克风—语音转文字—Codex CLI—文件改动—语音反馈”的最小闭环也可以把文章里的表格当成正式演示前的检查清单。文章面向已经能熟练使用终端、想尝试 AI 编程但又不想一直坐在屏幕前敲命令的开发者也适合准备做内部技术分享的人作为脚本参考。1. 先理清 Codex 在“语音免提编程”链路里的角色1.1 Codex 不是聊天框而是能动手改代码的终端智能体很多人在第一次听到 Codex 时会误以为它只是又一个网页聊天界面。实际上 Codex CLI 这类工具的核心差异在于它能读取当前工作目录的文件结构能创建、修改、删除文件能执行 shell 命令能根据运行结果继续迭代。也就是说它不再只负责“生成一段代码给你复制”而是承担了“把需求变成真实文件改动”的完整任务。在终端里运行时常见的使用方式有两种。一种是进入交互式会话一行一行地对话另一种是用codex exec 提示词方式一次性执行一个任务执行结束后把控制权交还给终端。语音免提编程演示用的正是后者因为它是非交互式的适合被另一个程序调用。codex exec 在当前目录创建一个 hello.py文件内容打印 Hello Codex然后运行它这条命令已经包含了“创建文件”和“运行验证”两个动作。对于语音场景来说很关键人只需要说“创建一个打印 Hello Codex 的 Python 文件并运行”其余步骤由 Codex 自己完成。免提编程的基础就是这类“一句话即可启动一个完整工作流”的能力。需要说明的是不同版本的 Codex CLI参数名和默认行为会有差异。文章里涉及的exec、--sandbox、--approval-mode等参数都用于说明设计思路实际落地前一定要先执行codex --help确认当前版本支持哪些选项。1.2 免提编程的完整链路声音如何变成文件改动语音免提编程并不是把声音直接丢给 Codex而是经过一条明确的数据链路麦克风采集声音得到音频数据。语音转文字模块把音频变成文本。程序把文本包装成适合 Codex 执行的提示词并附上安全约束。Codex CLI 在工作目录内执行任务修改文件或运行命令。程序读取 Codex 的返回结果用语音合成把结论播报给用户。链路里的每一步都可能失败。麦克风没声音、识别出乱码、提示词太模糊、Codex 改错目录、TTS 不发声任何一个环节断掉演示都会失败。这也是为什么演示前必须把每一步拆开验证而不是只验证“整条链路能跑通一次”。从工程角度看这套链路本质上是一个“管道程序”上游输出是下游的输入。把每一段的输入输出格式固定下来调试会容易很多。例如语音转文字的输出永远是纯文本Codex 的输入永远是字符串提示词这样每一段都可以单独测试。1.3 演示预告要验证的能力边界语音免提编程演示的目标是验证三件事一是语音能否稳定转成可执行的开发意图二是 Codex 能否在免审批模式下安全地完成文件改动三是语音反馈能否让用户不切窗口就知道结果。但演示不等于生产。预告演示会刻意选择可控场景在一个临时目录里创建脚本、修改一个函数并运行测试、让 Codex 汇报改动文件清单。这些场景不需要访问敏感系统不涉及生产数据库也不依赖云端正式发布。边界之外的事情比如无人工审查的自动部署、大规模重构、高风险删除操作都不应该出现在演示范围里。明确边界既是安全需要也是演示可控的前提。2. 搭建 Codex 基础环境先让命令行智能体能单独跑通2.1 环境要求和版本检查语音链路再复杂底层还是依赖 Codex CLI 本身能正常工作。所以第一步不是装语音库而是先把 Codex 在终端里跑通。下面是一份常见环境要求具体版本以官方文档为准。项目常见要求说明操作系统Windows 10/11、macOS、主流 Linux 发行版语音库在不同系统上有差异后面会单独说明Node.js18 或更高版本Codex CLI 通过 npm 安装版本过低会直接失败npm随 Node.js 安装用于全局安装openai/codexGit建议安装并配置好用户信息Codex 在 Git 仓库里能更准确地判断改动终端建议使用支持 Unicode 的现代终端中文输出和错误提示更友好安装前先检查本机状态node -v npm -v git --version如果node命令找不到说明 Node.js 没有安装或者没有加入 PATH。直接安装 Codex 会得到一堆 npm 错误而且很难判断是 Codex 的问题还是环境的问题。先把这三条命令的输出确认好后面的步骤才不会被环境问题反复打断。2.2 安装 Codex CLI 并完成登录认证Codex CLI 最常见的安装方式是通过 npm 全局安装npm install -g openai/codex安装完成后确认版本codex --version如果输出一个版本号说明安装成功。如果报“命令找不到”需要检查 npm 全局 bin 目录是否在 PATH 里。Windows 上常见的是把%APPDATA%\npm加进 PATHmacOS 和 Linux 上则要看 npm 的 prefix 配置。登录认证有两种常见方式。一种是执行codex login通过浏览器完成 ChatGPT 账号授权另一种是配置 API Key 环境变量。具体方式随官方文档变化演示前应该提前确认好不要在演示现场才第一次登录。codex login登录成功后再跑一次最小命令验证认证是否真正生效。不要只看登录界面要确认 API 请求能返回结果。2.3 用最小命令验证“修改文件”闭环语音演示要求 Codex 能真实改动文件所以验证用例不能只是“你好”。建议用一个临时目录做验证避免污染自己的工作项目。mkdir -p ~/codex-voice-demo cd ~/codex-voice-demo codex exec 创建一个 data.txt内容写入 1 2 3再创建一个 sum.py 读取 data.txt 并输出数字之和然后运行它执行结束后检查目录内容ls -la cat sum.py python3 sum.py预期结果是目录里出现两个新文件sum.py能被运行并输出6。这一步验证的是Codex 能理解自然语言、能写文件、能运行命令、能完成一个多步骤任务。如果这个闭环跑不通语音部分做得再漂亮也没有意义。2.4 学习环境与生产环境的分工语音免提编程在演示和学习阶段应该坚持“用完即弃”的临时目录策略。每次演示前新建目录演示结束后整个目录删除避免 Codex 的自动操作碰到真实项目。生产环境则完全不同。真实项目里至少要有这些保障代码先提交到 Git 分支Codex 只能基于当前分支改动改动后用git diff审查不能允许自动推送到远端敏感配置和密钥不能出现在提示词里也不能被 Codex 读取到。演示环境可以为了流畅性牺牲一部分安全生产环境不能。3. 加入语音转文字把麦克风变成输入设备3.1 先选语音方案在线识别、本地模型、系统自带语音转文字是整个链路里最容易出问题的一环也是方案选择最丰富的一环。不同方案的取舍很明显在线识别质量高但依赖网络本地模型隐私性好但安装更重系统自带接口配置最少但能力有限。方案优点缺点适合场景SpeechRecognition Google Web Speech安装简单、识别中文稳定依赖网络服务可能变化快速验证链路openai-whisper / faster-whisper离线可用、识别质量高、支持中文首次要下载模型CPU 上较慢演示质量要求高时Vosk离线、轻量、支持关键词识别中文模型需要单独下载需要唤醒词时系统自带 API零额外依赖平台绑定能力有限临时兜底对于演示预告我建议准备两套方案默认用 SpeechRecognition 的在线识别快速跑通如果现场网络不稳定切到本地 whisper 模型。两套方案的代码入口可以共用只更换识别函数。3.2 安装语音依赖以 Python 为例最小依赖是三个库pip install SpeechRecognition pyttsx3 pyaudio其中pyaudio在 Windows 和 macOS 上通常可以直接安装Linux 上需要先安装 PortAudio 系统库# Ubuntu / Debian sudo apt update sudo apt install portaudio19-dev # macOS brew install portaudio安装完成后验证导入是否正常python -c import speech_recognition, pyttsx3; print(ok)如果import pyaudio失败常见原因是系统缺少 PortAudio或者在虚拟环境里没有重新安装。单独运行这条检查可以避免把“麦克风问题”和“库安装问题”混在一起。3.3 写一个最小转写脚本下面这个脚本演示了录音和识别的最小逻辑。它的职责只有一个录一段声音返回文本。import speech_recognition as sr def listen_once(backend: str google, language: str zh-CN) - str: recognizer sr.Recognizer() mic sr.Microphone() with mic as source: print(请开始说话说完后会自动停止) recognizer.adjust_for_ambient_noise(source, duration0.5) audio recognizer.listen(source, timeout8, phrase_time_limit15) if backend google: return recognizer.recognize_google(audio, languagelanguage) if backend sphinx: return recognizer.recognize_sphinx(audio, languagelanguage) raise ValueError(funknown backend: {backend}) if __name__ __main__: text listen_once() print(识别结果:, text)这里几个参数值得解释。adjust_for_ambient_noise会让识别器用前 0.5 秒的环境噪音校准能量阈值避免把背景声音当成语音timeout8表示等待用户开始说话的最长时间超过就抛出WaitTimeoutErrorphrase_time_limit15表示单次最长识别 15 秒防止一句口误导致录音停不下来。调试时可以先跑这个独立脚本确定“录音—转文字”稳定后再接入 Codex。不要一上来就把语音和 Codex 串在一起否则出问题时无法定位是哪一段出错。3.4 麦克风选择与常见入场问题大多数电脑自带麦克风能用但演示场景里噪音大建议优先使用外置麦克风或带麦克风的耳机。检查麦克风是否被系统识别可以先运行 SpeechRecognition 自带的列设备功能import speech_recognition as sr for index, name in enumerate(sr.Microphone.list_microphone_names()): print(index, name)如果程序默认选中了错误设备可以指定设备索引mic sr.Microphone(device_index1)常见问题是默认设备是虚拟音频设备实际没有拾音能力麦克风权限被系统禁用录音一直是静音说话离麦克风太远识别器听到的全是环境噪音。这些都要在接入 Codex 之前单独验证。4. 把语音结果交给 Codex并处理好审批和反馈4.1 为什么不能直接把音频丢给 Codex 执行Codex CLI 的输入是文本提示词不是音频文件。即使未来某个版本支持音频输入当前稳定的工程做法仍然是在外部完成语音转文字再把文本交给 Codex。这样做有两个好处一是语音转文字的结果可以让用户先确认避免误识别导致错误操作二是文本提示词可以记录到日志里方便事后排查“Codex 为什么做了这个改动”。在免提场景里确认环节尤其重要。识别结果一旦有歧义Codex 可能把“删除 test.py”听成“删除 rest.py”。所以提示词构建时必须要求 Codex 在改动前明确说明意图并且把用户原始语音文本完整拼进提示词让它能判断上下文。4.2 编写 voice_codex.py把三步串起来下面是一个完整的演示脚本骨架。它把“语音识别—提示词构建—调用 Codex—语音反馈”串成一条链路所有环节的输入输出都是纯文本。import argparse import subprocess import sys from pathlib import Path import pyttsx3 import speech_recognition as sr def tts_init(): try: return pyttsx3.init() except Exception as exc: print(f[TTS 初始化失败继续使用文字反馈] {exc}) return None def tts_say(engine, text: str): print(f[语音反馈] {text}) if engine is not None: try: engine.say(text) engine.runAndWait() except Exception as exc: print(f[TTS 播放失败] {exc}) def listen_once(backend: str google, language: str zh-CN) - str: recognizer sr.Recognizer() mic sr.Microphone() with mic as source: recognizer.adjust_for_ambient_noise(source, duration0.5) audio recognizer.listen(source, timeout8, phrase_time_limit20) if backend google: return recognizer.recognize_google(audio, languagelanguage) if backend sphinx: return recognizer.recognize_sphinx(audio, languagelanguage) raise ValueError(funknown backend: {backend}) def build_prompt(raw_command: str) - str: return ( 你是一个运行在终端里的编码智能体。\n 请完成用户语音下达的任务遵守以下约束\n 1. 只修改当前工作目录内的文件\n 2. 删除或覆盖文件前先说明再执行\n 3. 完成后用一句话列出改动的文件清单。\n\n f用户任务{raw_command}\n ) def run_codex(prompt: str, work_dir: Path, extra_args: list[str]) - int: cmd [codex, exec, prompt, *extra_args] print([执行], .join(cmd)) result subprocess.run(cmd, cwdstr(work_dir), textTrue, capture_outputTrue) print(result.stdout) if result.stderr: print(result.stderr, filesys.stderr) return result.returncode def main(): parser argparse.ArgumentParser(descriptionCodex 语音免提编程演示) parser.add_argument(--text, help直接传入文本跳过语音识别) parser.add_argument(--backend, defaultgoogle, choices[google, sphinx]) parser.add_argument(--workdir, default., helpCodex 工作目录) parser.add_argument(--approval-mode, defaulton-request, help审批策略语义以 codex --help 为准) parser.add_argument(--sandbox, defaultworkspace-write, help沙箱级别read-only / workspace-write / danger-full-access) args parser.parse_args() engine tts_init() tts_say(engine, 语音免提编程演示启动) if args.text: raw args.text else: tts_say(engine, 请说出你要让 Codex 完成的任务) try: raw listen_once(backendargs.backend) except sr.UnknownValueError: tts_say(engine, 没有听清楚请重试) sys.exit(2) except sr.RequestError as exc: tts_say(engine, 语音识别服务不可用) print(exc) sys.exit(3) tts_say(engine, f识别结果{raw}) prompt build_prompt(raw) extra_args [] if args.approval_mode: extra_args.extend([--approval-mode, args.approval_mode]) if args.sandbox: extra_args.extend([--sandbox, args.sandbox]) rc run_codex(prompt, Path(args.workdir).resolve(), extra_args) if rc 0: tts_say(engine, 任务执行完成请查看文件改动) else: tts_say(engine, 任务执行失败请查看终端日志) sys.exit(rc) if __name__ __main__: main()使用方式有两种。一种是直接传文本方便调试python voice_codex.py --text 在当前目录创建一个 hello.py运行它并输出结果另一种是真正的语音模式python voice_codex.py --workdir ~/codex-voice-demo --sandbox workspace-write脚本的设计核心是“每段都可以单独替换”。如果觉得在线识别不稳定只需要把listen_once换成 whisper 实现如果不想用 Python也可以把语音转文字放在其他语言里输出文本后再调用codex exec。链路的价值在于接口清晰而不在于某个具体实现。4.3 审批模式与沙箱免提场景的安全取舍普通使用 Codex 时它每做一步修改都会在终端里询问是否同意。但语音免提场景下用户没法按键盘确认。这就产生了一个矛盾既要自动化又要安全。解决思路是分层控制而不是一刀切。控制维度常见语义适合场景风险提示每次询问每个操作都等待人工确认日常开发、学习需要按键不符合完全免提失败时询问只在命令失败时请求介入半自动批处理失败后仍需人工参与全自动不再逐个确认自动执行演示、一次性生成高风险命令也可能被自动执行只读沙箱不允许写文件只想看方案无法完成真实修改工作区沙箱只允许写当前工作目录常规开发、演示仍可能覆盖现有文件完全访问没有文件系统限制特殊系统维护演示中坚决不用在演示脚本里推荐组合是“工作区沙箱 全自动审批”但前提是工作目录是一个干净的临时目录。同时要保证目录本身是 Git 仓库并且每次演示前先提交一次初始状态。这样即使 Codex 改了不该改的地方也能通过git diff看到通过git checkout回滚。注意免提不代表无人审查。语音演示的安全前提是“可回滚”。如果不知道如何回滚一次自动改动就不要启用全自动模式。4.4 语音反馈设计不要播报整段日志Codex 执行任务时输出的日志可能很长包含 diff、命令输出、中间过程。这些内容适合看屏幕不适合用语音朗读。语音反馈只应该播报三件事开始录制的提示、识别结果的确认、最终成功或失败结论。如果希望得到更多信息可以让 Codex 在提示词里按要求输出“一句话总结”和“文件清单”程序再把这部分文本交给 TTS。这样做的好处是反馈短、可预期不会因为日志太长导致播报中断。反馈设计要记住一个原则语音适合传达状态不适合传达细节。细节留在终端日志里。5. 演示预告的演示流程、校验标准和失败预案5.1 场景一用一句话创建小项目演示第一个场景最稳妥风险最低。语音指令可以这样设计在当前目录创建一个 Python 脚本脚本读取一个 CSV 文件并输出每一列的平均值同时生成一个示例 CSV 文件。预期输出是目录里出现示例 CSV 和脚本文件运行后控制台打印出每列平均值TTS 播报“任务执行完成”。这个场景验证了链路最基础的能力语音转文字、自然语言转代码、文件创建、命令执行。它不涉及对已有代码的修改即使 Codex 理解偏差也不会破坏任何东西。5.2 场景二修改已有函数并运行测试第二个场景加入“修改已有文件”的复杂度。先在工作目录里准备一个带函数和测试的小项目然后语音指令把 factorial 函数改成递归实现然后运行 pytest确认测试通过。这个场景的关键在于验证 Codex 能理解“既有代码结构”而不是只会新建文件。演示前要提前准备一个简单项目并确保基础测试本来就是通过的。这样如果运行后测试失败就能明确判断是 Codex 改坏了而不是环境本身有问题。5.3 场景三让 Codex 汇报自己的改动第三个场景重点展示反馈闭环。语音指令查看当前 git diff列出你修改过的文件并且用一句话说明每个文件的作用。这个场景不需要 Codex 做复杂修改重点是让 TTS 播报出文件清单。它向观众展示的不只是“代码能跑”而是“系统知道改了什么”。在真实使用里这种自查能力比“能改代码”更重要因为自动化程度越高可观测性就越关键。5.4 验收清单和失败预案每个演示场景开始前都应该按下面的清单过一遍。任何一项不满足都不要直接进入演示。检查项通过标准不通过时的处理麦克风识别一句测试指令能稳定转成文字换麦克风设备或切换本地识别模型Codex 登录codex exec单次命令能返回结果重新登录验证认证状态工作目录目录存在且已初始化为 Git 仓库手动创建目录并执行git init和首次提交沙箱和审批codex --help确认参数名有效调整参数或改用脚本内置的默认值回滚方案git checkout .可以恢复初始状态补提交初始快照后再继续TTS 反馈播报清晰、语速正常检查系统语音引擎或先使用文字反馈失败预案要在演示前想好而不是演示中临时处理。比如语音识别听错了脚本里的确认环节会播报一次“识别结果”演示者可以纠正后重试Codex 执行超时要准备好一个“直接运行脚本验证结果”的补救动作最坏情况下放弃语音演示用codex exec文本方式继续确保观众看到核心能力而不是看到演示者手忙脚乱。6. 常见问题排查6.1 按链路顺序排查不跳步语音免提编程链路长出问题时的第一原则是“从输入到输出逐段验证”不要跳过某一环直接怀疑最后的结果。推荐排查顺序是麦克风是否拾音单独运行录音脚本查看波形或音量。语音转文字是否成功打印识别文本确认没有乱码。提示词是否构建正确观察cmd里的完整命令。Codex 是否真正执行查看退出码和stdout。文件改动是否符合预期执行git status和git diff。TTS 是否发声单独调用pyttsx3播放一句测试文字。每验证一段就能排除一整类原因。比如语音识别成功但 Codex 没有反应问题就只在 Codex 调用段而不是麦克风段。6.2 问题现象与处理对照表下面的表整理了演示中最常见的几类问题覆盖“现象—原因—检查方式—处理建议”。现象常见原因检查方式处理建议codex命令找不到Node.js 版本过低或 npm 全局目录不在 PATHnode -v、npm list -g openai/codex升级 Node.js重新安装或修复 PATHcodex login卡住或超时网络无法连通认证服务或浏览器弹窗被拦截观察终端提示检查当前网络连通性改用 API Key 方式登录演示前提前完成说话后返回“没有听清楚”环境噪音大、语速太快、语言参数不对查看识别日志单独测试识别脚本靠近麦克风、放慢语速、调整language参数识别成功但 Codex 没有反应工作目录不对或参数名与当前版本不匹配打印cmd和cwd单独执行一次codex exec修正--workdir用codex --help核对参数Codex 修改了无关文件工作区过大、提示词范围不清、沙箱级别过高