配置参考

这是 config.toml 的逐键参考。Takuto Core 仓库根目录下带注释的 config.toml.example 才是事实来源 —— 当本页与那个文件冲突时，以示例文件为准。

设置在文件变更时会重新加载（一个 5 秒的轮询器）。少数键是仅启动时生效的，需要重启（已在行内注明）。密钥属于 takuto.env，绝不要放进 config.toml —— 参见环境变量。

Takuto Core 把配置分为两类：

Bootstrap —— 在数据库/仪表盘存在之前就需要，或仅在启动时应用。首次启动前在 config.toml 里手工编辑这些。
UI 管理 —— 有合理的默认值，通常从仪表盘的 Configuration 界面编辑。UI 会把变更写回 config.toml，因此文件仍是存储；在这里设置的值只是部署时的默认值。

Scope 列把每个键标为 Bootstrap，或标出管理它的仪表盘界面名。🔒 标记安全敏感的键 —— 在共享部署中更改前请先审查。

`[general]`

进程级行为：工单模式、轮询、并发、日志。

键	默认值	类型	Scope	说明
`ticketing_system`	`"none"`	string	Bootstrap	`"jira"`、`"github"` 或 `"none"`。驱动轮询器和仪表盘的 + 按钮。
`dry_mode` 🔒	`false`	bool	Bootstrap	跳过真实的 Jira/GitHub 副作用（不分配、不流转、不推送）。本地工作 —— worktree、安装、agent 会话 —— 仍照常运行。适合在上线前预演一个 workflow 定义。
`log_level`	`"info"`	string	Bootstrap（重启）	`trace`、`debug`、`info`、`warn`、`error`。
`worker_image`	`""`	string	Bootstrap	启用 DinD 时，隔离 workflow container 所用的 Docker 镜像。留空 = 从运行中的 Takuto 镜像自动识别。
`workflow_definitions_dir`	`"workflows"`	string	Bootstrap（重启）	扫描 `*.toml` workflow 的路径，这些定义为新用户/工作区播种默认值。实际生效的 workflow 在仪表盘里编辑（Configuration → Workflows）；事后改 TOML 不会影响已播种的工作区。
`allow_auto_generate_secret_key` 🔒	`true`	bool	Bootstrap	为 `true` 时，若首次启动找不到密钥，服务器会自动生成 `{data_dir}/secret.key`。设为 `false` 可在带外预置该密钥。
`poller_owner_username`	(未设置)	string	Bootstrap	拥有轮询器自动创建的 workflow 的用户名。未设置时，取按字典序排在最前、未被停用的 admin。
`migrate_orphan_workflows`	`false`	bool	Bootstrap	为 `true` 时，启动时把没有所有者的已恢复 workflow（多用户化之前的孤儿）重新分配给解析出的轮询器所有者。
`migrate_orphan_repo_associations`	`true`	bool	Bootstrap	为 `true` 时，启动对账会把已恢复的 workflow 关联到与之匹配的已注册仓库。
`auto_polling`	`true`	bool	UI: Item Polling	为 `false` 时，轮询在启动时处于暂停。用 Resume polling 来开始领取工单。
`poll_interval_secs`	`60`	int	UI: Item Polling	Jira/GitHub 两次轮询之间的秒数。
`pr_merge_poll_interval_secs`	`60`	int	UI: Item Polling	检查某 workflow 的 PR 是否已在 GitHub 上合并的轮询间隔（秒）。`0` 表示禁用。
`max_concurrent_workflows`	`1`	int	UI: Item Polling	并行 mise/安装/agent 会话的信号量大小。调到与你的 CPU 和 RAM 相称。
`max_active_workflows`	`0`	int	UI: Item Polling	仪表盘上可见 workflow（每一行）的上限。达到该上限时轮询器不会启动新工单。`0` 等同于 `max_concurrent_workflows`。
`max_concurrent_manual_workflows`	`0`	int	UI: Item Polling	对仪表盘 + 手动启动且非 Done/Stopped/Error 的 workflow 数量上限。`0` = 无上限。
`generate_report`	`false`	bool	UI: Item Polling	为 `true` 时，每个 agent 步骤都会把发现追加到一份报告里，最后一步将其汇总。会增加 token 消耗。
`work_item_log_retention_days`	`7`	int	UI: Item Polling	清理前保留工作项日志行的天数。`0` = 永久保留。

`[jira]`

仅在 [general] ticketing_system = "jira" 时使用。

