# Claude Code 命令与缓存影响

> Claude Code 常用 CLI、斜杠命令、模型切换、后台 agent、Web/Remote Control 与 5 分钟/1 小时 prompt cache 的关系。

URL: https://docs.passion8.cc/docs/claude-code/command-cache
Language: zh-CN
Publisher: Passion8

这页把“某个命令会不会让下一轮变慢、变贵”单独列出来。核心规则只有三条:

1. 缓存按请求开头的完全一致前缀命中。
2. 5 分钟和 1 小时 TTL 只决定多久没用会过期,不改变命中规则。
3. 模型、effort、fast mode header、system prompt、工具定义集合变了,下一轮通常会重建缓存。




Claude subscription 在计划额度内通常使用 1 小时 TTL。API key、Bedrock、Vertex、Foundry、Claude Platform on AWS 和第三方 provider 默认是 5 分钟 TTL。第三方网关是否真的命中,取决于它是否完整转发缓存、工具和 beta 字段。




如果你想把缓存策略落到日常开发流程,看 [最佳实践与工作流](https://docs.passion8.cc/docs/claude-code/best-practices-workflows)。

## TTL 读法

| 场景 | 5 分钟 TTL | 1 小时 TTL |
| --- | --- | --- |
| 连续追问 | 每轮命中会刷新 5 分钟计时 | 每轮命中会刷新 1 小时计时 |
| 休息 10 分钟回来 | 通常重新处理前缀 | 通常仍可读旧前缀 |
| 换模型或 effort | 仍然 miss | 仍然 miss |
| 开启 fast mode 的第一轮 | 仍然 miss,且按 fast mode 处理未缓存输入 | 仍然 miss,但后续更能扛长间隔 |
| `/compact` 后 | 摘要请求通常读旧缓存,摘要后新历史重建 | 同上,只是旧缓存活得更久 |

## CLI 启动命令

| 命令 | 缓存影响 | 5m / 1h 解释 |
| --- | --- | --- |
| `claude` | 新交互会话加载 system prompt、目录、git 状态、CLAUDE.md | 同一目录短时间连续开会话可能读到共享前缀;1h 更适合离开后回来 |
| `claude "query"` | 等同交互会话加一条初始消息 | 初始 prompt 不同只影响末尾,前面项目上下文仍可能命中 |
| `claude -p "query"` | 非交互一次性请求,仍使用 Claude Code system prompt | 脚本频繁调用时 5m 内更容易热;间隔任务可考虑 1h |
| `claude -c` | 继续当前目录最近会话 | 若未升级 CLI 且 TTL 未过期,历史前缀可命中 |
| `claude -c -p "query"` | 继续最近会话并追加一次请求 | 同上,适合自动化补问 |
| `claude -r "<session>"` | 恢复指定会话 | 旧会话很长时,TTL 过期后的第一轮会重新处理大量历史 |
| `claude --model <model>` | 本次启动指定模型 | 模型是 cache key,不同模型之间不共用缓存 |
| `claude --effort <level>` | 本次启动指定 effort | effort 是 cache key,不同 effort 之间不共用缓存 |
| `claude --fallback-model a,b` | 只在主模型不可用时尝试备用模型 | 触发 fallback 的那一轮等同模型切换,备用模型另建缓存 |
| `claude --safe-mode` | 不加载 CLAUDE.md、skills、plugins、hooks、MCP、output style 等自定义项 | prefix 形状和普通启动不同,用于排错,不要拿它判断正常缓存命中率 |
| `claude --teammate-mode <mode>` | 设置 Agent Teams 显示模式,不直接改变模型请求 | teammate 生成后每个 teammate 独立建缓存;显示模式本身不吃 5m/1h |
| `claude update` / `claude install stable` | 下次启动可能换 system prompt 或工具定义 | 升级后的第一轮通常全量 miss,1h 也不能跨版本保证命中 |
| `claude doctor` | 诊断命令,通常不调用模型 | 不涉及 prompt cache |
| `claude agents` | 打开 Agent View 或输出后台 session 列表 | 只是管理界面;派发新 agent 后各 agent 有自己的缓存 |
| `claude attach <id>` | 附加到后台 session | 继续该后台 session 的历史;TTL 内更容易命中 |
| `claude logs <id>` | 查看后台日志 | 不调用模型 |
| `claude stop/rm/respawn <id>` | 管理后台 session | `respawn` 后下一轮可能因进程和版本变化重新建缓存 |
| `claude mcp login/logout <name>` | 只处理 MCP OAuth | OAuth 本身不改 prompt;连接状态变化会在重启或下一次 server 变化时影响缓存 |
| `claude remote-control` | 启动 Remote Control server mode | 远程消息进入同一会话历史;认证和 base URL 限制见 [网页与远程控制](https://docs.passion8.cc/docs/claude-code/remote-web) |
| `claude project purge` | 删除项目本地状态 | 删除 transcript 后无法靠 `/resume` 继续旧历史 |
| `claude gateway` | 管理员启动 Claude apps gateway | 不直接影响当前 CLI 会话缓存,但网关实现会影响所有经它转发的缓存 |

## 会话内命令

| 命令 | 缓存影响 | 5m / 1h 解释 |
| --- | --- | --- |
| `/add-dir <path>` | 增加可读目录,通常作为会话消息追加 | 不会加载新目录 `.claude/` 配置;TTL 内主前缀仍热 |
| `/advisor [model\|off]` | advisor tool 定义位于缓存断点后,开关通常不破坏主缓存 | advisor 自己每次会重新读完整 transcript,不复用 advisor 调用间缓存 |
| `/agents` | 新版本只是提示如何管理 subagents | 不改 prompt;旧版本打开创建界面也主要是交互操作 |
| `/autofix-pr [prompt]` | 派发 Claude Code on the web 监控 PR | 云端 session 有自己的环境和缓存,本地会话只追加派发记录 |
| `/background [prompt]` / `/bg` | 当前会话转后台,可附加一条新指令 | 同一 session 继续运行;后台进程重连后仍按它自己的 TTL 命中 |
| `/batch <instruction>` | bundled skill,拆成 5 到 30 个 worktree/subagent 单元 | 主会话追加 plan;每个后台 subagent 自己建缓存,通常 5m TTL |
| `/branch [name]` | 从当前点复制会话分支 | 分支继承旧前缀,TTL 内第一轮更容易命中 |
| `/btw <question>` | 旁路问题,不进入主 conversation | 不污染主缓存,适合临时问一句 |
| `/cd <path>` | 移动当前会话到新目录,官方说明会尽量保留 conversation cache | 新目录 CLAUDE.md 作为消息追加;5m/1h 内旧历史仍可命中 |
| `/chrome` | 配置 Claude in Chrome | 配置动作本身不影响模型缓存;浏览器工具输出进入历史后会增加上下文 |
| `/claude-api ...` | bundled skill,加载 API 参考或迁移指导 | skill 指令作为消息追加;大量参考内容会增加后续输入 |
| `/clear [name]` | 清空当前上下文开始新会话 | 旧会话可恢复,但新会话重建项目前缀 |
| `/code-review ...` | bundled skill,本地或云端多 agent review | 本地 review 追加指令和工具结果;`ultra` 云端 review 使用独立缓存 |
| `/color` | 改当前提示栏颜色 | UI 状态,不影响 prompt cache |
| `/compact [instructions]` | 先发摘要请求读旧缓存,再用短摘要替换历史 | 摘要后下一轮重建短历史缓存;自然断点再用 |
| `/config [key=value]` | 多数配置热加载;`model`、`outputStyle`、thinking 等需分情况 | 改 output style 当前会话通常不生效也不立刻失效;改模型会 miss |
| `/context [all]` | 查看上下文占用 | 只读观测,不改变 prompt 前缀 |
| `/copy [N]` | 复制回复或代码块 | 本地操作,不调用模型 |
| `/cost` / `/stats` / `/usage` | 查看用量、限制和活动统计 | 不改变 prompt;用于观察 cache read/write 是否健康 |
| `/dataviz [request]` | bundled skill,图表和 dashboard 设计指导 | skill 指令追加到会话;不改 system prompt |
| `/debug [description]` | 打开调试日志并帮助排查 | 开启日志本身不改 prompt;让 Claude 分析日志会追加内容 |
| `/deep-research <question>` | bundled workflow,并行搜索和交叉验证来源 | workflow 子任务各自缓存;主会话只接收结果摘要 |
| `/diff` | 查看当前 diff | 可能读取 git diff 并追加到历史;diff 很大时会增加后续 token |
| `/doctor` | 诊断配置和登录 | 多数为本地检查;让 Claude 解释结果才进入上下文 |
| `/export` | 导出当前会话 | 本地操作,不影响缓存 |
| `/fast` | 开启 fast mode 的第一轮会因 header 和可能模型切换 miss | 官方说明 v2.1.86+ 后续开关/限速 fallback 不再反复破坏同一会话缓存 |
| `/feedback` | 提交反馈 | 不作为成本优化工具,通常不影响主模型缓存 |
| `/fork` | 把当前上下文分派给后台子任务 | 子任务继承父前缀,TTL 内更容易读到父缓存 |
| `/goal` | 设置持续完成条件 | 设置目标本身是会话状态;后续自动推进每轮照常追加并刷新 TTL |
| `/hooks` | 查看 hooks 配置和运行状态 | 观测命令;修改 hooks 后何时影响取决于 settings 热加载和下一次触发 |
| 请求 Claude spawn teammates | Agent Teams 会启动多个独立 Claude Code 实例 | 每个 teammate 有自己的上下文和缓存;token 近似随 active teammate 数量增加 |
| `/init` | 生成或改进 CLAUDE.md | 写文件不 retroactive;当前会话通常继续用启动时读到的 CLAUDE.md |
| `/loop` | 设置循环检查或定时提示 | 每次触发都是新一轮请求;间隔超过 5m 时 5m TTL 可能冷,1h 更稳 |
| `/mcp` | 查看、认证、管理 MCP server | server 连接/断开可能影响工具定义;tool search/deferred tools 更缓存友好 |
| `/memory` | 编辑记忆文件 | 根级 CLAUDE.md 类内容当前会话通常不立即生效;后续 `/clear` 或重启加载 |
| `/model` | 切模型 | 下一轮全量 miss;先定模型再做长任务 |
| `/permissions` | 管理 allow/ask/deny | scoped allow/ask 通常不改工具定义;deny 整个工具会让 system prompt 层变化 |
| `/plan` | 进入计划模式 | 普通 plan mode 追加状态;若模型是 `opusplan`,进出 plan 等同模型切换 |
| `/plugin list` | 查看插件 | 不调用模型 |
| `/recap` | 生成展示用摘要,不替换历史 | 缓存友好,但不释放上下文 |
| `/reload-plugins` | 应用插件变更 | skills/hooks/agents/themes 多数追加;插件带 MCP 时按 MCP 工具规则处理 |
| `/rename <name>` | 给会话命名 | 元数据,不影响 prompt cache |
| `/resume` | 从历史恢复 | 版本、模型、effort 未变且 TTL 未过期时可命中;长时间后第一轮较贵 |
| `/rewind` | 回退对话和文件 checkpoint | 回到旧前缀,通常比 `/compact` 更容易读旧缓存 |
| `/schedule` | 设置一次性或周期性任务 | 计划触发的每轮请求按间隔命中;超过 5m 的周期更适合 1h TTL |
| `/security-review` | 更深安全审查 | 多 agent/skill 类工作会追加大量上下文;子任务独立缓存 |
| `/setup-bedrock` / `/setup-vertex` | provider 配置向导 | 配置后重启或切 provider 会改变请求路径和缓存位置 |
| `/simplify [target]` | cleanup-only review 并可应用修复 | 类似 `/code-review`,可能追加 diff 和检查结果 |
| `/skills` | 列出、过滤、切换 skill 可见性 | 列表操作不改前缀;调用 skill 才作为消息追加 |
| `/status` | 查看状态页 | 只读观测 |
| `/statusline` | 配置状态栏脚本 | 状态栏刷新本地运行,不调用模型 |
| `/stop` | 停止当前后台 session | 停止不影响其他会话缓存 |
| `/tasks` / `/bashes` | 查看后台任务 | 本地/会话管理,不改模型前缀 |
| `/team-onboarding` | 从近期使用历史生成团队上手文档 | 会读取本地历史并追加分析结果,内容可能较长 |
| `/teleport` / `/tp` | 把 web session 拉到本地终端 | web/cloud session 的历史进入本地后继续,缓存位置和 provider 可能变化 |
| `/terminal-setup` | 配置终端快捷键 | 本地配置,不影响模型 |
| `/theme` | 终端主题 | UI 配置,不影响模型 |
| `/tui [default\|fullscreen]` | 切换终端 renderer | UI renderer,不影响 prompt |
| `/ultraplan <prompt>` | 云端深度计划 | 云端 session 独立缓存,本地接收计划结果 |
| `/ultrareview [PR]` | 云端深度审查,现推荐 `/code-review ultra` | 云端多 agent 独立缓存 |
| `/usage-credits` | 配置超出计划后的 credits | 若进入 usage credits,Claude subscription 可能从 1h TTL 降回 5m TTL |
| `/verify` | bundled skill,构建、运行并观察应用 | 工具输出可能很长;验证过程本身按普通会话追加 |
| `/voice` | 语音输入 | 转录依赖 claude.ai 身份;最终文本进入会话后按普通消息处理 |
| `/web-setup` | 连接 GitHub 到 Claude Code on the web | 配置命令,云端 session 独立缓存 |
| `/workflows` | 查看动态 workflow 进度 | 管理界面;workflow 子任务各自缓存 |
| Channel 事件推入 | MCP channel 把外部事件追加到运行中 session | 短间隔事件可刷新该 session TTL;长日志会抬高后续输入成本 |

## 按环境显示命令的缓存影响

这些命令常见于官方账号、Desktop、Web、IDE、GitHub/Slack 或特定 provider 环境。它们大多不是“问模型一次”的命令,但会通过账号、工具集合、provider 或后续 session 形状间接影响缓存。

| 命令 | 缓存影响 | 5m / 1h 解释 |
| --- | --- | --- |
| `/help` | 读取当前命令帮助,通常不改 prompt 前缀 | 用它确认命令是否存在,不会因为查看帮助破坏 5m/1h |
| `/login` | 认证流程本身通常不进主 prompt | 登录后 provider、账号能力或工具集合可能变化,下一次新会话要重新观察 |
| `/logout` | 清掉账号状态,后续官方能力会变化 | 不直接消耗 prompt cache,但后续会话的身份和工具边界会变 |
| `/ide` | IDE 连接状态管理 | 不直接改模型缓存;IDE 注入的文件/诊断进入历史后才增加上下文 |
| `/desktop`, `/app` | 会话交给 Desktop surface | surface、provider 或 session 存储可能变化,按新的会话边界看缓存 |
| `/mobile`, `/qr` | 生成移动端连接入口 | 本身不调用主模型;移动端接续后的消息按所接 session 的 TTL 计算 |
| `/remote-env` | 改后续 cloud agent 默认环境 | 不改当前本地前缀,但未来 cloud session 会以新环境重建缓存 |
| `/install-github-app` | OAuth/安装流程,通常不走主模型 | GitHub App、Actions、secret 配置完成后,云端自动化有独立缓存 |
| `/install-slack-app` | OAuth/安装流程,通常不走主模型 | Slack 触发的任务按 Slack/云端 session 独立计缓存 |
| `/design-login` | 设计系统授权,不直接改主 prompt | 授权后 `/design-sync` 才会引入大量组件和工具输出 |
| `/design-sync [hint]` | bundled skill 和上传工具流可能很长 | 首次同步会读大量 React 组件;稳定后再同步更容易复用相同前缀 |
| `/powerup` | 教程内容,通常独立于生产任务 | 不建议在长生产会话中穿插,避免把教程内容塞进上下文 |
| `/fewer-permission-prompts` | 读取历史并写权限 allowlist | 下一轮可能因权限可用性变化而改变工具使用路径,先观察一次成本 |
| `/focus` | UI 视图开关 | 不影响 prompt cache |
| `/scroll-speed` | fullscreen 滚动设置 | 不影响 prompt cache |
| `/keybindings` | 键盘绑定查看/配置 | 不影响模型缓存;配置后输入行为可能改变 |
| `/exit` | 退出界面或脱离后台 session | 停止交互不会刷新 TTL,回来时看间隔是否超过 5m/1h |
| `/run` | 启动、观察、驱动应用的 tool flow | 日志、截图和错误输出会抬高后续 token;让 recipe 保持稳定可提高命中 |
| `/run-skill-generator` | 写入项目运行 skill | skill 变更后 `/reload-skills` 或新会话会改变可加载上下文 |
| `/sandbox` | 改 sandbox/权限边界 | 工具可用性和执行结果可能变化,切换后的第一轮按新边界观察 |
| `/release-notes` | 查看版本说明 | 本身不影响主缓存;用于判断升级后为什么首轮 miss |
| `/reload-skills` | 重新加载 skills | skill 描述和可见性变化会影响后续 skill 调用,必要时自然断点再 reload |
| `/remote-control` | 配对 claude.ai 或 Claude app 控制本地 session | 远程消息进入同一 session 历史;自定义 gateway credential 下可能不可用 |
| `/review` | 对 GitHub PR 做只读审查 | PR 数据和评论进入云端/本地 review 流程,缓存按对应 session 计算 |
| `/insights` | 分析会话使用/摩擦 | 可能读取历史并输出较长报告,建议放在任务结束后 |
| `/heapdump` | 本地诊断 heap snapshot | 不影响主模型缓存,除非让 Claude 分析 snapshot 或日志 |
| `/privacy-settings` | 账号设置界面 | 不影响 prompt cache |
| `/passes` | 账号额度入口 | 不影响当前 prompt,但额度策略会影响后续可用模型和 provider 路径 |
| `/pr-comments` | PR 评论入口 | 读取评论后会把相关上下文带入任务,大 PR 先筛选目标 |
| `/setup-bedrock`, `/setup-vertex` | provider 配置向导 | 切 provider 后缓存位置和可用 beta/tool 字段可能变化,下一轮通常重新建 |
| `/team-onboarding` | 读取近期使用历史生成文档 | 输出可能很长,适合任务收尾;不要塞进正在优化缓存的长会话中 |
| `/upgrade` | 打开升级入口或计划升级页面 | 账号/计划操作本身不改 prompt;升级后 TTL、模型和额度策略可能变化 |
| `/stickers`, `/radio` | 非核心账号/娱乐入口 | 不作为开发缓存信号 |
| `/vim` | 已移除 | 不涉及缓存;用 `/config` 的 Editor mode |

## Provider 与网关提醒

| 现象 | 解释 |
| --- | --- |
| Passion8 下 cache 字段总是 0 | 可能是前缀太短、模型/effort 变动、MCP 工具 upfront、网关未透传缓存字段 |
| `/model` picker 看不到网关模型 | 需要网关支持 `/v1/models`,并设置 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` |
| MCP 一连上就 miss | 自定义 `ANTHROPIC_BASE_URL` 下如果 tool search 不可用,工具定义可能在 system prompt 前缀里 |
| Remote Control 不可用 | 官方说明 Remote Control 依赖 claude.ai 身份,并且在 gateway credential 或非 Anthropic base URL 下可能禁用 |
| fast mode 打开后第一轮很贵 | header 和可能的 Opus 切换进入 cache key,应该在长会话一开始决定 |

如果遇到 429、529、timeout、request too large 或模型不可用,先看 [错误参考](https://docs.passion8.cc/docs/claude-code/error-reference),尽量在不切模型、不改 effort 的前提下重试,这样更可能保留已有 cache key。

5 分钟和 1 小时 TTL 只描述 prompt 前缀缓存窗口,不是本地 transcript、网关日志或服务端数据保留周期。数据边界见 [数据使用与隐私](https://docs.passion8.cc/docs/claude-code/data-usage)。

## 官方参考

- [Commands](https://code.claude.com/docs/en/commands.md)
- [CLI reference](https://code.claude.com/docs/en/cli-reference.md)
- [How Claude Code uses prompt caching](https://code.claude.com/docs/en/prompt-caching.md)
- [Model configuration](https://code.claude.com/docs/en/model-config.md)
- [Fast mode](https://code.claude.com/docs/en/fast-mode.md)
- [Agent view](https://code.claude.com/docs/en/agent-view.md)