跳到内容
PaneflowPaneflow

设置

了解 Paneflow 的 Settings 面板控制什么、写入 paneflow.json 的内容,以及哪些高级键仍然只属于配置文件。

Paneflow 的 Settings 面板是常用偏好的人工 UI。它不是完整的配置参考。用它调整你经常改的内容:editor、shell、theme、shortcuts、notifications、 terminal display、workspace templates、agent launchers、AI access 和 MCP setup。

TL;DR. 大多数 Settings 行会写入 paneflow.json,并在文件保存后热重载。 Plugins 不同:它会在受支持的 agent config 中安装或修复 Paneflow 的 MCP bridge。高级键仍然可以在 paneflow.json 中使用。

Settings map

Page控制内容写入位置生效方式
General新 terminal pane 的默认外部 editor 和默认 shell。external_editor, default_shell新启动时生效。正在运行的 terminal 保持当前进程。
AppearanceLight、Dark、System、theme preset、Comfortable density、Interface style、Workspace icon、Windows、macOS 和 Linux 上的 Background style、App icon,以及专用于 Windows、macOS 和 Linux 的 sidebar material controls。theme, comfortable_density, interface_style, workspace_icon, app_icon, windows_chrome_material, windows_terminal_material, macos_chrome_material, linux_chrome_material, linux_terminal_materialtheme、density、style、icon 和 material 更改会热重载。
Keyboard Shortcutsaction bindings 和重置为 defaults。shortcutsconfig 保存后重新加载。
Notifications等待中 agent 以及终端程序所发送通知的原生 OS notifications。agent_panel.notify_when_agent_waiting热重载。
Terminalcursor shape 和 color、font family、font size、font weight、line height、cell width、integrated glyphs、color emoji、minimum contrast、Windows 和 Linux terminal material。terminal.cursor_shape, terminal.cursor_color, font_family, font_size, font_weight, line_height, cell_width, terminal.integrated_glyphs, terminal.color_emoji, terminal.minimum_contrast, windows_terminal_material, linux_terminal_materialdisplay controls 会热重载。cursor shape 应用于下一个新 terminal。
Workspaces可复用 workspace templates,包含 panes、agents、shell commands、cwd、env 和 prompt prefill。commands[].workspacetemplates 通过与 paneflow up 相同的 workspace launch path 启动。
Spaces对工作区分组的空间:先是 Default,然后是每个空间及其名称、图片、颜色、环境变量、它所设置的配置目录中 Claude Code 和 Codex hooks 与 MCP 的状态,以及一个删除操作,确认后会把其工作区移到 Default。最多 9 个空间。spaces;图片写入 Paneflow home 中的 avatars/名称、图片和颜色会热重载。环境对更改之后打开的终端生效。
WorktreesPaneflow 创建的 worktree 的根目录、带保留上限的自动删除、带删除操作的受管 worktree 列表,以及删除前拍下的快照及其恢复和删除操作。worktrees.dir, worktrees.auto_remove, worktrees.keep_limit热重载。根目录对之后创建的 worktree 生效。
Agentslauncher 显示哪些 agents 及其已安装版本和 hook 状态、Claude Code 和 Codex 的 Paneflow hooks 开关、自定义 agent profiles、Claude Code full access、AI free access 和 injection fence。*_button_visible, agent_profiles, claude_code_bypass_permissions, ai_unrestricted, ai_injection_fence;Paneflow hooks 开关写入智能体自己的 hook 配置launcher 和 access 更改会热重载。
Plugins为 Claude Code、Codex、Gemini 和 opencode 安装或修复内置 paneflow-mcp bridge。agent config files,不是 paneflow.jsonPaneflow 更新后或 agent config 变更后重新运行。

界面风格

Settings > Appearance 在 theme preset 下方提供 Interface style。命令面板的 Interface style 提供相同的选项。它决定整个应用的布局和圆角风格,保存在 interface_style 中。

