設定

Zshell の永続設定の多くは、次の 1 ファイルに保存されます。

~/.config/zshell/config.toml

設定ウィンドウ（Cmd+,）も同じファイルへ書き込みます。 言語や自動更新など macOS が管理する一部の設定は別の場所に保存され、このページの末尾にまとめています。

新しい設定では Vim コマンドヒント、セッション履歴の復元、失敗したコマンドの通知が標準で有効です。更新の自動ダウンロードも標準で有効です。既存の設定と保存済みの選択は保持されます。

ファイルの動作リンクをコピー

手動編集の前に、次の点を確認してください。

• 実行中も変更を読み込みます。 有効な外部編集は自動反映されます。新しい端末向けの設定には新規ペインが必要です。読み取り不能や構文エラーでは直前の有効な設定を維持し、意図的な空ファイルは少し待って既定値に戻します。
• ファイルで管理する設定を変えるたびに書き直します。 ファイル全体を再生成するため、次に該当する操作欄を使うとコメントや未知のキーは失われます。編集方法を一つにするか、管理元のコピーを dotfiles に保存してください。
• 原則として既定値以外だけを書き込みます。 font-size, terminal.vim-command-hints, terminal.restore-history, terminal.notify-on-error は常に保存します。既存のファイルでこの3つのターミナルキーのいずれかを削除すると、対応する機能がオフになります。ほかのキーを削除すると既定値に戻ります。
• パーサーは意図的に小さくしています。 単純なキー、ドット付きキー、[table] 見出し、# コメント、文字列・数値・真偽値に対応します。配列、インラインテーブル、複数行文字列は非対応です。
• 不正な値は安全に代替されます。 範囲外のサイズ、未知のバックエンド、誤記したテーマがあっても Zshell の起動を妨げません。

設定の保存時はファイルやディレクトリのシンボリックリンクを維持し、リンク先を権限を保って原子的に更新します。外部編集ではコメントや未知のキーを書き換えませんが、その後設定画面から保存すると上記のとおり再生成します。

アプリの表示場所リンクをコピー

app-presenceリンクをコピー

"dock" · "dock-and-menu-bar" · "menu-bar" — デフォルト "dock"

設定 → 一般 → Zshell の表示場所 で切り替えると、すぐに反映されます。"dock" は Dock のみ、"dock-and-menu-bar" は Dock とメニューバー、"menu-bar" はメニューバーのみにアイコンを表示します。

メニューバーから現在のワークスペース、クイックターミナル、設定、アップデート確認を開けます。どちらのメニューバーモードでも、最後のワークスペースウインドウを閉じると非表示になり、ターミナルとジョブは動作し続けます。ワークスペースを開く で同じウインドウ、プロジェクト、セッションに戻れます。ほかのウインドウ、ペイン、プロジェクトを閉じると、そのタスクは終了します。明示的な 終了 は引き続き terminal.preserve-sessions に従い、すべてのセッションを終了してアプリを終了 はタスクを終了します。モードは次回起動時も保持されます。

外観リンクをコピー

themeリンクをコピー

"system" · "light" · "dark" — 既定値 "system"

アプリの外観を選びます。"system" は macOS に従い、ほかの 2 つは指定した外観に固定します。

theme-dark と theme-lightリンクをコピー

文字列 — 既定値 "Default Dark" と "Default Light"

各外観に使う配色テーマです。ターミナル、ウィンドウ周辺、サイドバー、エディタ、差分をまとめて配色します。 内蔵の既定テーマは半透明のサイドバーを保ち、その他のテーマはそのパレットに合わせた色を使います。

設定には、両バックエンド共通の厳選したテーマ一覧を表示します。手書きの名前は大文字小文字も含め表示名と完全一致する必要があり、一致しなければ対応する既定テーマに戻ります。

toolbar.visibilityリンクをコピー

"hide" · "auto" · "always" — 既定値 "hide"

アクティブなタブの下のコンパクトなツールバーを制御します。

• "hide" は表示しません。
• "auto" はプロジェクトディレクトリが Git リポジトリの場合だけ表示します。
• "always" は全プロジェクトに Git の入口を表示し、リポジトリがなければGit リポジトリなし（No Git Repository）を表示します。

内容は Git ツールバーを参照してください。

テキストリンクをコピー

font-familyリンクをコピー

文字列 — 既定値 ""。同梱の JetBrains Mono を使います

ターミナル、エディタ、差分表示で共有する欧文フォントファミリーです。 "IBM Plex Mono Regular" のような書体名ではなく、"IBM Plex Mono" のようなファミリー名を指定します。未知または等幅でないファミリーは同梱の既定フォントへ戻ります。