键	默认值	类型	Scope	说明
`site`	`""`	string	Bootstrap	Jira 主机或完整 `https://` URL（例如 `"yourcompany.atlassian.net"`）。驱动 token 认证、egress 允许清单和 PR 正文中的 Jira 链接。
`email`	`""`	string	Bootstrap	用于 `acli` token 认证的 Jira 用户邮箱。
`project_keys`	`[]`	array	UI: Item Polling	要轮询的 Jira 项目键（例如 `["PROJ", "ENG"]`）。为空时隐藏 + 选择器。
`item_types`	`["Task", "Bug"]`	array	UI: Item Polling	轮询器领取的工单类型。手动 + 选择器会显示所有非 Epic 的 issue。
`done_status`	`"Done"`	string	UI: Item Polling	Mark as Done 触发的流转。必须与你 Jira workflow 中的真实流转相匹配。
`jql_filter`	`""`	string	UI: Item Polling	以 `AND` 合并进 + 选择器的额外 JQL。Epic 始终被排除。
`linked_items_in_prompt`	`"full"`	string	UI: Item Polling	`"full"` \| `"summary_only"` \| `"omit"` —— 关联 issue 文本在 `{ticket_context}` 中如何呈现。
`ticket_context_max_description_bytes`	`0`	int	UI: Item Polling	`{ticket_context}` 中主工单描述的字节上限。`0` = 不限（默认）。
`linked_issue_description_max_bytes`	`0`	int	UI: Item Polling	当 `linked_items_in_prompt = "full"` 时，每个关联 issue 描述的字节上限。`0` = 不限（默认）。

`[polling]`

管理员可调的工单轮询策略：轮询器自动添加哪些发现到的条目、自动启动哪条 flow，以及并行运行多少个。每个周期实时读取（无需重启）。所有 [polling] 键都从 Configuration → Item Polling 进行 UI 管理。

键	默认值	类型	Scope	说明
`auto_start_flow`	`""`	string	UI: Item Polling	每个被轮询条目要自动启动的那条 flow 的 slug。为空 = 启动所有无依赖的 flow。
`max_parallel_items`	`0`	int	UI: Item Polling	同时占用并发槽位的条目上限。`0` = 不限。
`max_parallel_per_user`	`false`	bool	UI: Item Polling	为 `true` 时，`max_parallel_items` 按 workflow 所有者计；`false` 则全局计。

`[polling.jira]`

键	默认值	类型	Scope	说明
`summary_keywords`	`[]`	array	UI: Item Polling	对工单摘要做大小写不敏感的 “任一子串” 匹配。为空 = 不过滤。

`[polling.github]`

键	默认值	类型	Scope	说明
`labels`	`[]`	array	UI: Item Polling	精确的标签归属，任一匹配即可。为空 = 不过滤。
`title_keywords`	`[]`	array	UI: Item Polling	对 issue 标题做大小写不敏感的 “任一子串” 匹配。为空 = 不过滤。

`[git]`

所有 [git] 键都是 Bootstrap 设置。

键	默认值	类型	Scope	说明
`base_branch`	`"main"`	string	Bootstrap	每个 worktree 从中创建的分支。
`remote`	`"origin"`	string	Bootstrap	用于 fetch、base ref 和 push 的 git remote。
`repo_path`	`"/workspace"`	string	Bootstrap	container 内已克隆仓库的路径。workspace 名称取自该路径的最后一段。

`[github]`

可选的 GitHub App 认证。配置后，提交和 PR 会归属到 bot 账号，而非你个人的 gh 用户。三个字段（app_id、app_installation_id 以及一个私钥来源）必须一并设置；错误不致命 —— Takuto Core 会回退到个人 gh 认证并记录一条警告。所需的 App 权限：contents （写）、pull_requests（写）、metadata（读）。

键	默认值	类型	Scope	说明
`app_id`	(未设置)	int	Bootstrap	GitHub App ID。
`app_installation_id`	(未设置)	int	Bootstrap	你的组织/仓库对应的 App installation ID。
`app_private_key` 🔒	(未设置)	string	Bootstrap	PEM 编码的 RSA 私钥，内联形式。与 `app_private_key_path` 互斥。建议把它放在 `takuto.env` 中。
`app_private_key_path` 🔒	(未设置)	string	Bootstrap	指向含 App 私钥的 PEM 文件的路径。

`[web]`

仪表盘服务器。