风格显示效果
Classic (默认)边到边铺满的窗口:sidebar、面板和 Changes 停靠面板延伸到窗口边缘,之间以细线分隔;顶部面板和停靠面板的标签页位于标题栏中、窗口控制按钮旁,该行的空白部分可用于拖动窗口。圆角为圆形,尺度紧凑:对话框和提示消息为 12 px,行、按钮和面板标签页为 8 px。Comfortable density 不起作用。
RoundedPaneflow 0.19 及更早版本的外观:面板卡片使用连续曲率圆角(squircle)和较大的圆角半径,浮在全宽标题栏下方。Comfortable density 只对此风格生效。

两种风格下,所有菜单和下拉选择弹出层都是 8 px 面板,行高 28 px,标签 14 px,快捷键 12 px。命令面板和 Clone repository 对话框在两种风格中外观相同。更改会立即应用到所有已打开的窗口。自 0.20.0 起,Paneflow 默认以 Classic 打开;要保留浮动的面板卡片,请选择 Rounded,或设置 "interface_style": "rounded"。

背景风格

在 Windows、macOS 和 Linux 上,Settings > Appearance 在 interface style 下方提供 Background style。命令面板的 Background style 提供相同的选项。它会一次性切换该平台的全部窗口 material。0.19 及更早版本中,该设置名为 Interface style;它保留原有的取值和键。

风格WindowsmacOSLinux
Themed (默认)windows_chrome_material 和 windows_terminal_material 设为 false:使用 theme 的纯色。macos_chrome_material 设为 false:sidebar 不透明。linux_chrome_material 和 linux_terminal_material 设为 false:窗口不透明。
Blended两者均设为 true:Mica 透过 sidebar 和终端显示。macos_chrome_material 设为 true:sidebar 后方显示原生 Sidebar material。两者均设为 true:桌面透过 sidebar 后方的半透明层显示,终端后方的半透明层更浓。

在 Linux 上,设置 "window_backdrop": "blurred" 后,Paneflow 会请求提供 ext-background-effect 或 KDE 模糊的 Wayland 合成器模糊半透明窗口后方的内容,并沿窗口的圆角进行模糊。在其他环境(包括 X11 和 GNOME)中,Paneflow 不请求模糊效果:合成器可能自行提供,例如 GNOME 上的 Blur my Shell 扩展。没有模糊时,壁纸会不经模糊地透过半透明层显示。

没有 background_style 键:Paneflow 根据这些开关推断风格。当它们不一致时 (例如手动只开启其中一个),该行显示 Custom。

工作区图标

Settings > Appearance 提供 Workspace icon,命令面板的 Workspace icon 提供相同的选项。它决定侧边栏中每个工作区前面的图标,保存在 workspace_icon 中。Default 保留 Paneflow 的线框文件夹。Standard 用展开箭头取代文件夹:工作区折叠时向右,展开时向下。Metal 是填充的玻璃文件夹,Windows 是黄色渐变文件夹, Windows 95 是 16 色像素文件夹,Pixel 是线框像素文件夹。每种风格都有关闭和打开两种图标,两种像素风格在 100% 或 200% 显示缩放下最清晰。

应用图标

Settings > Appearance 在 theme 卡片底部提供 App icon。它决定 Paneflow 为运行中的窗口显示的图标,保存在 app_icon 中。该行显示当前图标及其名称;点击即可展开包含所有图标的图库,选择一个即可立即应用。

图标显示效果
Glass (默认)安装时的图标:紫色底板上的三块玻璃面板。
Black黑色底板上,Paneflow 标志由米白色横条组成。
White白色底板上,同样的横条使用深色墨色。
Black solid黑色底板上,三块面板为米白色实心形状。
White solid白色底板上,同样的实心面板使用深色墨色。

后面还有 16 个插画图标。每个图标以另一种材质呈现同一标志。

