标签页配置

标签页配置让您可以定义可重用的标签页设置——包括目录、启动命令、窗格布局、Shell 和主题——全部通过一个简单的 TOML 文件实现。从 + 菜单中选择一个标签页配置，即可一键打开配置完善的标签页。

标签页配置的工作原理

每个标签页配置都是一个存储在 Warp 的 tab_configs 目录中的 .toml 文件。每个文件定义了一个标签页布局，包含可选的窗格拆分、启动命令和参数化输入。标签页配置会显示在 + 菜单中，与您现有的标签页并列，因此您可以立即启动一个预配置的工作区。

tab_configs 目录在不同平台上的位置不同

macOS

~/.warp/tab_configs/ (稳定版) 或 ~/.warp-preview/tab_configs/ (预览版)。

Windows

%APPDATA%\warp\Warp\data\tab_configs\ (稳定版) 或 %APPDATA%\warp\WarpPreview\data\tab_configs\ (预览版)。

Linux

${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/tab_configs/ (稳定版) 或 ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal-preview/tab_configs/ (预览版)。

有关 Warp 文件位置的完整列表，请参阅 文件和文件夹位置。

创建标签页配置

通过 UI

1. 点击标签栏中的 + 按钮以打开新标签页菜单。
2. 点击 + New tab config (新建标签页配置)。Warp 会在 tab_configs 目录中创建一个新的 .toml 文件并将其打开以供编辑。

手动

1. 在上述 tab_configs 目录中创建一个新的 .toml 文件。文件名请使用 snake_case (例如 dev_server.toml)。
2. 使用下方的架构定义标签页布局，然后保存文件。新的配置会自动出现在 + 菜单中。

将现有标签页保存为配置

您还可以将标签页的当前状态捕获为可重用的标签页配置，而无需编写 TOML。右键点击 垂直标签页 面板或水平标签栏中的任何标签页以打开上下文菜单，然后点击 Save as new config (保存为新配置)。Warp 将根据标签页的布局、命令和目录生成一个 .toml 文件，并将其添加到 + 菜单中。

保存标签页配置。

管理标签页配置

已保存的标签页配置会出现在 + 菜单中以便快速访问。当您将鼠标悬停在菜单中的标签页配置上时，旁边会出现一个 边栏面板，其中包含以下选项：

• Edit config (编辑配置) — 打开底层的 .toml 文件进行手动编辑。编辑器还显示一个页脚，用于调用 update tab config (更新标签页配置) 技能，这样您就可以用自然语言描述更改，并让 Warp 的 AI 代理应用它们。
• Remove (移除) — 从 + 菜单中移除该配置。
• Make default (设为默认) — 将此配置指定为新建标签页时的默认 Cmd T 操作。

带有边栏选项的标签页配置菜单。

从 URL 打开标签页配置

您可以直接通过 Warp 的 URI 方案 打开已保存的标签页配置。这对于浏览器书签、脚本以及 Raycast 或 Alfred 等启动器非常有用，它们无需经过 + 菜单即可直接跳转到配置好的窗格布局。

默认情况下，标签页配置会在活动窗口中作为新标签页打开。传入 ?new_window=true (或者在没有 Warp 窗口打开时调用) 即可在新建窗口中打开。

# Open my_tab.toml as a new tab in the focused window
open "warp://tab_config/my_tab"

# Open it in a brand-new window
open "warp://tab_config/my_tab?new_window=true"

<name> 与 .toml 的文件名（不含后缀）进行不区分大小写的匹配，因此 warp://tab_config/my_tab 和 warp://tab_config/my_tab.toml 都会解析为 my_tab.toml。匹配使用的是文件名而不是文件内部的 name 字段，因为多个标签页配置可以共享同一个显示名称。

如果标签页配置声明了 [params.*] 条目，参数模态框会像从 + 菜单启动时一样打开。引用 {{autogenerated_branch_name}} 的工作树风格配置在每次打开时仍会生成一个新的分支名称。

注意

在 Warp 预览版中，请改用 warppreview://tab_config/<name>。

使用技能管理标签页配置

Warp 内置了技能，可以通过自然语言创建和修改标签页配置

• Create Tab Config (创建标签页配置) — 根据描述生成新的标签页配置（例如，“创建一个 2x2 网格，其中一个窗格运行我的开发服务器”）。
• Update Tab Config (更新标签页配置) — 通过描述您想要的更改来修改现有的标签页配置。

要使用这些技能，请在 Agent 模式下输入 /skills 并选择标签页配置技能，或者使用编辑标签页配置文件时出现的页脚。

标签页配置 TOML 架构

顶级字段

• name (必需，字符串) — 在 + 菜单中显示的显示名称。
• title (可选，字符串) — 自定义标签页标题。支持 {{param}} 模板变量。
• color (可选，字符串) — 标签页颜色。可选值："black"、"red"、"green"、"yellow"、"blue"、"magenta"、"cyan"、"white"。实际颜色值源自您的 Warp 主题。

窗格列表

所有窗格都在一个扁平的 [[panes]] 数组中定义。第一个条目是窗格树的根节点。每个条目要么是 拆分节点 (分支)，要么是 叶子节点。

叶子节点字段

• id (必需，字符串) — 此窗格的唯一标识符。使用描述性名称，如 "editor" 或 "server"。
• type (必需，字符串) — "terminal" (标准 Shell)、"agent" (在 Agent 模式下打开) 或 "cloud" (云模式窗格，无本地 Shell)。
• directory (可选，字符串) — 初始工作目录。支持 ~ 扩展和 {{param}} 模板变量。
• commands (可选，字符串数组) — 标签页打开时按顺序运行的命令。
• shell (可选，字符串) — 用于此窗格的 Shell 可执行文件 (例如 "pwsh"、"zsh"、"bash"、"fish")。仅适用于 terminal 和 agent 窗格类型。如果省略或未安装指定的 Shell，则使用用户的默认 Shell。
• is_focused (可选，布尔值) — 最多在一个窗格上设置为 true，以使其获得初始焦点。

拆分节点字段

• id (必需，字符串) — 此拆分的唯一标识符。
• split (必需，字符串) — "horizontal" (子窗格从左到右排列) 或 "vertical" (子窗格从上到下排列)。
• children (必需，字符串数组) — 子窗格 id 值的有序列表。必须至少包含 2 个条目。顺序决定视觉布局顺序。

注意

拆分内的所有子窗格大小相等。没有弹性或比例值。

参数

参数允许用户在打开时通过模态提示填写值。使用 [params.<name>] 表声明它们，并在 directory、commands 和 title 中使用 {{name}} 语法引用它们。

每个参数包含

• type (可选，字符串) — "text" (默认，自由输入)、"branch" (Git 分支选择器) 或 "repo" (仓库选择器)。
• description (可选，字符串) — 填写 UI 中显示的标签。
• default (可选，字符串) — 默认值。

{{autogenerated_branch_name}} 是一个保留的模板变量。如果标签页配置引用了它，Warp 会在每次打开时生成一个唯一的工作树分支名称，而不是提示用户。

示例

单窗格

一个简单的配置，在项目目录中打开终端并启动开发服务器

name = "Dev Server"

[[panes]]
id = "main"
type = "terminal"
directory = "~/code/my-app"
commands = ["npm run dev"]

双窗格并排

一个编辑器和一个服务器并行运行，且编辑器获得焦点

name = "Editor + Server"
color = "green"

[[panes]]
id = "root"
split = "horizontal"
children = ["editor", "server"]

[[panes]]
id = "editor"
type = "terminal"
directory = "~/code/my-app"
commands = ["nvim ."]
is_focused = true

[[panes]]
id = "server"
type = "terminal"
directory = "~/code/my-app"
commands = ["npm run dev"]

跨 Shell 开发

一个并排打开两个窗格的配置，每个窗格使用不同的 Shell

name = "Cross Shell"
color = "cyan"

[[panes]]
id = "root"
split = "horizontal"
children = ["bash_pane", "pwsh_pane"]

[[panes]]
id = "bash_pane"
type = "terminal"
shell = "bash"
directory = "~/code/my-app"
is_focused = true

[[panes]]
id = "pwsh_pane"
type = "terminal"
shell = "pwsh"
directory = "~/code/my-app"

带参数的工作树

一个参数化配置，在打开时创建一个新的 Git 工作树

name = "New Worktree"
title = "{{branch_name}}"

[[panes]]
id = "main"
type = "terminal"
directory = "{{repo}}"
commands = [
  "git worktree add -b {{branch_name}} ../{{branch_name}} {{base_branch}}",
  "cd ../{{branch_name}}",
]

[params.repo]
type = "repo"
description = "Repository path"

[params.base_branch]
type = "branch"
description = "Base branch to branch from"

[params.branch_name]
type = "text"
description = "New branch name"
default = "my-feature"

快速工作树设置

您也可以直接从 + 菜单点击 New worktree config (新建工作树配置) 并选择工作树所属的仓库，来创建基于工作树的标签页配置。Warp 会自动生成标签页配置并保存以备将来使用。

相关页面

• 启动配置 (旧版) — 之前的会话配置格式。现有配置仍然有效，但建议新设置使用标签页配置。
• 标签页 — 标签页管理、键盘快捷键和行为设置
• 主题 — 自定义标签颜色设置使用的颜色
• 工作目录 — Warp 如何解析工作目录
• 第三方 CLI 代理 — 使用 "agent" 窗格类型在 Agent 模式下打开标签页
• Warp URI 方案 — 通过 warp://tab_config/<name> 深层链接打开标签页配置