键	默认值	类型	Scope	说明
`host`	`"0.0.0.0"`	string	Bootstrap（重启）	绑定地址。
`port`	`8080`	int	Bootstrap（重启）	绑定端口。
`cors_origins` 🔒	`[]`	array	Bootstrap（重启）	允许的 CORS 来源。为空 = 从 `host`/`port` 自动计算。处于反向代理或 TLS 终结器之后时请显式设置（例如 `["https://maestro.example.com"]`）。
`cookie_secure` 🔒	(自动识别)	bool	Bootstrap	控制会话 cookie 上的 `Secure` 标志。会从 `https://` 的 `cors_origins` 或入站的 `X-Forwarded-Proto: https` 自动识别。当在没有该头部的情况下终结 TLS 时强制设为 `true`；仅在本地纯 HTTP 测试时设为 `false`。
`kick_other_sessions_on_login`	`true`	bool	Bootstrap	为 `true` 时，一次成功登录会删除同一用户先前的会话。若要桌面 + 移动并发会话，设为 `false`。

认证是仅多用户的。首次启动时仪表盘会提示你创建初始 admin 账号。旧版单用户键 [web] dashboard_username / dashboard_password 已被移除 —— 若它们仍存在于旧 config.toml 中，会被静默忽略。

会话策略（不可配置）： 空闲 TTL 24 小时；绝对 TTL 30 天；10 分钟内 5 次登录/恢复失败后锁定账号（admin 通过 POST /api/users/{id}/unlock 解锁）；对 /api/auth/login 和 /api/auth/recover 按 IP 限速 10 次/分钟。

`[database]`

Takuto 存放用户、会话和快照的地方。省略这一小节（或把 connection 留空），就保持 零配置的 SQLite 默认值，位于 {data_dir}/takuto.db。设置 connection 即可改用外部的 PostgreSQL / MariaDB / MySQL。仅启动时生效 —— PUT /api/config 不会修补这一小节；更换后端需要重启进程。

键	默认值	类型	Scope	说明
`connection` 🔒	`""`	string	Bootstrap（重启）	数据库 URL。为空 → SQLite。scheme：`sqlite://…`、`postgres://…` / `postgresql://…`、`mysql://…`（也涵盖 MariaDB）。`GET /api/config` 中密码会被打码。
`max_connections`	`10`	int	Bootstrap（重启）	连接池大小。
`acquire_timeout_secs`	`30`	int	Bootstrap（重启）	在超时之前等待获取一个池中连接的时长。
`idle_timeout_secs`	`600`	int	Bootstrap（重启）	空闲连接的存活时长。
`fail_fast` 🔒	`true`	bool	Bootstrap（重启）	为 `true` 时，启动时会跑一个 5 秒的 `SELECT 1` 探测，若后端不可达则中止。为 `false` 时，它会记录一条警告，并为该进程回退到本地 SQLite。
`import_from_sqlite`	`true`	bool	Bootstrap（重启）	首次连接到一个全新的外部后端时，把已有的本地 SQLite 数据一次性拷贝进去（会话会失效，因此用户需重新认证）。后续重启会跳过。

数据库跑在 container 里？ connection 的主机必须从 Takuto container 内部可达 —— 请使用数据库的 container 名及其内部端口（例如 takuto_db:5432），而不是 localhost 或宿主发布的端口（例如 localhost:5433），并把两个 container 放到同一个网络上。完整的操作指引见 外部数据库。

`[agent]`

为携带 prompt 的 workflow 步骤服务的 AI 提供商。每个 [agent] 键都从 Configuration → AI Settings 进行 UI 管理；这里的值是部署时的默认值。

键	默认值	类型	Scope	说明
`provider`	`"claude"`	string	UI: AI Settings	`"claude"`、`"cursor"`、`"codex"` 或 `"opencode"`。每个都读取自己的 `[agent.providers.<name>]` 子表。
`step_timeout_secs`	`1800`	int	UI: AI Settings	单步超时（秒）。对所有提供商生效。
`improve_timeout_secs`	`300`	int	UI: AI Settings	AI 描述润色（“improve”）操作的超时（秒）。
`share_conversation_across_steps`	`false`	bool	UI: AI Settings	在一条 flow 的各步骤间共享同一个 agent 对话，还是每步开新会话。
`max_repeated_output_lines`	`8`	int	UI: AI Settings	无进展防护。当某步骤的输出连续这么多次重复同一行实质内容时中止它。`0` 表示禁用。

各提供商的设置（模型、端点、CLI 路径、额外参数）放在 [agent.providers.<name>] 子表里。常见字段：model、extra_args、allow_shared_default；Claude/Codex/OpenCode 使用 base_url，Cursor 使用 cli。

`[agent.providers.cursor]`

仅在 provider = "cursor" 时使用。

键	默认值	类型	Scope	说明
`cli`	`"agent"`	string	UI: AI Settings	Cursor Agent 可执行文件名或绝对路径。
`model`	`"Auto"`	string	UI: AI Settings	Cursor Agent 的 `--model`。`"Auto"` 或为空 = 自动选择。
`extra_args`	`[]`	array	UI: AI Settings	额外的 CLI 标志（强制执行拒绝清单）。

`[agent.providers.opencode]`

OpenCode（自托管、OpenAI 兼容）适配器。仅在 provider = "opencode" 时使用。参见自托管模型。

键	默认值	类型	Scope	说明
`model`	`""`	string	UI: AI Settings	端点所服务的模型 id（即 `-m self_hosted/<model>` 中的 `<model>`）。启用时必填。
`base_url`	`""`	string	UI: AI Settings	OpenAI 兼容的端点 URL（例如 `http://lm-studio:1234/v1`）。启用时必填。
`extra_args`	`[]`	array	UI: AI Settings	额外的 CLI 标志（强制执行拒绝清单）。
`allow_shared_default`	`false`	bool	UI: AI Settings	让没有个人 bearer 的用户回退到部署默认 token。
`context_limit`	`32768`	int	UI: AI Settings	自托管模型的最大上下文窗口（token）。与你服务器加载的上下文长度保持一致。
`output_limit`	`8192`	int	UI: AI Settings	每次响应的最大输出 token 数。

Claude 和 Codex 使用各自的 [agent.providers.claude] / [agent.providers.codex] 子表，含 model、base_url 和 extra_args，全部可从 Configuration → AI Settings 编辑。

`[docker]`

所有 [docker] 键都是 Bootstrap（在镜像构建 / compose up 时消费）。

键	默认值	类型	Scope	说明
`build_commands`	`[]`	array	Bootstrap	镜像构建期间运行的可选 `bash -c` 步骤。
`compose_up_commands`	`[]`	array	Bootstrap	每次 `docker compose up` 在预检之后、以 `maestro` 用户身份运行的可选命令。

`[editor]`

浏览器内的 VS Code（openvscode-server）和动态端口转发。所有 [editor] 键都是 Bootstrap。

键	默认值	类型	Scope	说明
`ports`	`[]`	array	Bootstrap	打开编辑器时要暴露的应用端口（例如 `[3000, 5173, 6006]`）。每个都会映射到 9100–9200 范围内的一个宿主端口，并显示在 workflow 卡片上。
`dynamic_ports`	`10`	int	Bootstrap	为自动转发开发服务器预分配的备用端口。`0` 表示禁用。
`theme`	`""`	string	Bootstrap	VS Code 配色主题；留空则使用编辑器自带的默认主题（例如 `"One Dark Pro"`）。
`extensions`	`[]`	array	Bootstrap	要预装的 Marketplace ID（例如 `["esbenp.prettier-vscode"]`）。
`settings`	`{}`	table	Bootstrap	`[editor.settings]` 下的自由格式 VS Code 设置。

`[terminal]`

编辑器 container 内的 web 终端（ttyd）。所有 [terminal] 键都是 Bootstrap。

键	默认值	类型	Scope	说明
`git_editor`	(未设置)	string	Bootstrap	装进每个编辑器 container 的 apt 包（例如 `"nano"`、`"vim"`）；`git config core.editor` 会设为它。
`setup_commands`	`[]`	array	Bootstrap	每个编辑器 container 生命周期内只运行一次的 shell 命令（由一个标记文件守卫）。
`startup_commands`	`[]`	array	Bootstrap	每次创建全新编辑器 container 时都运行的 shell 命令。

`[network]`

防火墙策略 —— 仅部署时生效。所有 [network] 键都是 Bootstrap。

允许清单是按提供商感知的：防火墙会自动放行你所启用的 AI 提供商的 API 主机 —— 即当前的 [agent].provider，加上 [agent].available_providers 中的每一个提供商（Claude、Codex/OpenAI、Cursor），以及任何自托管的 base_url。在默认配置下（四个提供商全部可用），每一家受支持的厂商都开箱即可访问；收窄 available_providers 即可把防火墙收紧到只剩你实际使用的提供商。具体主机由核心的 takuto egress-hosts 命令在应用时解析得出。

键	默认值	类型	Scope	说明
`extra_egress_hosts` 🔒	`[]`	array	Bootstrap	在内置默认项（你的 AI 提供商、Atlassian、GitHub、npm registry，以及在 `.npmrc` 中检测到的 registry）之上加入 egress 允许清单的域名。每一条都会扩大攻击面 —— 只添加你信任 agent 去访问的主机。
`allow_all_https` 🔒	`false`	bool	Bootstrap	为 `true` 时跳过允许清单，放行所有出站 HTTPS（443/8443）。`extra_egress_hosts` 会被忽略。仅在受信环境中使用 —— 这会禁用 Takuto Core 的核心缓解措施之一。

`[provisioning]`

启动时在镜像内置工具之上、额外装进共享工具卷的 CLI 工具。可用它锁定某个工具版本、添加一个从内置打包中移除的工具，或完全跳过某个工具。Bootstrap（启动时应用）。参见扩展 Takuto Core。

键	默认值	类型	Scope	说明
`install_commands`	`[]`	array	Bootstrap	针对工具卷按顺序运行的 shell 片段。受 SHA 门控：仅当列表变化时才重新运行。每个片段都应幂等，并装到 `$MAESTRO_TOOLS_BIN`。

`[dev]`

仅开发用的旋钮。生产环境中保持注释掉。所有 [dev] 键都是 Bootstrap。

键	默认值	类型	Scope	说明
`mock_agent`	`false`	bool	Bootstrap	为 `true` 时，agent 会话会短路成一个脚本化的 mock —— 没有真实的 `claude`/`agent` 进程，不消耗 token。遵从 `MAESTRO_DEV_MOCK_AGENT=1`。
`mock_agent_script_path`	(未设置)	string	Bootstrap	mock 脚本文件的路径。无默认值 —— `tmp/mock_script.txt` 只是建议的示例。
`mock_agent_line_delay_ms`	`75`	int	Bootstrap	mock 输出行之间的延迟。
`mock_agent_total_ms`	`5000`	int	Bootstrap	mock 会话的总时长。

被忽略的小节

以下小节在加载时被完全忽略 —— 会记录一条启动警告以引起你注意，但它们的内容从不被读取。它们之所以从 config.toml 中移出，是因为它们是按用户、按 workspace 的，如今只存在于数据库里，从仪表盘编辑：

[commands] —— worktree 初始化命令（原先的 pre_install、install、 pre_workflow，现为 worktree_init_commands）存在数据库里，按 (user, workspace) 解析，从 Configuration → Worktree Settings 编辑。
[[run_commands]] —— 作为运行/停止按钮呈现的长时运行开发服务器命令，是按用户的，从同一个 Worktree Settings 标签页配置。

不存在配置回退：如果某小节在数据库里缺失，workflow 就干脆不为它运行任何命令。

环境变量

密钥和按主机的覆盖项放进 takuto.env（挂载在 /etc/maestro/env）。只有 export VAR=value 形式的行才会被采纳。

变量	用途
`ANTHROPIC_API_KEY` 🔒	Claude API key（或通过 `claude login` 使用 OAuth）。
`ANTHROPIC_BASE_URL`	覆盖 Anthropic API 端点（代理 / 本地部署网关）。
`CLAUDE_CODE_OAUTH_TOKEN` 🔒	Claude Code OAuth 认证用的 token。
`CURSOR_API_KEY` 🔒	Cursor Agent 的 key —— 跳过交互式的 `agent status` 预检。
`GH_TOKEN` 🔒	GitHub PAT（细粒度，限定到目标仓库）。
`MAESTRO_CONFIG`	指向一个备用 `config.toml` 的路径。
`MAESTRO_DATA_DIR`	覆盖持久数据目录（`maestro.db`、快照）。
`MAESTRO_HOME`	覆盖用于计算 `MAESTRO_DATA_DIR` 的 home 基目录。
`MAESTRO_DEV_MOCK_AGENT`	`1` = 强制开启 mock agent（覆盖 `[dev] mock_agent`）。

takuto.env 示例：

export ANTHROPIC_API_KEY="sk-ant-..."
export GH_TOKEN="github_pat_..."
export ANTHROPIC_BASE_URL="https://custom-proxy.example.com/claude"