ターミナルの代替順は、欧文ファミリー、任意の CJK 代替、同梱の Symbols Nerd Font、バックエンドのシステム代替です。 エディタと差分表示は従来の macOS／WebKit の代替処理を使います。

terminal.font-fallback-familyリンクをコピー

文字列 — 既定値 ""。バックエンド／システムの代替を使います

インストール済みの CJK ファミリーを 1 つ、ターミナルの代替フォント列に追加します。 設定の選択欄には代表的な中国語・日本語・韓国語の文字を含むファミリーを表示します。主な欧文フォントにない文字だけを補うため、厳密な等幅である必要はありません。

font-sizeリンクをコピー

数値、8–32 — 既定値 13

ターミナル、エディタ、差分で共有するポイント単位の文字サイズです。既定値でも Zshell が書き出す唯一のキーです。

interface.scaleリンクをコピー

数値、0.9–1.5 — 既定値 1

タブ、アイコン、ボタン、サイドバーなどアプリのインターフェースを拡大・縮小します。 ターミナル、エディタ、差分の内容は、上記で別に設定した文字サイズを保ちます。

sidebar.font-sizeリンクをコピー

数値、9–24 — 既定値 14

両サイドバーの基本文字サイズです。変更しても、セクション見出し、行、メタデータ、操作欄の相対的な階層を維持します。

terminal.font-thickenリンクをコピー

真偽値 — 既定値 false

従来の macOS のフォントスムージングに近い、少し太い線でターミナル文字を描きます。 両バックエンドで使え、設定のプレビューで結果を確認できます。旧 font-thicken も読み込めますが、書き直すと現在のドット付きキーになります。

terminal.font-thicken-strengthリンクをコピー

整数、0–255 — 既定値 255

terminal.font-thicken が true の場合の太さ補正を調整します。0 はオフではなく、最も弱い補正です。 Ghostty は macOS ネイティブの強度、Alacritty は同じ範囲を CoreText の線幅に対応させます。増減方向と両端はそろいますが、描画されたピクセルは異なることがあります。

terminal.line-heightリンクをコピー

数値、0.75–2 — 既定値 1

各バックエンドの標準セル高に倍率を掛け、文字の縦位置は中央に保ちます。ターミナル行だけを変え、エディタや差分の行間は変えません。

Zshell は基本のフォントウェイト設定を公開していません。 Ghostty は名前付きスタイルや可変軸を選び、Alacritty／CoreText は属性から標準・太字の書体を解決します。単一の共有値では、静的・可変フォントを通して標準／太字の区別や代替フォントの太さを一貫して保てないためです。

editor.wrap-linesリンクをコピー

真偽値 — 既定値 true

ファイルエディタで長い行をペイン幅に折り返します。 false なら横スクロールします。ターミナルや差分の折り返しは変わりません。

ターミナルリンクをコピー

terminal.startup-program / terminal.startup-argumentsリンクをコピー

文字列 — 標準では未設定

以降に作成するターミナルで使う実行ファイルと引数列を指定します。 terminal.startup-program がなければ、アカウントのログインシェルを -l 付きで使います。 実行可能な絶対パスが必要です。存在しない、または実行できない場合は、空のペインを開かずログインシェルに戻ります。

terminal.startup-arguments はシェルを呼び出さず引数に分割します。 引用符とバックスラッシュで、空白や空の引数も含め境界を保ちますが、変数・glob・コマンド置換は展開しません。 引用符が不正な場合もログインシェルへ戻ります。Zshell CLI から明示的な argv が与えられた場合は、そのターミナルではそちらが優先します。

terminal.backendリンクをコピー

"libghostty" · "alacritty" — 既定値 "libghostty"

以降に作成するターミナルのエミュレータを選びます。既存ペインは起動時のバックエンドを保ちます。 両方ともネイティブ、GPU アクセラレーション、画像描画、共通の Zshell テーマに対応し、一般に Alacritty のほうがメモリ使用量は少なめです。

環境変数と互換性の取り決めはターミナルバックエンドを参照してください。

terminal.macos-option-as-altリンクをコピー

真偽値 — 既定値 false

true なら Option キーの組み合わせを Alt/Meta ショートカットとしてターミナルプログラムへ送ります。 標準では macOS の現在の入力ソースに任せ、Polish Pro などの配列で合成文字を入力できるようにします。

terminal.bellリンクをコピー

真偽値 — 既定値 true

ターミナルプログラムがベルを鳴らした際の音と、macOS の視覚的な注意喚起を制御します。 false なら音、ターミナルベル通知、Dock での注意要求を行いません。支援技術には意味的な通知としてベルを引き続き伝えます。両バックエンドに適用されます。

