企业官网建设流程全解析

agent-deck 是一个终端会话管理器（terminal session manager），让你在同一个 TUI 里统一管理 Claude、Gemini、OpenCode、Codex 等多种 AI 编程代理。想让它真正贴合你的工作流，关键就在一个文件——config.toml。这篇文章带你从基础参数一路走到高级定制，把 agent-deck 的 config.toml 配置逐项讲透，帮你快速搭出一个顺手的多代理工作环境。

一、配置文件在哪里？快速定位 config.toml

在改任何参数前，先搞清楚文件位置。agent-deck 读取的配置默认在：

$XDG_CONFIG_HOME/agent-deck/config.toml

也就是大多数系统上的~/.config/agent-deck/config.toml（旧版~/.agent-deck/config.toml仍受支持）。整个配置采用 TOML 语法，用一个个[section]分块组织。

💡 不用背路径：TUI 里按S打开Settings面板，底部会直接提示当前生效的config.toml位置，还能可视化编辑部分项。

完整参数清单见官方参考文档：config-reference.md。

二、顶层基础参数：default_tool 等入门设置

文件最上方是一批顶层键，决定了"新建会话"时的默认行为。新手最常用的是前两项：

default_tool = "claude" default_path = "" sync_title = true group_sort = "creation"

把sync_title = false可以全局禁止代理重命名你的会话，让你自己起的名字保持稳定。

三、[shell] 环境变量：让每个会话都带上你的环境

如果你的代理需要direnv、nvm、pyenv或某些密钥，用[shell]统一注入，对所有会话生效：

[shell] env_files = ["~/.agent-deck.env", ".env"] # 依次 source，后者覆盖前者 init_script = "~/.agent-deck/init.sh" # 每个会话启动前执行 ignore_missing_env_files = true # 缺失的 .env 静默跳过

路径支持~、$VAR、${VAR}以及相对路径。加载顺序为：全局env_files→init_script→ 工具专属env_file→ 内联env（后者优先级最高）。

四、[claude] 与多账号配置

Claude Code 是最常用的代理，可单独精调：

[claude] config_dir = "~/.claude" # Claude 配置目录 dangerous_mode = true # 加 --dangerously-skip-permissions env_file = "~/.claude.env" # 仅 Claude 会话读取的 .env

当你同时有个人、工作、客户等多个 Claude 账号时，用profile 级覆盖最干净——全局给默认值，只为需要的 profile 覆盖config_dir：

[claude] config_dir = "~/.claude" # 全局默认（个人） [profiles.work.claude] config_dir = "~/.claude-team" # 工作账号 [profiles.clientx.claude] config_dir = "~/.claude-clientx" # 客户账号

之后用agent-deck -p work即自动切到对应账号。组/编排器粒度还能用[groups."<name>".claude]与[conductors.<name>.claude]做更细的隔离。

五、[worktree] 与 [fork]：多代理并行的高级定制

多个代理同时改同一个仓库时，用 Git worktree 隔离最省心。[worktree]控制 worktree 落地方式：

[worktree] default_location = "sibling" # sibling | subdirectory | 自定义路径 branch_prefix = "$USER/" # 分支名前缀，支持环境变量展开 auto_cleanup = true # 删除会话时移除 worktree sparse_checkout = "off" # 大型 monorepo 可设 "inherit" 继承稀疏检出

而分叉会话（fork）用独立的[fork]段——它与上面的 worktree 默认值互不干扰：

[fork] inherit_from_parent = false # true => 完全镜像父会话 worktree = true # 为新分支建 worktree with_state = true # 携带父会话未提交改动 with_ignored = false # 是否连 .env 等 gitignored 文件一起复制（默认关） docker = "auto" # auto | on | off branch_prefix = "fork/"

⚠️with_ignored默认关闭是有原因的：gitignored 目录可能包含node_modules、密钥等敏感内容且体积无上限，显式开启才复制。

六、[mcp_pool] 与 [mcps.*]：一次定义，随处挂载

MCP 服务器在config.toml里只定义一次，之后在 TUI 里按会话开关即可。本地 STDIO 型：

[mcps.exa] command = "npx" args = ["-y", "exa-mcp-server"] env = { EXA_API_KEY = "your-key" } description = "Web search via Exa AI"

远程 HTTP/SSE 型则写url+transport。当你同时跑很多会话时，用[mcp_pool]让所有会话共享同一批 MCP 进程，通过 Unix socket 复用，可把内存占用降低 85–90%：

[mcp_pool] enabled = true # 开启 socket 池 pool_all = true # 池化全部 MCP exclude_mcps = [] # 需要排除的 MCP

七、[ui] 与 [display]：界面外观微调

想让 TUI 更清爽？这两段管"看"的体验：

[ui] footer = "full" # full | curated | compact | minimal hidden_tools = ["gemini", "opencode"] # 从新建选择器隐藏不用的工具 [display] default_filter = "active" # 启动时的初始状态过滤 show_pane_titles = false # 是否每行显示任务描述 include_cwd_prefix = true # 标题前是否加 [项目名]

hidden_tools是显示层面的过滤，不影响 CLI 启动；shell永远无法被隐藏。

八、[docker] 沙箱与 [notifications] 通知

需要隔离执行时，用[docker]把会话跑进容器：

[docker] default_enabled = false # 新建会话默认勾选沙箱 mount_ssh = true # 只读挂载 ~/.ssh，容器内可用 git auto_cleanup = true # 会话结束时删除容器

代理等待输入时，希望被"揪"出来看一眼，就打开通知：

[notifications] enabled = true # tmux 状态栏通知条 desktop = false # 会话进入 waiting/error 时弹系统通知 transition_events = true # 子会话状态变化时通知父会话

desktop = true是唯一能在 TUI 之外打断你的信号，适合后台挂代理的场景。

九、用 CLI 命令管理配置：config get / set / schema

不想手改文件？agent-deck 提供了四个子命令直接读写配置：

agent-deck config get display.default_filter # 查看某个键的生效值 agent-deck config set display.footer compact # 写入单个设置 agent-deck config schema --json # 列出全部可设键 agent-deck config show --effective ~/path/to/repo # 查看合并后的 worktree 设置及来源

config schema会给出每个键的 section、类型、默认值、允许取值与是否需要重启，是查参数的好帮手；config show --effective能告诉你某个值是来自默认、全局配置还是目录级覆盖。

十、完整配置示例速查

下面是一份涵盖常用段的完整config.toml骨架，按需删改即可：

default_tool = "claude" [shell] env_files = ["~/.agent-deck.env"] [claude] config_dir = "~/.claude" dangerous_mode = true [profiles.work.claude] config_dir = "~/.claude-team" [worktree] default_location = "sibling" branch_prefix = "$USER/" [fork] worktree = true with_state = true [notifications] enabled = true [mcp_pool] enabled = true pool_all = true [mcps.exa] command = "npx" args = ["-y", "exa-mcp-server"] env = { EXA_API_KEY = "your-key" }

📌 进阶能力如 Conductor 编排、Recall 记忆、Comms 通信账本等各有独立文档：recall.md、comms.md、daemon-protocol.md，配合config.toml的对应段落即可解锁完整的舰队级编排。

掌握以上段落，你就能把 agent-deck 的 config.toml 从"开箱即用"调成"专属定制"。建议从顶层默认值与[claude]账号入手，再逐步叠加 worktree、MCP 池与通知等高级项，逐步搭出一个稳定、省心的多代理工作台。