图标app_icon显示效果
Aubergineaubergine深茄紫色底板上的淡紫色面板。
Paperpaper米白色纸质底板上的茄紫色墨色面板。
Midnight mattemidnight-matte哑光黑色底板上的深灰色面板。
Polarpolar冰白色底板上的蓝色和青色面板。
Melonmelon奶油色底板上的珊瑚色和橙色面板。
Honeydewhoneydew薄荷绿与青柠色底板上的深绿色面板。
Berryberry紫色与粉色底板上的梅子色面板。
Rainbowrainbow黑色底板上由六道复古条纹组成的面板。
Solarwavesolarwave深紫色底板上的铬色日落条带。
Neonneon深紫罗兰色底板上的青色和粉色霓虹轮廓。
Phosphorphosphor黑色屏幕底板上发光的绿色面板。
Holoholo彩虹镭射箔底板上的深色面板。
Amethystamethyst多切面紫色宝石上的淡紫色面板。
Blueprintblueprint蓝图底板上的浅蓝色面板。
Chipchip绿色电路板中芯片上的拉丝金属面板。
Nostalgianostalgia亮面蓝色底板上的铬白色面板。
平台显示位置生效时间
Windows任务栏按钮、Alt+Tab,以及你的用户配置中打开此 Paneflow 的快捷方式:固定到任务栏的快捷方式、桌面快捷方式和开始菜单条目。Alt+Tab 立即生效。任务栏按钮在下次登录或重启 Windows 资源管理器后生效。Paneflow 关闭时,快捷方式仍保留该图标。
macOSPaneflow 运行期间的 Dock 和应用切换器。立即生效。
Linux,X11窗口管理器和任务切换器读取的窗口图标。对更改之后打开的窗口生效;重启 Paneflow 可应用到所有窗口。
Linux,Wayland不显示:合成器从已安装的桌面条目读取图标。不生效。

在 Windows 上,固定的任务栏按钮显示的是其快捷方式的图标,而不是窗口的图标,因此 Paneflow 会让该快捷方式指向它写入 Paneflow home 中 icons/ 下的图标文件,并在每次启动时重新检查。Windows 会缓存任务栏按钮的图像,只有在重新加载任务栏时才会再次读取快捷方式,因此按钮会在下次登录或 Windows 资源管理器重启后改变。选择 Glass 会恢复快捷方式自身的图标。

全机安装的开始菜单快捷方式不属于你,不能修改。选择 Glass 以外的任何图标时,Paneflow 会将它复制到你自己的开始菜单文件夹中的相同位置(Windows 会优先使用该位置),并为该副本设置图标;选择 Glass 会删除该副本。如果在选中其他图标时卸载 Paneflow,该副本会保留下来:请从 %APPDATA%\Microsoft\Windows\Start Menu\Programs 中删除它。

在 macOS 和 Linux 上,已安装的启动器以及未运行的 Paneflow 的 Dock 图标仍为 Glass 图标。

终端对比度

当程序自行指定的文字颜色与背景过于接近时,Paneflow 会提高文字对比度。 Settings > Terminal 中的 Minimum contrast 控制此行为。命令面板的 Minimum contrast 提供相同的选项。

显示值terminal.minimum_contrast效果
Auto不设置此键所有主题均使用 APCA Lc 60,包括浅色和深色主题。
Off0不进行校正,保留程序请求的颜色。
45, 60, 75, 90对应数值显式指定 APCA Lc 目标。

大于 90 的值会限制为 90。负数或无效值会回退到 Auto。

只校正程序选择的颜色:truecolor 和调色板索引 16 到 255。主题自身的 16 种 ANSI 颜色、前景色和背景色保持不变。校正首先在保留色相的同时调整明度。如果必须大幅降低饱和度,则会向最接近的主题颜色调整。

修改会热重载到已打开的终端。要在所有终端中关闭校正,请在 paneflow.json 的 terminal 下设置 "minimum_contrast": 0。

空间

Spaces 页面的介绍旁有一个 New space 按钮,下方是一张先列出 Default 的卡片。Default 包含所有不属于任何空间的工作区,显示 Workspaces without a space 或其工作区数量,不能重命名或删除。之后每个空间占一行,显示其圆形图标、名称,以及工作区数量和变量数量;折叠的行还会标出 Agent setup failed 或其环境警告。点击一行即可展开。同一时间只展开一个空间。