terminal.vim-command-hintsリンクをコピー

真偽値 — 既定値 true

情報サイドバーのセッション情報の下に、モードに応じた Vim／Neovim コマンドを表示します。 認識できる SSH 上のエディタを含め、両バックエンドですぐに反映されます。検出条件は Vim コマンドヒントを参照してください。

terminal.restore-historyリンクをコピー

真偽値 — 既定値 true

再起動後、新しいシェルの上にターミナルの以前のスクロールバックを復元します。復元するのは静的なテキストで、生き残ったプロセスではありません。

復元用の履歴はディスクに保存されるため、ターミナルに表示された機密情報も含まれる可能性があります。 プロジェクト、タブ、ペイン配置は、この設定にかかわらず復元されます。

自動化リンクをコピー

ai.enabledリンクをコピー

真偽値 — 既定値 true

自然な言葉で依頼すると、対応するコーディングエージェントがバックグラウンドの Zshell ペインを調整でき、提供元が報告するライフサイクル状態を UI に表示します。 Zshell はターミナル文字から状態を推測しません。エラーを画面内で確認でき、競合する既存設定を変更しないため、設定画面のスイッチから変更することを推奨します。

使い方は AI エージェントとの作業で説明しています。

Codex app-server を共有する場合、検証済みの会話 ID を前面のペインに対応付け、曖昧な場合は紐付けません。管理対象の連携は他の項目を維持し、Codex の端末タイトルに session-id を追加します。

ai.resume-conversationsリンクをコピー

真偽値 — 既定値 true

ターミナルペインの復元時、元の PTY が利用できなければ、記録済みの Claude Code、Codex、Pi、OpenCode の元の会話を再開します。ai.enabled = true が必要です。検証済みの会話がないペインは新しいシェルを開きます。ディレクトリから最新の会話を選ぶことはありません。

設定 → 自動化 → エージェントの会話を再開 で切り替えます。terminal.restore-history とは独立した設定です。

その他の設定リンクをコピー

バックアップと移行リンクをコピー

Zshell → 設定をエクスポート…（Export Settings…）で TOML を保存し、設定をインポート…（Import Settings…）で読み込みます。 インポート時は置き換えを確認し、現在のファイルを同じディレクトリの config.toml.bak にバックアップしようとします。

インポートは対応するすべての設定を読み込みます。省略した項目は設定リーダーの既定値に従い、ai.enabled を省略すると現在の AI 設定を維持します。言語とプロジェクトやタブの環境変数は別に保存されます。

設定例リンクをコピー

theme = "dark"
theme-dark = "Catppuccin Mocha"
theme-light = "Catppuccin Latte"
font-family = "IBM Plex Mono"
font-size = 14
interface.scale = 1.25
sidebar.font-size = 13
toolbar.visibility = "auto"
terminal.font-fallback-family = "PingFang SC"
terminal.font-thicken = true
terminal.font-thicken-strength = 180
terminal.line-height = 1.15
terminal.macos-option-as-alt = false
terminal.bell = false
terminal.startup-program = "/opt/homebrew/bin/fish"
terminal.startup-arguments = "--no-config"
terminal.backend = "alacritty"
terminal.restore-history = true
editor.wrap-lines = true
ai.enabled = true
ai.resume-conversations = true

すべてのキーは省略できます。キーを削除すると、その設定を既定値へ戻します。

キーボードショートカットリンクをコピー

設定 → ショートカット（Shortcuts）で主要コマンドの新しいショートカットを登録できます。 競合する組み合わせは拒否し、すでに使っているコマンド名を表示します。 標準ショートカットに戻す（Restore Default Shortcuts）で全変更をリセットできます。キー操作一覧に標準の割り当てを掲載しています。

このファイル以外にある設定リンクをコピー

• 言語。 設定にはシステム既定と Web サイトと同じ 17 言語があります。変更は即座に適用され、ターミナルセッションは動作を続けます。macOS のアプリ別言語設定を使うため TOML ではなく Zshell の環境設定に保存されます。システム既定は macOS の言語順序に従います。
• 自動更新。 設定 → 更新の自動確認・ダウンロード・インストールは TOML 外のアプリ環境設定に保存され、起動をまたいで保持します。インストールは自動ダウンロードが有効な間だけ表示します。インストールを参照してください。
• ウィンドウとレイアウト。 ウィンドウサイズ、サイドバー幅、選択パネル、プロジェクト、タブ、ペイン、ブラウザ URL、差分表示の設定は macOS の環境設定とセッションスナップショットに保存します。
• バックエンドの設定ファイル。 ~/.config/ghostty や Alacritty の設定は読み込みません。両方とも Zshell の設定で管理します。