---
title: "SessionEnd 做清理：默认 1 秒，切走对话不会立刻触发"
summary: "归档、删除、正常退出、空闲约 30 分钟才跑。输出不能续写会话。不要用 mcp_tool，也不要设 600 秒超时。"
category: hooks
level: advanced
surfaces: [cli, app]
tags: ["hooks", "SessionEnd", "清理"]
canonical: /tips/session-end-hook/
---

# SessionEnd 做清理：默认 1 秒，切走对话不会立刻触发

归档、删除、正常退出、空闲约 30 分钟才跑。输出不能续写会话。不要用 mcp_tool，也不要设 600 秒超时。

`SessionEnd` 只给主线程。子代理结束走 `SubagentStop`，不要混用。触发包括：仍打开时归档或删除对话、进程正常退出、没有任何客户端连着且空闲约 30 分钟。切到别的对话，或 app-server 的 `thread/unsubscribe`，**不会**马上跑。

```toml
[[hooks.SessionEnd]]
matcher = "other"

[[hooks.SessionEnd.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/session_end.py"'
timeout = 3
statusMessage = "Saving session notes"
```

官方约束：

- 现在 `reason` 只有 `other`。matcher 可省略，或写成 `other`
- 默认超时 **1 秒**，上限 **3 秒**。别的钩子默认 600 秒，抄过来会在拆会话时被砍掉
- 输出是建议性的：不能 `continue: false`，也不能把 additionalContext 送回模型
- 不支持 `mcp_tool`；`async = true` 仍同步跑
- 钩子执行时 transcript 已经 flush，stdin 里有 `session_id`、`transcript_path`、`cwd`

适合写收尾笔记、删临时目录。不要在这里做完成门或再调一次 MCP 扫描。Esc 打断正在跑的顶层轮走 `Interrupt`，不是 `SessionEnd`。

## 来源

- [OpenAI · Hooks](https://learn.chatgpt.com/docs/hooks)