SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Claude Code 输出样式详解:内置样式与自定义方法

Claude Code 输出样式会修改系统提示词,影响每条回复。了解内置样式如何改变会话记录,以及 v2.1.251 的切换生效规则和自定义方法。

Claude Code 的输出风格是什么

Claude Code 的输出风格是一组指令块,Claude Code 会在每次请求时将其附加到发送给 Claude 的内容中。它会改变 Claude 回答你的方式:包括它所扮演的角色以及输出内容的格式。它不会向 Claude 提供任何关于你代码库的信息,也无法赋予 Claude 执行任何操作的权限。

Claude Code 内置了 5 种风格。你的选择保存在一个设置键 outputStyle 中。在 Claude Code v2.1.251 或更高版本中,你在会话期间切换的风格会从下一条消息开始生效。从 v2.1.73 到 v2.1.251 版本,切换操作会被保存,但在你执行 /clear 清除会话前都不会生效;这一事实解释了你至今仍能在关于此功能的旧指南中发现的大多数困惑。

在 VPS 上,这不仅仅是视觉偏好问题。会话记录是你通过 SSH(安全外壳协议)链接阅读的内容,通常是在 tmux 窗口内,因此 Claude 叙述的每一行都需要你等待,并且会占用固定大小的回滚缓冲区。

outputStyle 设置的存储位置

从 /config 菜单的 Output style 中选择一种样式。Claude Code 会将您的选择写入当前项目中的 .claude/settings.local.json。

/output-style 命令可通过提示词执行相同的操作。运行 /output-style concise 进行切换,或直接运行 /output-style 查看当前样式。该命令会将设置保存至同一个 .claude/settings.local.json 文件,不区分大小写,且支持非交互模式。此处描述的命令自 Claude Code v2.1.269 版本引入。v2.0.30 版本中曾存在一个旧的 /output-style 命令,该命令在 v2.1.73 版本中被弃用,转而使用 /config。因此,处于这两个版本之间的构建版本可能与本页描述的行为不符。在参考任何指南(包括本文)之前,请先检查您当前运行的版本。本页提及的版本信息已于 2026 年 10 月核实。

claude --version

您也可以手动设置该键值。共有四个设置文件可以存储此配置,作用域较窄的文件优先级高于较宽的文件。

  • ~/.claude/settings.json 是您的用户配置文件,适用于该机器上的所有项目。
  • .claude/settings.json 是项目配置文件。它会被提交到 git,因此适用于所有克隆该仓库的用户。
  • .claude/settings.local.json 是本地项目配置文件。它不会被提交,且优先级高于上述两个文件。/config 菜单和 /output-style 命令写入的正是此文件。
  • 由 IT 团队通过系统路径(例如 Linux 上的 /etc/claude-code/)部署的托管设置,其优先级最高。

该键的值为样式名称:

{
  "outputStyle": "Concise"
}

该值区分大小写。内置名称应写为 Proactive、Concise、Explanatory 和 Learning。如果值与样式名称不完全匹配(例如 concise),系统将静默使用 Default 样式。

若仅需在单次会话中生效,可在命令行中传递相同的键。--settings 标志接受路径或内联 JSON 字符串,其值会覆盖本次运行中用户、项目及本地设置文件中的对应键值。托管设置的优先级依然最高:

claude --settings '{"outputStyle": "Concise"}'

文档列出了四种选择样式的方法,其中仅两种有最低版本要求。终端中的 /config 菜单无版本限制。当前形式的 /output-style 命令需要 v2.1.269 版本,而 VS Code 扩展中的 Output styles 菜单需要 v2.1.257 版本。在桌面应用中,您需要在设置文件中配置 outputStyle 字段。outputStyle 键本身没有最低版本限制,因此它是最可靠的选择。当指南中的截图与您实际看到的不符时,请直接设置该键,并使用 /status 进行确认,该命令会列出当前生效的设置来源。

新的输出样式何时生效

在 Claude Code v2.1.251 或更高版本中,您可通过命令、菜单或设置文件在会话中途切换样式。新样式会从您的下一条消息开始生效。您无需清除上下文。从 v2.1.73 到 v2.1.251,正在运行的会话会继续使用启动时的样式,新样式只会在下一次 /clear 或下次启动时加载。

在终端中,Claude Code 启动时会读取样式文件。因此,如果您在会话运行期间创建或编辑自定义样式文件,请先重启 Claude Code,再选择该样式。在 VS Code v2.1.261 或更高版本中,Output styles 菜单中的 Build a custom style 向导会创建文件,并立即列出新样式。在该旧版本范围内构建,或因编辑终端样式文件而重启后,运行以下两个命令即可清理当前状态,然后查看已加载的内容:

/clear
/context

/context 会按类别列出当前占用上下文窗口的内容,包括系统提示词。在每种样式下分别于新会话中运行该命令,系统提示词所在行就是比较的输入项。它也是确认自定义样式是否加载的最快方法。有关上下文窗口在更大范围内如何被占用,请参阅 长期 Claude Code 会话中的上下文如何逐渐占满。

缓存解释了样式切换的工作方式。API 会从提示词缓存中提供重复请求的结果,缓存匹配每个请求的开头,而系统提示词正位于开头。在会话中途重写系统提示词会使其后的所有内容失效,因此下一轮请求必须将完整历史记录作为新输入重新处理。从 v2.1.73 到 v2.1.251 的构建版本通过在会话启动时固定样式来避免这一成本。当前构建版本改为将新样式的指令作为会话中的一条消息发送,因此切换后的请求仍会从缓存读取系统提示词和之前的会话内容。无论采用哪种方式,切换样式的成本都很低。

内置输出样式对会话内容的影响

  • Default 是 Claude Code 的标准系统提示词,面向软件工程工作编写。
  • Concise 会先给出结果。它省略前置说明和逐步操作叙述,并在您要求详细说明前保持回答简短。背后的工程工作不变。它不会缩短错误报告或安全警告;执行破坏性操作前,仍会完整询问确认。此样式需要 Claude Code v2.1.237 或更高版本。
  • Explanatory 会在任务步骤之间添加教学性的“Insights”,说明为何采用某种实现方式,以及您的代码库已在使用哪种模式。会话内容会因此有意变长。
  • Learning 更进一步。Claude 会分享这些见解,然后要求您自行编写少量代码,并在文件中使用 TODO(human) 注释标记每个位置。
  • Proactive 会让 Claude 直接执行操作,而不是先询问。对于常规决策,它会做出合理假设,而不是停下来等待确认。

请仔细阅读最后一项,因为人们最容易误解它。Proactive 是系统提示词中的指导。它会改变 Claude 尝试执行的操作。实际哪些操作可以在不询问您的情况下运行,仍由权限模式决定。对于无人值守运行的服务器,这才是需要关注的设置。相关内容请参阅 自动模式和 Claude Code 的权限模式。

输出样式与 CLAUDE.md、hook 和子代理的区别

这些机制看起来都是在告诉 Claude 应如何运行,但它们作用于不同层级。

  • 输出样式属于 Claude Code 随每个请求发送的指令。它适用于主对话中的每个响应。
  • CLAUDE.md 会在系统提示之后作为用户消息添加。项目约定和代码库事实应写在这里。
  • --append-system-prompt 会为单次调用向系统提示追加文本,但不会删除任何内容。它是输出样式的一次性版本。
  • hook 是 Claude Code 在事件触发时自行运行的 shell 命令。它由宿主程序强制执行,因此无论 Claude 是否会主动选择执行,都会运行。请参阅 Claude Code hook 能做什么以及不能做什么。
  • 子代理使用自己的系统提示和自己的工具集运行。

一个简短的测试可以帮助你在前两者之间做出选择。项目事实应写入 CLAUDE.md,因为 Claude 需要了解这些事实。措辞应写入输出样式,因为它决定答案的表达方式。任何无论模型如何决定都必须每次发生的操作,都应使用 hook。每种机制所处的层级取决于运行模型的程序,而不是模型本身。因此,样式只能产生影响,而 hook 可以强制执行。

输出样式只适用于主对话。子代理不会继承你的样式,因为它会使用自己的系统提示启动独立对话。当前对话的分支是例外,因为分支会完全继承父对话的系统提示。如果子代理的写法不符合你的要求,请编辑该代理的文件,而不是修改你的样式。同一台主机上的另一个 Claude Code 会话也遵循相同的边界:它启动时会自行读取设置文件。因此,当你将工作交给旁边运行的另一个会话时,它返回的回复会采用该会话加载的样式,而不是你的样式。

如何编写自己的输出样式

自定义输出样式是一个带有 frontmatter 的 Markdown 文件。将它保存到主目录后,可在每个项目中使用;将它保存到仓库中,则可与代码一同维护。用户目录为 ~/.claude/output-styles/,项目目录为 .claude/output-styles/。

