Skip to content
BranchesTags

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
CREDITS.md
CREDITS.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

Pawwake 接入 Claude Code 与 Codex

面向使用 Claude Pro / Max 或 ChatGPT 订阅登录的本地 CLI 用户。
适用版本：Pawwake 4.0.1，2026-08-10。 Pawwake 项目：garan0613/pawwake

先说结论

Claude Code 和 Codex 用订阅账号登录时，模型请求可以继续直连官方。Pawwake 作为旁路记忆服务接入：

  • 发送消息前，hook 从 Pawwake 查询相关记忆和历史对话，再注入当轮上下文。
  • 一轮完成后，hook 或前端适配器把干净的真实对话写回 Pawwake。
  • Pawwake 在数据库中按会话计算逻辑轮，到设定间隔时自动提取记忆。

Pawwake 4.0.1 已具备读取 API，但还没有面向外部 CLI 的逐轮对话写入 API、单条记忆写入 API 和官方 hook 模板。因此：

  • 4.0.1 现在可用：读取已有记忆与历史对话。
  • 4.1 计划补齐：自动写回对话、按轮提取记忆、显式创建单条记忆，以及可直接安装的 Claude Code / Codex 模板。

如果你需要一份从零开始、复制即可运行的完整脚本，请等待 4.1 模板。4.0.1 阶段的配置用于说明已验证的接入形状，不代表仓库已包含示例中的 pawwake_recall.py。

一张图看懂两条旁路

                         官方订阅连接
用户消息 ──────────────────> Claude Code / Codex ──> 官方模型
   │                              │
   │ 发送前                       │ 完成后（4.1）
   ▼                              ▼
UserPromptSubmit hook          Stop / notify / adapter
   │                              │
   │ POST 检索                    │ POST /api/conversations/turn
   ▼                              ▼
Pawwake 记忆 + 历史原文         Pawwake 对话库
   │                              │
   └── 历史参考上下文 ──────> 按 N 个逻辑轮提取记忆

这条路线不需要把 Pawwake 配成模型 provider，也不会改变 CLI 原有的订阅登录。

你属于哪一条路

使用方式 4.0.1 现状 建议
Kelivo、ChatBox 等 OpenAI Chat Completions 兼容前端 可把模型请求经过 Pawwake，对话与记忆可自动积累 使用现有网关教程
Claude Code CLI / 本地 Desktop Code 可用 hook 读取；公开版自动写回待 4.1 使用本文 Claude Code 路线
Codex CLI / IDE 扩展 / ChatGPT 桌面端本地 Codex 项目 可用 hook 读取；公开版自动写回待 4.1 使用本文 Codex 路线
Claude Code 网页云环境 仓库 hook 可以运行，个人本机配置不会自动迁移 需云端密钥、网络放行与仓库脚本，暂不作为新手路线
Codex 云任务、普通 ChatGPT / Claude 聊天 本机 lifecycle hook 不在该运行环境中 当前不适用本教程

准备 Pawwake

  1. 部署 Pawwake 4.0.1，并确认 CLI 所在主机能通过 HTTPS 访问它。
  2. 在 Pawwake 中开启记忆系统和需要的对话召回功能。
  3. 确保库里已有内容。可以先通过 Dashboard、seed 或导入功能放入记忆；空库无法召回任何东西。
  4. 为 hook 准备 Pawwake URL 和 X-Gateway-Key。把密钥放在权限为 600 的私有配置文件或操作系统凭据存储中。

密钥不应进入：

  • URL 或 query string
  • 仓库与可共享的 hook 配置
  • 命令行参数
  • 浏览器 localStorage

共用的读取路线

两种 CLI 的 UserPromptSubmit hook 都做同一件事：

  1. 从 hook 输入中取得当前用户消息。
  2. 用 POST /api/memories/search 查询相关记忆。
  3. 用 POST /api/chat/search-fragments 查询带上下文的历史对话。
  4. 排除当前 session，并把已注入过的 fragment_id 放入 exclude_fragment_ids。
  5. 把命中内容限量、标注为“历史参考”，再输出给 CLI 的上下文入口。