字段作用
Name点击名称即可编辑,然后按 Enter 保存或按 Escape 取消;点击其他位置也会保存。名称必须为 1 到 32 个字符,不能是 Default,且不能与其他空间的名称重复(不区分大小写)。名称无效时,字段下方会显示原因,并且不会保存任何内容。
ImageUpload image 会打开文件选择器,点击空间的圆形图标也一样。设置图片后,按钮变为 Replace image 和 Remove image。参见空间图片。
Color无颜色,或 Red、Green、Yellow、Blue、Magenta 和 Cyan 之一。没有图片的空间会在圆形图标中以渐变绘制其颜色,在所有主题中都相同;没有颜色时则显示轮廓。
Environment空间变量的摘要和一个 Edit 按钮。参见空间环境。
Agent setup当空间把 CLAUDE_CONFIG_DIR 或 CODEX_HOME 从默认位置移开时显示:每个智能体一行,例如 Claude Code hooks and MCP,并显示其状态;出错后显示 Retry,未安装时显示 Install。

展开的空间底部有 Delete space,它会询问 Delete Work? Its 3 workspaces move to Default.,并提供 Cancel 和 Delete space。确认后,该空间的工作区会移到 Default,不会关闭任何终端;如果被删除的空间处于活动状态,Default 会成为活动空间;空间的图片也会被删除。

New space 会以第一个未使用的编号添加 Space N,并打开其名称供编辑;侧边栏空间菜单中的 New space… 和命令面板中的 New space 作用相同。已有 9 个空间时,该按钮会被禁用,旁边显示 9 spaces maximum。

空间图片

图片会在侧边栏标题、空间菜单和 Settings 中取代空间圆形图标里的颜色渐变。选择不超过 25 MB、每边不超过 12,000 像素的 PNG、JPEG、WebP、GIF、BMP 或 TIFF 文件。Paneflow 会应用照片的 EXIF 方向,将其裁剪为居中的正方形,并在 Paneflow home 下的 avatars/ 中存储一张 96 像素的 PNG(~/.paneflow/avatars/,在 Windows 上为 %USERPROFILE%\.paneflow\avatars\)。文件名会作为 avatar 记录在 paneflow.json 中该空间的条目上。无法读取或过大的图片会在 Image 字段下方显示原因,空间保留之前的圆形图标。替换或删除图片会删除之前的文件。

空间环境

Environment 下的 Edit 会为每个变量打开一行。这些值会设置在此后该空间各工作区中打开的每个终端上,优先级高于 terminal.env,低于智能体配置的 env 和 surface 自身的 env。开头的 ~ 表示你的 home 目录,$NAME 从 Paneflow 的环境中取值;每行下方会显示展开后的值。把 CLAUDE_CONFIG_DIR、CODEX_HOME 或 GH_CONFIG_DIR 指向单独的目录,即可在该空间中使用第二个 Claude Code、 Codex 或 GitHub CLI 账号。这三个变量必须是绝对路径;目录不存在时,Paneflow 会在第一个终端启动前创建它,在 Linux 和 macOS 上仅你自己可访问;无法创建时,提示消息会注明该目录。只有当每个 CLI 都遵循其目录变量时,两个账号才能保持隔离;设置了 GH_TOKEN 或 GITHUB_TOKEN 时,GH_CONFIG_DIR 不会隔离任何内容。