mkdir -p ~/.claude/output-styles
cat > ~/.claude/output-styles/terse-ops.md <<'EOF'
---
name: Terse ops
description: Command first, explanation after, for SSH sessions
keep-coding-instructions: true
---

Lead with the command or the file change. Put the explanation after it, in two sentences or fewer.

Do not narrate what you are about to do. Report what you did.

When a command can fail, print the one check that proves it worked and say what a healthy result looks like.
EOF

启动会话并打开 /config。您的样式会显示在 Output style 列表中,并带有您编写的描述。如果样式未显示,说明文件未被读取:请检查路径;如果保存文件时会话已经在运行,请重启 Claude Code。如果样式显示为文件名且没有描述,说明 frontmatter 解析失败,claude --debug 会显示解析错误。除非 frontmatter 设置了 name,否则文件名会成为样式名称。因此,这个样式称为 Terse ops,而不是 terse-ops。

选择该样式,或将此键设置为完全相同的名称,并保持大小写一致:

{
  "outputStyle": "Terse ops"
}

有一个字段决定您的文件是调整项还是替代项。keep-coding-instructions 默认值为 false,这表示自定义样式会移除 Claude Code 内置的软件工程指令,仅根据您的文本运行。这些内置指令用于告知 Claude 如何确定变更范围以及如何验证工作结果。对于写作助手或数据分析师,可以省略此字段,因为这些任务不涉及上述内容。对于任何仍会修改代码的场景,应将其设置为 true;否则,您会发现原本谨慎的工程师突然不再检查自己的工作。只有 Claude Code 的完整系统提示包含该部分,因此在较短的系统提示下,此字段不起作用。将 CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT 环境变量设置为 0,可在任何模型上选择完整提示。如果您真正需要的不是改变语气,而是更严格地定义任务应投入多少工作量,那么应将其放在工程指令中,而不是样式文件中:Ponytail 技能就是一个完整示例,其中只有一条规则,用于推动代理采用能够完成任务的最小变更。

description 是 /config 选择器在名称旁显示的行。请针对 6 个月后您在两个自定义样式之间进行选择的场景来编写它。

为什么简洁风格在 SSH 中有所不同

在 VPS 上,您需要通过本地终端没有的多层环境读取终端记录,而每一层都会让冗长输出带来额外开销。

第一项是回滚缓冲区。在 tmux 中,每个窗格会保留固定行数,由 history-limit 设置,默认值为 2000。带有解释的记录会更快填满缓冲区,因此会话早期内容会更早被移出,您想回滚查看的输出也会消失。如果需要更多空间,可以提高该值:

echo 'set -g history-limit 20000' >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

之后创建的窗格各自会保留 20000 行,但每个窗格的内存开销也会增加。在 tmux 3.7 或更高版本中,修改 history-limit 还会更新已经打开的窗格;旧版本只会将其应用于新窗格。如果您还在构建会话布局,请参阅 在 VPS 的 tmux 中运行 Claude Code。

第二项是延迟。响应会在生成过程中流式传输到您的终端。在往返时间较高的连接上,冗长的开场白会占用您的等待时间,您只能看着文字逐步显示,直到答案出现。

第三项是输出 token。每一行解释性文字都会计入输出费用。Explanatory 和 Learning 的设计目标就是更长。Concise 的设计目标就是更短,因为它会指示 Claude 默认保持简短回复。

不要相信任何人提供的百分比,包括本页面提供的百分比。差异大小取决于您的提示、所使用的模型以及您要求完成的工作,因此请在使用前后自行测量。在两个新的会话中执行同一个真实任务,一个使用 Default,另一个使用 Concise,然后进行比较。状态栏是最简单的计量方式,因为 Claude Code 会将一个 JSON 对象传递到您脚本的 stdin,其中已经包含风格名称、最新回复的输出 token 数以及会话的累计费用估算:

cat > ~/.claude/statusline.sh <<'EOF'
#!/bin/bash
input=$(cat)
style=$(echo "$input" | jq -r '.output_style.name // "default"')
out=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0')
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
echo "style=$style out=$out cost=$cost"
EOF
chmod +x ~/.claude/statusline.sh

将 statusLine 设置指向该脚本:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