读取 hook 应当设短超时。Pawwake 暂时不可用时，当前模型请求继续，hook 不伪造“未命中”结果。

/api/chat/search-fragments 是无状态 API。已看过哪些历史片段，由 hook 在本地维护。只有当前轮成功进入模型上下文后，才把返回的 fragment_id 标记为已看过。

Claude Code 配置

Claude Code 的 hooks 定义在 settings.json 中。用户级配置位于 ~/.claude/settings.json，项目级配置可位于 .claude/settings.json 或不入 Git 的 .claude/settings.local.json。

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/pawwake_recall.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

UserPromptSubmit 在 Claude 处理用户消息前触发。召回脚本读取 stdin 中的 hook JSON，将限量后的历史参考写到 stdout，Claude Code 会把它加入当轮上下文。

公开版 4.1 的写回模板将使用 Stop 事件：它在 Claude 完成回复时触发。模板会从当前会话中取得完整的真实轮次，过滤 system prompt、hook 注入块、终端草稿、tool 诊断与其他脚手架，再写入 /api/conversations/turn。

Claude Code 网页云环境不读取本机 ~/.claude/settings.json。如果要在云环境使用读取 hook，需将项目 hook 与脚本纳入仓库，通过云环境私密配置提供 Pawwake 凭据，并放行相应出站网络。

Codex 配置

Codex 可以从 ~/.codex/hooks.json 或受信任项目的 .codex/hooks.json 载入 hook。CLI、IDE 扩展和 ChatGPT 桌面端的本地 Codex 项目共用配置层。

