Notion AI Proxy — AI skill for Claude Code

Notion AI 本地代理（ai-proxy）

把 **Notion 网页版里的 AI** 变成 **本机可用的 OpenAI 兼容接口**。

启动后，你会得到这样一个地址：

http://127.0.0.1:8787/v1

任何支持 OpenAI 接口的客户端（Cherry Studio、Cursor、各种 SDK、自己写的脚本）都可以连它， 直接使用 Notion AI 背后的 Claude、GPT、Gemini、Kimi、Grok、DeepSeek、GLM 等模型。

本机自用工具：只监听 `127.0.0.1`，别人访问不到；登录凭据只存在本机 `secret/` 目录里。 使用前请先看文末的 [安全与风险提示](#10-安全与风险提示)，了解可能的风控与账号风险。

---

目录

1. 它能做什么
2. 准备工作
3. 快速开始（3 步）
4. 验证是否启动成功
5. 在客户端里怎么填
6. 模型怎么选
7. 批量处理文件（batch_process.py）
8. 登录态过期怎么办
9. 常见问题
10. 安全与风险提示
11. 文件结构说明
12. 附录：接口与配置

---

1. 它能做什么

• 提供 OpenAI 兼容接口，把请求转发给 你自己的 Notion AI 网页登录态：
  • POST /v1/chat/completions：聊天补全（支持 stream: true 流式输出）
  • GET /v1/models：模型列表（动态来自你的 Notion 账号）
  • GET /health：健康检查
• 模型列表动态发现，通常有 30 个以上，涵盖 Claude / GPT / Gemini / Kimi / Grok / DeepSeek / GLM 等。
• 支持多轮对话、流式输出、web_search（联网搜索）、reasoning_effort（思考强度，部分模型）等可选参数。
• 附带四个示例脚本：
  • examples/openai_python.py：官方 openai SDK 示例（非流式 + 流式）
  • examples/curl_chat.cmd：curl 示例（已处理中文编码）
  • examples/batch_process.py：批量处理工具，把一整个目录的代码/文本交给 AI 处理，结果存成 .md
  • examples/auto_agent.py：自动改代码 agent，让 AI 自己读文件、改文件（dry-run 预览 + 自动备份）

**不支持的（别在这些地方浪费时间）：**

不支持的能力	说明
原生 tools / function calling	Notion 网页接口不提供原生工具调用，Cursor 的 Agent 这类客户端用不了；但 examples/auto_agent.py 用「文本 JSON 协议」在本地执行读写文件，能实现有限的自动改代码
图片 / 文件附件	✅ 已支持（2026-10 实测）：OpenAI 的 image_url / file part、Anthropic 的 image / document block；支持本地文件（base64）、data: URL、公网 URL。图片/PDF 走 attachment step，文本类文件（txt/md/csv/json/代码等）走 computer-file step。限制见 5.8
temperature、max_tokens 等采样参数	会被忽略，不生效
/v1/embeddings、/v1/images、/v1/audio	未实现
给别的电脑/手机远程使用	默认只绑定 127.0.0.1，而且强烈不建议改成对其他设备开放

关于流式：代理是"伪流式"（`streamMode: "pseudo"`）——等 Notion 生成完整回答后分块推送， 所以可能先停顿一会儿、再