现在,会话底部的状态栏会显示当前风格、最新回复的大小以及截至目前的会话预计费用。out 仅涵盖最新回复,因此可以显示每个答案的长度。cost 会累计数值,因此每次运行结束时的数值就是前后对比结果。清除前先读取该数值,因为 /clear 开始新会话时,费用会重置为 $0;同时请将其视为估算值,而不是实际账单。该脚本需要使用命令行 JSON 解析器 jq,因此请先使用 sudo apt install -y jq 安装它。如果状态栏保持空白,请手动运行脚本并向其管道传入一些 JSON,因为以非零状态退出的状态栏脚本不会打印任何内容,也不会报告任何内容。自定义 Claude Code 状态栏列出了该对象中的其余字段。如果您关注的是计费而不是会话,请阅读Claude Code 的 token 实际流向和跟踪 Claude Code 支出的工具。

如何检查实际加载了哪个输出样式

请使用以下检查方法,不要凭猜测判断。

  • /status 列出当前会话生效的设置来源,包括是否启用了组织提供的托管设置。
  • /context 在上下文窗口分类统计中,将已加载的系统提示词显示为一个类别。
  • claude doctor 在不启动会话的情况下从 shell 运行该命令,可输出安装和设置诊断信息,并报告无效的设置文件。

样式未生效时,原因几乎总是以下两种之一。第一种是时机问题:在 v2.1.73 到 v2.1.251 的构建版本中,会话中途的切换要等到 /clear 才会生效;在终端中,会话中途创建或编辑的样式文件则要等到重启后才会生效。第二种是优先级问题:.claude/settings.local.json 会覆盖 .claude/settings.json,二者都会覆盖 ~/.claude/settings.json。由于 /config 选择器和 /output-style 命令会写入本地文件,团队提交到 .claude/settings.json 中的样式会在曾经使用过其中任一项的机器上被静默覆盖。/status 会告诉您加载了哪些文件,但不会告诉您哪个文件提供了关键设置。因此,请打开它列出的每个文件,并查找 outputStyle。

JSON 语法错误也会产生相同症状,但修复方法不同。claude doctor 会指出无法解析的文件名。在查找更复杂的原因前,值得先运行该命令。大小写错误的值(例如 explanatory)仍是有效的 JSON,但会让您得到 Default 样式,因此也要检查大小写。

FAQ

为什么 /output-style 命令停止工作了?

在当前构建版本中,该命令并未停止工作。/output-style 会列出样式,/output-style concise 会切换到指定样式。该命令在历史版本中存在一段变更期:v2.1.73 弃用了它,改用 /config;v2.1.269 又加入了当前的 /output-style [name] 形式。因此,在这两个版本之间的构建版本中,它可能无法按本文所述工作。运行 claude --version 查看当前版本。在任何构建版本中,您都可以在 /config 的 Output style 下选择样式,或在设置文件中设置 outputStyle 键。文档没有为该键规定最低版本,因此直接设置该键是值得记录在您自己的笔记中的方法。

我更改了输出样式,但什么都没有发生。为什么?

先检查版本。在 Claude Code v2.1.251 或更高版本中,会话中途切换的样式会从您的下一条消息开始生效。从 v2.1.73 到 v2.1.251,变更会被保存,但只有在 /clear 或启动新会话后才会生效。在终端中,会话期间创建或编辑的自定义样式文件需要重启,因为 Claude Code 会在启动时读取样式文件。如果仍未生效,请确认该值与样式名称完全一致,包括大小写。然后运行 /status 查看加载了哪些设置文件,因为 .claude/settings.local.json 会覆盖 .claude/settings.json,二者都会覆盖 ~/.claude/settings.json。

Concise 输出样式能节省费用吗?

它会按预期减少输出 token,因为该样式会指示 Claude 默认保持简短。具体节省量取决于您的提示词和模型,因此应将任何公开的百分比视为他人工作中的测量结果。请测量您自己的情况:在每种样式下分别于新会话中运行 /context,以获取输入侧数据;然后在每种样式下执行相同任务,比较输出 token 数量和估算费用。Concise 不会缩短错误报告或安全警告,因此您最需要阅读的部分仍会完整保留。

输出样式会改变我的子代理的写作方式吗?

不会。输出样式只适用于主会话,因为子代理会使用自己的系统提示词和工具集启动独立会话。当前会话的分支是例外,因为分支会完全继承父会话的系统提示词。若要改变子代理的响应方式,请编辑该代理自己的文件。

输出样式能让 Claude 无需询问就运行命令吗?

不能。输出样式是系统提示词中的文本,因此只能影响 Claude 尝试执行的操作。Proactive 样式会让 Claude 在例行决策中默认采取行动,而不是停下来询问,但它仍无法批准命令。决定哪些操作可在无需提示的情况下运行的是权限模式。让会话在服务器上持续运行前,请检查该设置。

这篇文章对您有帮助吗?