OpenAI Codex Python SDK 快速上手：从安装、登录到多轮对话与沙箱权限控制

OpenAI Codex Python SDK 快速上手：从安装、登录到多轮对话与沙箱权限控制

【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter

本指南基于本仓库 sdk/python 中的官方入门文档 getting-started.md 展开，目标是让读者在最短时间内把已发布的openai-codexPython SDK 跑起来，并打通"启动客户端 → 认证 → 启动线程 → 运行多轮 turn → 选择沙箱权限 → 使用异步 API"的完整闭环。读完你将能够用十余行 Python 代码驱动 Codex 完成真实编码任务，也能理解Codex/Thread/TurnHandle/Sandbox这些核心对象在源码层面的真实行为，为后续阅读 API reference、FAQ 与 可运行示例 打下基础。

1. 安装 SDK 与运行依赖

在已安装 Python 3.10 及以上版本的环境中，直接通过 pip 安装 SDK：

pip install openai-codex

运行时依赖的自动安装

文档明确说明 SDK 会自动安装与之匹配的openai-codex-cli-bin运行时依赖。从 pyproject.toml 可以看到项目本身声明了：

requires-python = ">=3.10" dependencies = ["pydantic>=2.12", "openai-codex-cli-bin==0.144.4"]

也就是说openai-codex-cli-bin被固定为精确版本（而非浮动版本），SDK 的发布版本号与对应的 Codex CLI 发布版本严格对齐，二者必须协同工作。安装完成后，SDK 客户端会在运行时通过codex_cli_bin.bundled_codex_path()定位随依赖一起分发的 Codex 可执行文件（见 client.py），然后以子进程方式拉起本地 Codex 运行时。

环境要求小结

• Python>=3.10（由requires-python强制约束，低于该版本的解释器将无法安装）；
• 已存在的 Codex 账户会话，或下文任一种登录流程；
• 网络可达 Codex 后端服务（SDK 通过本地 CLI 运行时与后端通信，并非直连网络 API）。

2. 创建客户端：上下文管理器与连接生命周期

SDK 的入口是Codex（同步）与AsyncCodex（异步）两个客户端类，二者都在模块顶层被导出，见init.py。使用方式均为"上下文管理器 + with 语句"：

from openai_codex import Codex with Codex() as codex: thread = codex.thread_start() result = thread.run("Explain this repository in three bullets.") print(result.final_response)

从源码实现看，Codex.__init__在构造期间就会start()连接本地运行时并完成initialize()握手（见 api.py）；__exit__会调用close()关闭底层进程与管道（api.py）。因此文档推荐始终用with语句，让资源能够被及时、确定性地释放。

客户端底层在做什么？

CodexClient的start()方法（client.py）展示了连接的本质：SDK 会定位 Codex 可执行文件并启动：

codex app-server --listen stdio://

也就是说，Python SDK 与 Codex 本地运行时之间通过stdio 上的类型化 JSON-RPC通信（app-server监听stdio://），SDK 包一个MessageRouter来处理进程 stdout 上的通知与响应。理解这一点有助于排查"装了 SDK 却连不上"类问题：SDK 依赖的是一个能启动的本地 Codex 二进制。

可选的 CodexConfig

大多数场景直接Codex()即可。需要显式指定本地 Codex 可执行文件时，可传入CodexConfig。该配置类（client.py）支持以下字段：

• codex_bin：指定要使用的 Codex 二进制路径（默认自动解析已安装的openai-codex-cli-bin）；
• launch_args_override：整体覆盖进程启动参数；
• config_overrides：追加--config key=value形式的 Codex 配置覆盖项；
• cwd：设置运行时子进程的工作目录；
• env：注入额外环境变量；
• client_name/client_title/client_version：标识调用方的客户端元信息（默认codex_python_sdk/Codex Python SDK）。

例如仓库中的官方示例会通过一个runtime_config()辅助函数构造配置并在启动线程时指定模型与推理参数（见 examples/01_quickstart_constructor/sync.py）。

3. 认证：复用会话与三种登录方式

SDK 会自动复用已存在的 Codex 认证。若需要显式发起登录，SDK 提供三种方式，对应 api.py 上的三个方法：

3.1 ChatGPT 浏览器登录

from openai_codex import Codex with Codex() as codex: login = codex.login_chatgpt() print(login.auth_url) print(login.wait().success)

调用后会返回一个ChatgptLoginHandle。从源码看（client.py 中account_login_start与 _login.py），login_chatgpt()发出type="chatgpt"的登录请求，响应中携带login_id与auth_url。你需要用浏览器打开login.auth_url完成授权，再调用login.wait()阻塞等待turn/completed同类的登录完成通知；wait()返回的通知对象含success字段用于判断结果（_login.py）。登录句柄还提供cancel()方法可在等待期间取消该次登录尝试。

3.2 设备码（Device Code）登录

