Codex 的 Subagents 數量上限

#codex #agents

本文以此版文為測試依據：

> codex --version
codex-cli 0.142.5

在 Codex 的 Subagents 文件中提到，同時可以執行的 Subagents 數量由設定檔中的 agents.max_threads 決定，沒有設定時，預設是 6，不過時測時預設卻不是 6：

> codex exec "最多可以執行幾個 subagent？" 2>$null | glow -s light

  最多可同時執行 3 個 subagent；加上主 agent，共有 4 個並行執行槽位。

你可以看到預設是 4 個。

由於 codex exec 會透過標準錯誤輸出額外的資訊，為了避免干擾我們檢視回覆內容，因此利用 2>$nul 在 PowerShell 中把錯誤輸出轉向丟棄。另外，glow 是顯示 Markdown 文件的 CLI 工具。

但即使透過 agents.max_threads 強制設定：

> codex exec --config agents.max_threads=10 "最多可以執行幾個 subagent？" 2>$null | glow -s light

  最多可同時執行 3 個 subagent；加上我這個主 agent，共 4 個並行名額。

結果依然沒變，真是奇怪。還好，Codex CLI 是開放原始碼的專案，這種測試結果跟文件不一致的情況，就請 Codex 自己查看看原始碼：：

> codex exec "查一下原始碼中跟 subagent 數量上限有關的部分有哪些？查到後告訴我設定的方式" 2>$null | glow -s light

  目前 Codex 原始碼有兩套 subagent 數量限制，取決於使用哪一版 multi-agent。

  ### 1. 傳統 multi-agent                                          

  設定鍵：                                                         

    [features]                                                     
    multi_agent = true                                             

    [agents]                                                       
    max_threads = 12                                               

  預設值是  6 ：                                                   

    DEFAULT_AGENT_MAX_THREADS: Option<usize> = Some(6);            

  主要相關原始碼：                                                 

  •  codex-rs/core/src/config/mod.rs  https://github.              
  com/openai/codex/blob/main/codex-rs/core/src/config/mod.rs：預設值、讀取
  agents.max_threads                                               
  •  codex-rs/core/src/agent/control.rs  https://github.           
  com/openai/codex/blob/main/codex-rs/core/src/agent/control.rs：把限制交給
  session 執行 limiter                                             
  •  codex-rs/core/src/agent/registry.rs  https://github.          
  com/openai/codex/blob/main/codex-rs/core/src/agent/registry.rs：配置與回收
  spawn slot                                                       
  •  codex-rs/protocol/src/error.rs  https://github.               
  com/openai/codex/blob/main/codex-rs/protocol/src/error.rs：超過限制時的
  AgentLimitReached                                                

  也可以只對單次 CLI 執行覆寫：                                    

    codex -c agents.max_threads=12                                 

  或：                                                             

    codex exec -c agents.max_threads=12 "你的任務"                 

  ### 2. Multi-agent V2                                            

  新版另有獨立設定：                                               

    [features.multi_agent_v2]                                      
    enabled = true                                                 
    max_concurrent_threads_per_session = 8                         

  預設值是  4 ：                                                   

    DEFAULT_MULTI_AGENT_V2_MAX_CONCURRENT_THREADS_PER_SESSION: usize = 4;

  Schema 規定最小值是  1 ，原始碼目前看不到硬性最大值。設定 Schema 
  https://github.com/openai/codex/blob/main/codex-rs/core/config.schema.json

  你這個工作階段顯示「4 available concurrency slots」，與 V2       
  的預設值完全一致，所以如果要改目前看到的 4，應優先設定：         

    [features.multi_agent_v2]                                      
    enabled = true                                                 
    max_concurrent_threads_per_session = 8                         

  設定檔位置通常是 Windows 的：                                    

    %USERPROFILE%\.codex\config.toml                               

  修改後需重新啟動 Codex session。 agents.max_threads  和 V2 的    
  max_concurrent_threads_per_session                               
  是不同限制；為避免版本或功能切換造成落差，也可以兩個都設：       

    [features]                                                     
    multi_agent = true                                             

    [features.multi_agent_v2]                                      
    enabled = true                                                 
    max_concurrent_threads_per_session = 8                         

    [agents]                                                       
    max_threads = 8                                                

  數值開太高可能增加 429、token 消耗和資源競爭；官方把舊版預設設為 6、新版設為
  4，應是刻意的保守值。

你可以看到居然有兩套 Subagent 機制，該不會現在 Codex 其實是採用文件上沒有寫的 multi_agent_v2 吧？

> codex exec "現在是不是有啟用 multi_agent_v2？有的話，要如何設定 Subagent 數量上限？" 2>$null | glow -s light

  沒有啟用  multi_agent_v2 。本機狀態是：                          

    multi_agent       stable             true                      
    multi_agent_v2    under development  false                     

  目前工作階段上限是 4 個 agent thread（包含主 Agent），因此最多同時執行 3 個
  Subagent。                                                       

  若要設定全域上限，編輯  %USERPROFILE%\.codex\config.toml ：      

    [agents]                                                       
    max_threads = 4                                                
    max_depth = 1                                                  

  也可放在專案的  .codex/config.toml 。 max_threads  預設為 6； max_depth
  控制 Subagent 可繼續產生幾層子代理。設定後重開 Codex 工作階段。  

  若要實驗性啟用 v2：                                              

    codex features enable multi_agent_v2                           

  但一般 Subagent 工作目前使用穩定的  multi_agent  即可，無須啟用  
  v2。參考：Subagents                                              
  https://developers.openai.com/codex/subagents、Configuration reference
  https://developers.openai.com/codex/config-reference。

咦？並沒有啟用 multi_agent_v2，但 multi_agent_v2 預設限制是 4 個 Subagent，這看起來跟我們前面的測試相符，死馬當活馬醫，如果試試用用 multi_agent_v2 的方式設定：

> codex exec --config features.multi_agent_v2.max_concurrent_threads_per_session=6 "最多可以執行幾個 subagent？" 2>$null | glow -s light

  最多可同時執行 5 個 subagent，加上主 agent 共 6 個並行工作槽位。

成功了，雖然沒有啟用 multi_agent_v2，但卻要照著 multi_agent_v2 的方式設定，原因不知道，但至少目前可行。

DEV Community

Codex 的 Subagents 數量上限

Top comments (0)