English

本页内容

Sigil 配置指南

文档首页 · 权限与沙箱 · 外观 · 高级配置 · 字段参考 · Provider 指南 · English

这是 Sigil 共享配置的推荐入口。本文说明配置在哪里、最小可用设置、workspace 与存储选择，以及应该去哪里查找具体设置。Provider 凭据和 provider 专项选项由 Provider 指南维护。

选择正确的页面

你想要…	从这里开始
设置 Sigil、选择 workspace 或找到配置文件	本文
修改批准、网络、外部路径或 sandbox	权限与沙箱
修改 TUI 主题、代码高亮或颜色	外观
配置 task、检查、memory、代码智能、终端、plugin 或 MCP	高级配置
查询精确的 `sigil.toml` 字段或值	配置字段参考
选择 model service、endpoint 或凭据	Provider 指南

配置查找顺序

Sigil 按以下顺序解析配置：

--config <path>
用户可见 Sigil 配置目录中的 sigil.toml

默认用户配置为：

~/.sigil/sigil.toml

Quick Setup 会写入这个用户配置。workspace 中的 sigil.toml 不会被自动加载；只有明确想使用本地实验配置时，才传入 --config <path>。

最小路径

日常交互使用时，在希望工作的项目中启动 Sigil 并完成 Quick Setup：

cd /path/to/workspace
sigil

临时使用或 CI 时，先选择 provider，并在启动前设置对应的 provider 凭据。Provider 指南提供每项服务正确的变量与可复制示例；不存在一个对所有 provider 通用的 API key 变量。

如果希望手写一份很小的共享配置，可以从这里开始：

[workspace]
root = "."

[agent]
tool_timeout_secs = 30

[appearance]
theme = "sigil_dark"
syntax_theme = "auto"
usage_cost_currency = "auto"

然后从所选 provider 页面加入 provider 区块。可复制示例位于 docs/examples/config。

Workspace

[workspace]
root = "."

workspace.root = "." 会解析为启动 sigil 时所在的目录，因此一份用户配置可以跟随你打开的仓库。文件工具受限于这个 workspace，会拒绝父路径逃逸、绝对路径以及指向 workspace 外的 symlink。

允许 workspace 外路径或修改本地命令行为之前，请先阅读权限与沙箱。

本地命令 Shell

注册内置工具时，Sigil 会解析并冻结一个 native shell。Windows 优先使用 pwsh.exe，找不到时回退到 Windows PowerShell（powershell.exe）；macOS 与 Linux 使用 sh。为了 provider 兼容，工具名仍是 bash，但工具说明、批准分析、结果 metadata 与 terminal card 都会显示实际 program 和 dialect。

PowerShell 命令必须使用 $env:NAME、$null 等 PowerShell 语法；Sigil 不会翻译 Bash 语法。显式 terminal_start.shell 只接受已建模的 POSIX shell、PowerShell 或 cmd.exe，未知 shell 会在 spawn 前失败。跨平台读取和编辑应优先使用 Sigil file tools。如果命令语法与预期 host 不一致，运行 sigil doctor 并查看 terminal:shell。

Storage 与 Session 路径

[storage]
state_root = "auto"
cache_root = "auto"

[session]
# log_dir = "sessions"

[session.retention]
max_sessions = 500
max_bytes = 2147483648
expire_older_than_ms = 15552000000 # 180 天

state_root 保存持久的每用户 Sigil state，例如 session 相关记录和 artifact。cache_root 保存可重建的 scratch data。session.log_dir 只修改当前 workspace 的 session log 位置，不会取代 state root。

Session retention 只为显式 maintenance preview 与确认提供 policy；普通启动、run、resume 和 sigil serve 都不会自动应用。current、active、pinned、unsupported 或发生 drift 的 session 会受保护。TUI 操作见管理已保存的 session。

SIGIL_STATE_HOME 与 SIGIL_CACHE_HOME 可覆盖对应 root。在 sigil.toml 中覆盖时，优先使用绝对路径。仓库内可复用资源固定放在 .sigil/ 下；这些资源见高级配置。

Setup 出问题时使用 Doctor

运行：

sigil doctor

在 TUI 内使用 /doctor 可看到同一份报告。它检查配置加载、workspace 解析、session 位置、provider 与凭据来源、已配置 MCP server、代码智能 readiness 和终端兼容性。它绝不打印 secret 值，并为 warning 与 error 提供修复建议。

使用非默认配置启动时，也要带上同一个覆盖：

sigil --config ./sigil.toml doctor

下一步

在 Provider 指南中选择 model service。
在权限与沙箱中选择安全的编辑与网络策略。
在外观中自定义 TUI。
在高级配置中设置 task、检查、MCP 或终端行为。
在配置字段参考中查询字段。