with Codex() as codex: login = codex.login_chatgpt_device_code() print(login.verification_url, login.user_code) print(login.wait().success)

适用于无浏览器自动化能力的终端/服务器环境。SDK 发出type="chatgptDeviceCode"请求（_login.py），返回DeviceCodeLoginHandle，其中包含verification_url与user_code。你需要在另一台设备上打开验证网址并输入用户码完成绑定，随后同样调用login.wait()等待结果。

3.3 API Key 登录

with Codex() as codex: codex.login_api_key("sk-...") print(codex.account().account)

login_api_key("sk-...")会把 API Key 通过account_login_start（type="apiKey"，见 api.py）提交给本地运行时完成认证。它没有返回等待句柄；紧接着调用codex.account()即可读取当前账户状态（返回的GetAccountResponse中.account字段为账户标识）。与之配套的还有codex.logout()用于清除当前账户会话。

提示：一旦某种方式登录成功，后续程序运行会自动复用该会话，不需要重复登录。若需程序化校验当前会话是否有效，可调用codex.account()。

4. 运行一轮对话：线程与 Turn 模型

完成认证后，最核心的调用模式是"先thread_start建线程，再run跑一轮 turn"：

from openai_codex import Codex, Sandbox with Codex() as codex: thread = codex.thread_start(sandbox=Sandbox.workspace_write) result = thread.run("Say hello in one sentence.") print("Thread:", thread.id) print("Text:", result.final_response) print("Items:", len(result.items))

thread_start的完整签名（api.py）还支持大量可选参数，例如：

• approval_mode：审批模式，默认ApprovalMode.auto_review；
• model/model_provider：指定模型与提供方（如不指定则用运行时的默认模型）；
• cwd：线程工作目录；
• base_instructions/developer_instructions：追加系统级指令；
• personality/service_tier等高级选项。

4.1 run 的返回值

Thread.run(input, ...)的语义是"启动一个 turn → 等待它完整结束 → 聚合出最终结果"。源码实现（api.py）其实是内部调用了turn()拿到TurnHandle，再消费其事件流：

turn = self.turn(input, ...) stream = turn.stream() return _collect_turn_result(stream, turn_id=turn.id)

_collect_turn_result会持续读取 turn 的流式通知，直到收到turn/completed，再把最终响应聚合成TurnResult。TurnResult提供：

• final_response：模型最终文本回复；
• items：本次 turn 收集到的全部条目列表（包括文本、工具调用、文件编辑等输入输出项）；
• 以及 token 用量等元信息（见 README 对TurnResult的说明 sdk/python/README.md）。

4.2 输入参数与字符串简写

文档特别强调：纯字符串是TextInput(...)的简写。在 _inputs.py 中可以看到输入类型的归一化逻辑：

• TextInput：纯文本输入；
• ImageInput：以 data URL 形式提供的图片输入；
• LocalImageInput：本地图片路径输入；
• SkillInput/MentionInput：引用命名技能或资源的输入。

run/turn接受RunInput（即str | InputItem | list[InputItem]）。当传入字符串时，_normalize_run_input会把它自动包装为TextInput，再经_to_wire_input转成 JSON-RPC 线上的{"type": "text", "text": ...}结构。这意味着你可以直接写多模态输入，例如thread.run([TextInput("描述这张图"), LocalImageInput("/tmp/photo.png")])，而不需要自己拼接协议结构。

5. 选择沙箱访问级别：read_only / workspace_write / full_access

Codex 会在受限沙箱中执行文件系统操作。SDK 用一个枚举Sandbox统一表达权限预设，既可用于初始线程（thread_start(sandbox=...)），也可用于后续单轮覆盖（thread.run(..., sandbox=...)）：

from openai_codex import Codex, Sandbox with Codex() as codex: thread = codex.thread_start(sandbox=Sandbox.workspace_write) thread.run("Make the requested changes.") review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

三种预设的语义

• Sandbox.read_only：只允许读取文件，禁止任何写入。适合代码评审、只读问答场景；
• Sandbox.workspace_write：可读取文件，并允许在工作区（workspace）及已配置的可写根目录（writable roots）内写入。这是工作区开发的常规默认项；
• Sandbox.full_access：不施加文件系统访问限制（danger_full_access）。

源码中的落点

Sandbox枚举的定义位于 _sandbox.py：

• 在线程生命周期（thread_start）上，枚举被翻译成SandboxMode（read_only/workspace_write/danger_full_access），见_sandbox_mode()（_sandbox.py）；
• 在单轮覆盖（turn的sandbox_policy参数）上，被翻译成完整的SandboxPolicy结构（ReadOnlySandboxPolicy/WorkspaceWriteSandboxPolicy/DangerFullAccessSandboxPolicy），见_sandbox_policy()（_sandbox.py）。

两个值得注意的行为

