kymuco/chatgpt-web-adapter

# webchat-adapter [](https://github.com/kymuco/webchat-adapter/actions/workflows/ci.yml) 用于控制现有 ChatGPT web 会话而无需浏览器 UI 的 Python SDK。 `webchat-adapter` 是一个小巧、零依赖的 Python SDK，用于发送 prompt、继续对话、读取对话状态、上传图像，以及从 Python 处理选定的 ChatGPT web 工作流。 它专为那些已经拥有有效 ChatGPT web 会话 auth 数据并希望避免操控浏览器 UI 的工具而设计。 ## 这是什么 `webchat-adapter` 封装了已登录 web 会话所使用的现有 ChatGPT web 后端行为。它专注于可重用的传输、请求格式化、响应解析和对话辅助功能。 该 package 特意没有包含来自 `webchat-openai-cli` 的 CLI、本地化、auth 捕获、浏览器自动化或本地聊天记录管理功能。 ## 适用场景 - 无需加载浏览器 UI 即可控制长时间的 ChatGPT 对话 - 在现有 ChatGPT web 会话之上构建本地工具或 CLI - 通过 id 或 URL 继续现有的 ChatGPT web 对话 - 将 assistant 的 token 流式传输到终端或应用 UI - 从 Python 读取消息并轮询对话状态 - 通过 web 会话流程上传图像 - 体验无浏览器的审批工作流 ## 这不是什么 `webchat-adapter` 不是： - 官方的 OpenAI API - OpenAI Python SDK 的替代品 - 登录或 auth 捕获工具 - 浏览器自动化框架 - 针对未公开的 ChatGPT web 内部机制的稳定契约 ## 功能 - 零运行时 Python 依赖 - 同步的 `ChatGPTWebClient` - 通过 `on_token` 进行流式传输，以及通过 `on_event` 处理结构化事件 - 使用返回的对话元数据继续对话 - 针对现有对话的附加、读取、状态辅助功能 - 支持 `auth_data.json` 和 `.env` auth 加载 - 支持从本地路径、`Path`、URL、data URI 或原始字节上传图像 - 专为 web-agent 流程提供的实验性无浏览器 tool 审批辅助功能 - 专为高级用户提供的实验性原始 payload 逃生舱 - 本地基于 `curl` 的传输机制，以兼容原生的 Python ## 环境要求 - Python 3.10+ - 系统的 `curl` 可在 `PATH` 中找到 - 包含 `accessToken` 的有效 `auth_data.json`，或可选的带有 `accessToken` 的 `.env` 回退方案 ## 安装 ``` python -m pip install -e . ``` 用于测试： ``` python -m pip install -e .[test] pytest -q ``` ## 快速开始 ``` from webchat_adapter import ChatGPTWebClient client = ChatGPTWebClient(auth_file="auth_data.json") response = client.send( "Give me a short summary of this project.", model="gpt-4o-mini", ) print(response.text) ``` ## Auth 概览 `webchat-adapter` 不会执行登录操作，也不会自行捕获 auth。它仅重用现有的 `chatgpt.com` web 会话数据。 推荐的 `auth_data.json` 格式： ``` { "accessToken": "eyJhbGciOi...", "cookies": { "__Secure-next-auth.session-token": "..." }, "headers": { "user-agent": "Mozilla/5.0 ..." } } ``` - `accessToken` 是来自您浏览器会话的 ChatGPT web 访问 token。它不是官方的 OpenAI API key。 - `cookies` 和 `headers` 应与该 token 来自同一个账户/会话。 - `.env` 是可选的，非必需。如果存在，`accessToken=...` 仅在文件 token 缺失或过期时作为回退方案使用。 - 为了向后兼容，仍然使用 `api_key` 的旧文件会被接受，但新的示例和文件应使用 `accessToken`。 - 如果您需要生成此文件，请使用 `webchat-openai-cli` 捕获它，然后在此处重用。 ## 常见工作流 ### 流式回调 ``` from webchat_adapter import ChatGPTWebClient client = ChatGPTWebClient(auth_file="auth_data.json") response = client.send( "Stream the answer token by token.", on_token=lambda token: print(token, end="", flush=True), ) ``` ### 继续现有的 ChatGPT Web 对话 ``` from webchat_adapter import ChatGPTWebClient client = ChatGPTWebClient(auth_file="auth_data.json") response = client.send_to_conversation( "https://chatgpt.com/c/...", "Continue from this point.", ) print(response.text) ``` `send_to_conversation()` 会附加到最新的 web 对话状态，自动解析当前的父级消息，并尽可能保留检测到的模型。模型检测采用尽力而为的策略，因为 ChatGPT web 的 payload 可能会发生变化。如果无法检测到模型，SDK 将使用常规 `send()` 的默认模型。 ### 从 SDK 响应继续 ``` from webchat_adapter import ChatGPTWebClient client = ChatGPTWebClient(auth_file="auth_data.json") first = client.send("Start a conversation.") second = client.send( "Continue it.", conversation=first.conversation, ) ``` 其他常见的 API： - 使用 `client.get_messages(...)` 读取对话消息 - 使用 `client.get_status(...)` 轮询对话状态 - 使用 `client.wait_until_completed(...)` 等待完成 - 使用 `client.send_and_auto_approve(...)` 审批选定的 tool 流程 - 使用 [examples/diagnose_latency.py](examples/diagnose_latency.py) 检查请求延迟 ## 示例 - [examples/basic_send.py](examples/basic_send.py) - 发送一个 prompt 并打印响应元数据 - [examples/continue_saved.py](examples/continue_saved.py) - 保存 `ChatConversation` 元数据并在稍后继续 - [examples/attach_existing.py](examples/attach_existing.py) - 附加到现有的对话 URL 或 id - [examples/read_messages.py](examples/read_messages.py) - 从现有对话中读取消息 - [examples/status_polling.py](examples/status_polling.py) - 轮询对话生命周期状态 - [examples/approve_tools.py](examples/approve_tools.py) - 审查后批准待处理的 tool 操作 - [examples/raw_payload.py](examples/raw_payload.py) - 发送实验性的原始 web 后端 payload - [examples/diagnose_latency.py](examples/diagnose_latency.py) - 打印请求和流式传输诊断信息 - [examples/github_auto_approve.py](examples/github_auto_approve.py) - 专门的 GitHub 连接器审批演示 ## 实验性功能 SDK 包含用于 web-agent/tool 审批流程的实验性无浏览器辅助功能： - `approve_pending_action()` - `wait_and_approve_pending_actions()` - `send_and_auto_approve()` 这些 API 对于 ChatGPT web 连接器流程（例如 GitHub 文件创建）非常有用，但它们依赖于逆向工程的 web 行为，应被视为不如基础 `send()` API 稳定。 请参阅 [USAGE.md](USAGE.md) 和 [examples/github_auto_approve.py](examples/github_auto_approve.py)。 SDK 还包含面向高级用户的实验性原始 payload 逃生舱： - `PayloadBuilder` - `validate_payload()` - `send_payload()` 请参阅 [docs/raw_payload.md](docs/raw_payload.md)。 此 API 发送原始的 ChatGPT web 后端 payload。它不是官方或稳定的 API。 该示例脚本包含： - 一个中立的仓库占位符，而不是硬编码的演示仓库 - 实时的 assistant token 打印 - 结构化的审批进度事件 ## Auth 说明 此 repository 仅消费现有的 auth 数据。如果您仍然需要基于浏览器的捕获，请先使用 `webchat-openai-cli` 生成 `auth_data.json`，然后在此处重用。 ## 详细指南 如需完整的 SDK 演练，包括 auth 流程、`warmup()`、`temporary`、`web_search`、`reasoning_effort`、对话继续、图像输入、响应对象和错误处理，请参阅 [USAGE.md](USAGE.md)。 ## 未来重命名 该项目稍后可能会迁移到更清晰的名称 `chatgpt-web-adapter`，其 Python package 导入名为 `chatgpt_web_adapter`。 目前 `webchat_adapter` 导入仍是当今唯一受支持的导入方式。请参阅 [docs/rename_compatibility.md](docs/rename_compatibility.md)。 ## 状态 初始 SDK 基线。该 repository 特意保持小巧，并首先专注于传输层。 GitHub Actions 会在跨 Ubuntu 和 Windows 平台的 Python 3.10-3.13 上验证测试，并检查 package 是否构建成功。

标签：ChatGPT, Promptflow, Python, 无后门, 网络会话, 适配器, 逆向工具