{
  "description": "Recall Pawwake memories before each local Codex turn.",
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/pawwake_recall.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Codex 会把 hook JSON 写入 stdin。UserPromptSubmit 输入包含 prompt、session_id 和 turn_id；读取脚本可把历史参考作为普通 stdout 或 additionalContext 返回。

第一次配置或修改非托管 hook 后，在 Codex CLI 中使用 /hooks 检查来源并信任当前定义。未信任的项目 hook 会被跳过。

4.1 的 Codex 写回模板会在两种官方机制中选定一条，经实测后固定下来：

  • notify：当前支持 agent-turn-complete，传递 thread-id、turn-id、input-messages 和 last-assistant-message。它把 JSON 作为进程参数传入，共享主机上需要评估短时 argv 暴露。
  • Stop：通过 stdin 接收 turn_id、stop_hook_active 和 last_assistant_message，不需要把正文放进 argv。它可以要求当前 turn 继续，因此模板需验证重复 Stop 时的幂等与最终回复语义。

两条不会同时启用，一个入口只保留一个对话 writer。

codex exec 是 Codex 的非交互模式。它把进度写到 stderr，把最终 assistant 消息写到 stdout。面向 codex exec 的 writer 只保存完成的真实输入与最终消息，不把 stderr 进度、命令输出和事件流当成对话正文。

4.1 的通用对话写入合同

计划中的公开端点为：

POST /api/conversations/turn
X-Gateway-Key: <your-gateway-key>
Content-Type: application/json
{
  "turn_id": "stable-caller-generated-id",
  "session_id": "stable-conversation-id",
  "source": "codex",
  "model": "optional-model-name",
  "messages": [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "occurred_at": "optional-RFC3339-time",
  "extract_memories": true,
  "metadata": {}
}

调用方负责把正文清理干净：

  • 纯本地终端过滤 system prompt、召回块、hook payload、工具诊断和中间态。
  • Telegram、Discord 和自写前端在适配器中按可信的数字用户 / 频道标识做白名单，只保存真实入站正文与已成功送达的最终回复。
  • 一次性终端模式在拿到最终输出后提交，不保存 stderr 或运行日志。

Pawwake 核心不包含 Telegram 或 Discord 专用白名单。网关负责通用的认证、字段验证、整轮事务、幂等去重、检索索引与向量调度。

turn_id 在 source + session_id 内必须稳定。同一轮因网络失败重试时，网关返回幂等成功，不会重复写入、重复向量化或重复提取。

如果前端已经通过 Pawwake 的模型转发链自动落库，就不再启用第二个 hook writer。

记忆会每几轮提取

Pawwake 现有配置 MEMORY_EXTRACT_INTERVAL 定义提取间隔：

  • 0：关闭自动提取
  • 1：每个完整逻辑轮提取
  • N：每 N 个完整逻辑轮提取一次，并把最近 N 轮一起交给提取器

4.1 会把对话存储与 maybe_extract_memories() 拆开。新 turn 成功落库后，网关从数据库读取该 session 的权威历史，用逻辑轮分组：

  1. 只有最终 assistant 消息才闭合一轮并触发间隔判定。
  2. user-only 事件与等待 tool 结果的 assistant 中间态只落库，暂不提取。
  3. 当 当前逻辑轮数 % MEMORY_EXTRACT_INTERVAL == 0 时，取数据库末尾 N 轮提取。
  4. 重复 turn_id 不增加轮数，服务重启也不会丢掉计数。

extract_memories: false 为历史回填、归档导入等请求提供单次关闭通道。第一版继续使用网关全局间隔，不为每个 source 另造一份计数配置。

显式写入单条记忆

4.1 计划增加：

POST /api/memories
X-Gateway-Key: <your-gateway-key>
Content-Type: application/json

它用于 MCP 工具、日记、日摘要、迁移与用户明确指定的重要事实。它不是 hook 每轮要再调一次的第二条写入链。

逐轮 hook 只写 /api/conversations/turn。到达提取间隔后，Pawwake 内部提取器复用同一条记忆保存路径。

高级路线：让模型请求经过 Pawwake

这条路线不属于订阅用户的旁路教程，也不阻塞 4.1 的 hook 交付。

  • Claude Code 网关使用 Anthropic Messages 协议。Pawwake 4.0.1 只提供 OpenAI Chat Completions，目前无法作为 Claude Code 的完整协议网关。
  • Codex 自定义 provider 的 wire_api 当前使用 Responses。Pawwake 4.0.1 没有 /v1/responses，修改 Base URL 不能完成全量转发。

认证与协议适配需要分开判断：

  • Claude Code 使用网关凭据或 apiKeyHelper 时，该凭据取代订阅登录。只设 ANTHROPIC_BASE_URL 而不设网关凭据时，Claude Code 可以保留已登录的订阅身份，但中间网关必须完整支持并转发 Anthropic 要求的 OAuth capability。Pawwake 当前不支持这条链。
  • Codex 的 ChatGPT 订阅登录与 API key / 自定义 provider 是分开配置路径。实现 Responses 协议不能单独证明 ChatGPT 订阅额度会流经 Pawwake。

两条高级协议线都必须使用真实客户端样本验证 system / instructions、tool call 与 result、流式事件、usage、取消与错误语义。文本能转发不等于 CLI 完整兼容。

常见问题

hook 没有召回任何内容

先确认 Pawwake 中已有可召回内容，再检查 URL、X-Gateway-Key、网络和 hook 是否已加载。Codex 还需要在 /hooks 中确认非托管 hook 已被信任。

同一批历史片段反复出现

检查调用方是否持久化 fragment_id seen-set，并在下次检索时传入 exclude_fragment_ids。

对话没有自动长出新记忆

如果使用公开版 4.0.1 的 CLI 旁路，这是当前预期行为。该版本还没有 /api/conversations/turn 和外部 ingest 提取链。

对话出现重复

检查是否同时启用前端转发落库和 hook writer，并确认重试时复用同一个 turn_id。

修改 Base URL 后 CLI 无法工作

先核对客户端要求的协议、认证方式与流式事件。Pawwake 4.0.1 的 /v1/chat/completions 不能代替 Anthropic Messages 或 OpenAI Responses。

官方资料

许可与署名

本文档采用 Creative Commons Attribution-ShareAlike 4.0 International（CC-BY-SA-4.0）许可。共同创作与维护者见 CREDITS.md。

About

Use Pawwake as a sidecar memory service with Claude Code and Codex subscription logins.

Resources

Readme
License
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors