設定參考

Coppice 把設定儲存在一個檔案 config.toml 中:

作業系統路徑
Linux~/.config/Coppice/config.toml
macOS~/Library/Application Support/Coppice/config.toml

在 Linux 上,如果設定了 XDG_CONFIG_HOME,檔案位於 $XDG_CONFIG_HOME/Coppice/config.toml。

在應用中編輯

在側邊欄中開啟 Settings(設定)。頁面會以文字形式顯示該檔案,你寫的註釋也會保留。

  • Save 會在寫入前檢查檔案。無效的值不會被儲存。
  • Restore last good version 可以撤銷一次錯誤的修改。

有些修改會立即生效,另一些會提示 “Saved. Restart Coppice to apply.”(已儲存,重啟 Coppice 後生效。)

你也可以用任意文字編輯器修改這個檔案。你的修改在升級後依然保留。

更新

開啟 System → Updates(系統 → 更新)可以查看當前版本,並選擇 Check for updates(檢查更新)。Automatic updates(自動更新)預設開啟。關閉後,Coppice 將不再在後台檢查新版本。

這個開關不在 config.toml 中。Coppice 把它以 automaticUpdates 儲存在同一資料夾下的 update-settings.json 中。

更換金鑰

如果你分享過備份,請生成新的金鑰和新的管理員密碼。已儲存的令牌仍然可用,所有人都會被登出。

開啟 System → Backup → Replace keys,輸入新的管理員密碼並確認。

日誌

管理員可以開啟 System → Logs(系統 → 日誌),篩選並即時查看伺服器、請求、代理執行和資料庫日誌。每次執行都有一個 View logs 連結。

Export logs 會把符合當前篩選條件的日誌行儲存為 coppice-logs.zip。Coppice 會移除它已知的令牌和金鑰,但分享之前請自己再檢查一遍。

Report a problem 會新建一個 GitHub issue,並自動填好你的 Coppice 版本。寫明發生了甚麼、你原本期望甚麼,然後附上經 Export logs 匯出的 zip 檔案。

[logs]

欄位類型預設值作用
retention_days整數14日誌保留天數(含當天):3、7、14 或 30,預設 14。Coppice 每小時刪除一次過期日誌,修改無需重啟即可生效。如果日誌超過 256 MiB,即使還沒到 retention_days,Coppice 也會從最舊的開始刪除。

即使超過限制,Coppice 也不會刪除當天的日誌,以及正在寫入的資料庫日誌。資料庫日誌計入 256 MiB 上限,超過 retention_days 後會被刪除。

欄位類型預設值作用
dir字串./data/logs日誌資料夾。桌面應用使用自己的資料夾,會忽略此項。修改後需要重啟。

連接器

Coppice 找到的 CLI 預設開啟,除非登入檢查顯示你已登出。只有想關閉某個連接器時,才需要加一行:

[agent.connectors.claude-code]
enabled = false

System → Connectors 中的開關寫入的也是這一行。

Kilo Code、GitHub Copilot、Qwen Code 和 Kimi Code 只要被 Coppice 找到就會開啟。Coppice 無法免費檢查它們的登入狀態,所以如果你已登出,執行時會報錯。

[agent]

欄位類型預設值作用
worktrees_path字串<data-dir>/worktrees存放 worktree 的資料夾,每個工單各有一個 git worktree。
worker_count整數8所有連接器合計的代理任務上限。小於 1 時按 1 處理。舊設定的 worker_count = 2 仍會擋住其他連接器,直到你提高或刪掉這一行。
health_check_interval_secs整數60代理健康檢查的間隔秒數。小於 10 時按 10 處理。

<data-dir> 是存放 config.toml 的資料夾:Linux 和 WSL 上為 ~/.config/Coppice,macOS 上為 ~/Library/Application Support/Coppice。

[agent.connectors.<id>]

可用的 id:claude-code、codex、cursor、opencode、kilo-code、copilot、qwen-code、kimi、grok。每個表都是可選的。

欄位類型預設值作用
enabled布林值未設定:CLI 已登入則開啟開啟或關閉該連接器。
model_providers字串列表[]該連接器的模型供應商。開啟連接器時自動填寫。
run_timeout_secs整數所有連接器均為 1800該連接器上的一次執行超過多少秒算失敗。
max_concurrent_runs整數2該連接器同時可跑的任務數。多出來的保持排隊,空出位置後由最舊的先開始。小於 1 時按 1 處理。
command字串cursor-agent(Cursor)、codex、opencode、kilo、copilot、qwen、kimi、grok要執行的 CLI 執行檔。Claude Code 始終執行 claude,沒有 command。

僅限 OpenCode:

欄位類型預設值作用
serve_hostname字串127.0.0.1執行期間 OpenCode 輔助程式使用的主機名。修改後需要重啟。

修改 OpenCode 的 command 也需要重啟。

[workflow]