Save 会拒绝以下内容,并在对应行或表单下方显示原因:没有名称的值、重复列出的名称、不是合法变量名的名称、以 PANEFLOW_ 开头的名称、Paneflow 为每个终端设置的变量(例如 TERM)、会改变程序加载方式或智能体运行方式的变量(例如 LD_PRELOAD)或智能体会话标记(例如 CLAUDECODE)、 CLAUDE_CONFIG_DIR、CODEX_HOME 或 GH_CONFIG_DIR 的相对路径,以及指向 Paneflow 环境中未设置变量的 $NAME。在 Windows 上,终端收到的变量名会转为大写,而 paneflow.json 保留你输入时的大小写。名称包含 KEY、TOKEN、 SECRET 或 PASSWORD 的变量会显示 Stored in plain text in paneflow.json; prefer a config directory。当 Paneflow 自身的环境设置了 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、 CLAUDE_CODE_OAUTH_TOKEN、OPENAI_API_KEY、GH_TOKEN 或 GITHUB_TOKEN,而该空间没有重新定义它时,会显示一条警告:这些变量优先于配置目录中存储的账号。

已打开的终端保留启动时的环境:把工作区移到环境不同的空间时,会显示 Open terminals keep their previous environment,且不会重启任何内容。如果 shell 在其 rc 文件(例如 .zshrc)中导出同一个变量,则在该终端内会覆盖空间的值。

当空间把 CLAUDE_CONFIG_DIR 或 CODEX_HOME 从默认位置移开时,保存会为 Settings > Agents 中已安装的每个智能体,在该目录中安装 Paneflow 的 hooks 和 MCP 桥接,这样侧边栏仍能显示智能体何时在工作、何时在等待。发布版构建每次启动时都会刷新它们,每组不同的 Claude Code 和 Codex 目录各刷新一次。 Agent setup 列出每个智能体的状态,出错后显示 Retry,未安装时显示 Install。

删除空间不会移除其 hooks。要移除它们,请在该空间的 CLAUDE_CONFIG_DIR 中,从 settings.json 的 hooks 里删除标记为 "_paneflow_managed": true 的条目,从 .claude.json 中删除 paneflow server,并删除 skills/paneflow-conductor/SKILL.md;对于 Codex,请在其 CODEX_HOME 中,从 hooks.json 删除相同的条目,并从 config.toml 删除 [mcp_servers.paneflow] 表。该空间的记录位于 ~/.paneflow/integrations/spaces/<space id>/ 下,也可以一并删除。

空间用于组织工作,而不是安全边界。每个终端仍以你的身份运行,任何能读取你 home 目录的程序都能读取 paneflow.json 中的值。

AI access vs MCP

Agents 页面控制 Paneflow 如何启动 agents,以及可信 conductor 可以执行多少自动化。

claude_code_bypass_permissions 只影响 Claude Code 启动。启用后,Paneflow 会用 --permission-mode bypassPermissions 启动 Claude Code。它不会改变 Codex、OpenCode、Gemini 或 MCP 的行为。

Plugins 是单独的运维页面。它注册内置的 paneflow-mcp server,让受支持的 agents 可以 list、read 和 search Paneflow panes。它会修改 agents 自己的 config files,并且可以安全地再次运行。

Config-only controls

如果你需要的设置被有意留在主 Settings UI 之外,请使用 paneflow.json。

常见示例:

  • terminal.scrollback_lines,用于每个 terminal 的 scrollback history。
  • terminal.ligatures、terminal.cursor_blink、terminal.env 和 terminal.scroll_multiplier,用于高级 terminal behavior。Paneflow 的每个 build 都使用单一的固定版本、静态链接的 libghostty-vt 引擎来模拟面板,因此没有可供选择的引擎。
  • 不是 workspace templates 的 commands[] entries。
  • profiles、telemetry、window-decoration 和 agent-panel options。

Paneflow 会通过 watcher 重新加载有效的 config 变更。如果 JSON 格式错误,正在运行的 app 会保留上一个有效 config,而不是回退到 defaults。JSON Schema 会在 editors 中标记未知键;runtime 保持宽松,这样旧 build 可以忽略新键。

另请参阅

  • Configuration - file location、schema setup 和 runtime behavior。
  • Schema - 每个 key、type、default 和 stability。
  • Shortcuts and actions - shortcuts overrides 的 action names。
  • Themes - 内置 theme names 和 hot-reload behavior。