1. 当sandbox=被省略时，Codex 使用其已配置的默认沙箱级别（thread_start的sandbox参数默认为None，此时不强制指定，交给运行时配置决定，见 api.py）。注意文档强调workspace_write是"对已记录信任决策的项目"的正常默认。
2. turn 上的覆盖具有延续性：在某个 turn 上传入的 sandbox 覆盖，也会作用于该线程后续的 turns，直到再次显式覆盖。上面的示例里先用workspace_write做修改，再用read_only复查 diff，正是这一特性的典型用法。

6. 延续多轮线程与恢复历史线程

线程（Thread）本质上是一个可累积上下文的多轮会话容器，run一次即向该线程追加一个 turn。多轮延续直接在同一 Thread 上再次run即可：

from openai_codex import Codex with Codex() as codex: thread = codex.thread_start() thread.run("Summarize Rust ownership in two bullets.") result = thread.run("Now explain it to a Python developer.") print(result.final_response)

第二轮的run会把第一轮的对话历史作为上下文带给模型，从而保持话题连续性。

恢复历史线程

Codex 线程默认会被持久化，拿到线程 ID 即可在任意时刻、任意进程中恢复它：

with Codex() as codex: thread = codex.thread_resume("thr_123") print(thread.run("Continue where we left off.").final_response)

thread_resume(thread_id, ...)（api.py）与thread_start接受相似的覆盖参数（model、sandbox、cwd、approval_mode等）。SDK 客户端还提供完整的线程管理能力：thread_list()列出已保存线程、thread_fork()从既有线程分叉出新线程、thread_archive()/thread_unarchive()归档与恢复（详见 api.py）。

何时用 run，何时用 turn？

文档给出的判据很清晰：默认用thread.run(...)即可获得"阻塞等待 + 聚合结果"的最简体验；当需要流式读取中间事件、主动 steer 转向、或 interrupt 打断正在进行的 turn 时，才改用thread.turn(...)—— 它返回一个TurnHandle，通过handle.stream()逐条消费通知，通过handle.steer(...)向活跃 turn 注入新输入，通过handle.interrupt()请求中断（见 api.py）。

7. 异步客户端 AsyncCodex

对于需要高并发、或在 async/await 应用（FastAPI、爬虫、事件驱动框架）中集成 Codex 的场景，SDK 提供与同步 API 完全对应的AsyncCodex。AsyncThread.run()也同样是await形式：

import asyncio from openai_codex import AsyncCodex, Sandbox async def main() -> None: async with AsyncCodex() as codex: thread = await codex.thread_start(sandbox=Sandbox.workspace_write) result = await thread.run("Continue where we left off.") print(result.final_response) asyncio.run(main())

异步客户端的初始化语义

与同步Codex（构造即连接）不同，AsyncCodex采用惰性初始化：在进入async with上下文或第一次 await 某个 API 时才真正建立连接，并通过一把asyncio.Lock保证并发初始化只发生一次（见 api.py）。因此：

• 始终优先使用async with AsyncCodex()，让初始化与关闭显式配对；
• 若在async with之外提前访问codex.metadata，会抛出RuntimeError提示尚未初始化（api.py）。

仓库在 examples 目录为每个场景都提供了sync.py与async.py双版本（例如 03_turn_stream_events、05_existing_thread、09_async_parity），可直接对照学习同步/异步写法差异。

8. 获取内置帮助

SDK 面向公众导出的 API 表面经过精挑细选，可直接借助 Python 内建文档工具浏览，无需翻阅外部文档：

import openai_codex from openai_codex import Codex, CodexConfig help(openai_codex) help(Codex) help(CodexConfig)

也可以使用 pydoc 命令行工具：

python -m pydoc openai_codex

CodexConfig与Codex的 docstring 均来自源码中的类注释（client.py），会随版本更新保持一致。更完整的逐方法说明可继续阅读 API reference。

9. 从本仓库源码开发与调试

如果你是从源码克隆本仓库进行开发或调试（而非消费 PyPI 发布版），可以进入 SDK 目录用uv安装开发依赖并激活虚拟环境：

cd sdk/python uv sync --group dev source .venv/bin/activate

其中dev依赖组在 pyproject.toml 中定义，聚合了pytest、ruff等测试与格式化工装。仓库内还自带一套覆盖客户端生命周期、登录、运行、流式与 turn 控制的测试（见 sdk/python/tests 下的test_app_server_*.py系列），可作为理解各 API 行为的活文档。

若你只想快速验证 SDK 功能、不想手动编写样板代码，仓库提供了大量可运行示例，从最基础的thread_start + run到流式事件、图片输入、错误重试与 CLI 迷你应用一应俱全，参见 examples 目录说明 并按编号顺序阅读（01_quickstart_constructor→15_login_and_account）即可获得一条平滑的进阶路径。

【免费下载链接】openinterpreterA coding agent for open models like Kimi K3 and GLM 5.3项目地址: https://gitcode.com/GitHub_Trending/op/openinterpreter