欄位類型預設值作用
auto_start_runs布林值true為 true 時,給已關聯倉庫的工單指派代理會自動開始執行。為 false 時,需要你按 Run agent。
auto_assign.default布林值true為所有沒有單獨設定的狀態開啟自動指派。
auto_assign.<status>布林值backlog:false;其他:使用 default為某個狀態開啟或關閉自動指派。
auto_split.default布林值false為所有沒有單獨設定的狀態開啟自動拆分。
auto_split.<status>布林值使用 default為某個狀態開啟或關閉自動拆分。

狀態鍵:backlog、ready、in_progress、in_review、in_qa、wait_for_final_review(Wait for Human Review)、blocked、done。

某個狀態開啟自動指派時,Coppice 會指派該次執行指定的代理。關閉時,工單上會改為顯示 Recommends:(推薦)。

某個狀態開啟自動拆分時,Coppice 會建立該次執行建議的子工單。關閉時,它會儲存一條 Pending split recommendation(待處理的拆分建議),直到你按 Approve splits。

[knowledge]

欄位類型預設值作用
enabled布林值true開啟或關閉知識壓縮。
poll_interval_ms整數500壓縮排程器的喚醒頻率。小於 100 時按 100 處理。
compaction.interval_secs整數1800兩輪壓縮之間的間隔秒數。
compaction.batch_max_tickets整數10一批最多包含的工單數。
compaction.batch_max_source_bytes整數200000一批最多包含的源資料位元組數。
compaction.max_candidates_per_batch整數20一批最多能提出的候選條目數。
compaction.max_attempts整數3一批最多嘗試的次數。
auto_save.enabled布林值false不經詢問,直接儲存低風險的候選條目。
auto_save.allowed_types字串列表[]自動儲存允許儲存的類型:bug_pattern、coding_convention、dependency_note、performance_note、review_feedback、test_command。
auto_save.minimum_confidence字串high必須保持為 high。
retrieval.top_k整數8一次查詢返回的條目數,1 到 20。
retrieval.allowed_types字串列表[](所有類型)只返回這些類型:coding_convention、architecture_rule、bug_pattern、test_command、review_feedback、dependency_note、api_contract、workflow_rule、human_preference、operational_runbook、security_rule、performance_note。
retrieval.minimum_confidence字串mediumlow、medium 或 high。
retrieval.default_page_size整數25預設每頁條數。
retrieval.max_page_size整數100每頁最大條數,最多 100。
retrieval.max_active_per_board整數1000一塊看板最多可容納的 Knowledge 條目數(待批准或已批准)。該看板上代理的條目也計入在內。
retrieval.max_active_workspace整數10000適用於整個工作區的 Knowledge 條目上限(待批准或已批准)。

以上所有數量和間隔都必須大於 0。

[git]

欄位類型預設值作用
author_name字串CoppiceCoppice 所做提交的作者名。
author_email字串coppice@localhost這些提交的作者電郵。
push_enabled布林值false(桌面應用程式為 true)允許 Coppice 推送分支並建立 pull request。

[plugins]

欄位類型預設值作用
dir字串<data-dir>/plugins你的預設外掛資料夾。更多資料夾可在 Plugins 頁面新增。
allow_file_git_urls布林值false允許安裝外掛時使用 file: 形式的 git URL。
git_timeout_secs整數300外掛克隆或更新超過多少秒算失敗。
mcp_start_timeout_secs整數20等待外掛 MCP 伺服器啟動的秒數。
mcp_list_timeout_secs整數10等待外掛列出工具的秒數。
mcp_idle_shutdown_secs整數600空閒的外掛 MCP 伺服器保持執行的秒數。

[mcp]

欄位類型預設值作用
builtin_plugins_dir字串<data-dir>/builtin-pluginsCoppice 每次啟動時寫入內建技能的位置。在這裏做的修改會丟失。
call_timeout_secs整數60單次工具呼叫超過多少秒算失敗。
max_output_bytes整數32768工具結果的最大位元組數。
comment_post_limit整數5一次執行最多能發表的評論數。
token_ttl_secs整數14400一次執行的工具令牌有效期(秒)。

[keybindings]

每個鍵都是鍵盤快捷鍵中的一個命令 id。你設定的按鍵會替換該命令的預設按鍵,設為空值則關閉該快捷鍵。

欄位類型預設值作用
"<command id>"字串或字串列表內建快捷鍵替換該命令的按鍵。"" 會移除它們。
[keybindings]
"palette.open" = "P"
"ticket.create" = ""
"board.nextCard" = ["J", "Down"]

Mod 在 macOS 上是 Cmd,在 Linux 和 WSL 上是 Ctrl。按鍵序列寫作 G then B。一個命令的多個按鍵用 or 分隔,或寫成列表。儲存後無需重啟即可生效。無法解析的快捷鍵、未知的命令 id、已被其他命令佔用的按鍵,以及屬於瀏覽器或系統的按鍵都會被跳過。該命令保留預設按鍵,Settings 會說明原因。