建立和配置 AI 代理
選擇執行時，定義 AI 代理的職責、能力、執行方式和 Access。
建立 AI 代理前，需要先有一個可用的執行時。執行時決定這名 AI 代理使用哪臺電腦和哪款 AI 程式設計工具；AI 代理則儲存它長期使用的身份、指令和能力。
建立流程
在工作區的 AI 代理 頁面點 新建 AI 代理，按三步完成：
選擇執行時。 頁面會列出各臺機器上的 AI 程式設計工具（harness），只有線上的才能進入下一步。後面能選哪些模型、能不能用 skill，都取決於這一步的選擇。
配置 AI 代理。 填寫名稱、描述、指令、skill、模型和訪問權限。不想從頭寫，可以點 讓 AI 幫我寫：當前草稿會交給 Agent Builder，它在對話裡追問關鍵資訊並補全配置。這個按鈕只在所選執行時線上、且不是雲端執行時時出現。對話期間，旁邊的配置草稿隨時可以直接修改。
點選建立 AI 代理。 完成頁會顯示它執行在哪個執行時，並給出下一步入口：指派第一個任務、在任務裡 @ 它，或加入小隊。
- 1Choose runtime
- 2Configure
- 3Done
必填項
建立 AI 代理只要求兩項：
- 名稱：在當前工作區中必須唯一。
- 執行時：選擇實際執行的環境。
其他欄位可以先使用預設值，建立後再調整。新 AI 代理預設只有建立者可以執行。
描述與指令
描述是寫給團隊看的簡短介紹，只顯示在 AI 代理列表和詳情中，不會進入 AI 程式設計工具的提示。
指令會在每次執行時提供給 AI 代理，通常包含：
- 它負責什麼、不負責什麼；
- 收到工作後先檢查什麼；
- 允許修改哪些內容；
- 結果的提交方式；
- 什麼時候需要向成員確認。
例如：
你負責審查前端 Pull Request。
先閱讀改動和相關測試，只檢查：
- React 與 TypeScript 的正確性
- 可訪問性
- 與現有元件模式是否一致
不要直接修改程式碼。把問題按嚴重程度寫在 issue 評論中；
沒有阻塞問題時，明確說明可以合併。新增 skill
建立時可以從工作區選擇一個或多個 skill。
Skill 適合儲存可以跨 AI 代理重複使用的方法和資料；只屬於這名 AI 代理的長期要求寫在指令中。
對話開場建議
最多新增三條對話開場建議，讓使用者在傳送第一條訊息前瞭解這個 AI 代理擅長什麼。它們出現在別人與該 AI 代理開始新對話時，位於輸入框上方。每項包含一個簡短標題和一條完整提示詞。選擇後只會填入輸入框，使用者可以先檢查或修改，不會自動開始執行。
建立時，它是身份卡片裡的一個可選項。建立之後，它在設定 → 通用裡，和頭像、名稱、描述放在一起，旁邊會預覽新對話的實際效果。有編輯權限的人還會在那個空狀態裡看到自定義開場建議入口，點選可直接跳到這裡。
留空時，對話頁會顯示本地化的通用預設值。針對 AI 代理職責和邊界編寫的示例通常更有幫助。
CLI 可用 agent create / agent update 的 --conversation-starters 設定（{"label","prompt"} 物件的 JSON 陣列；更新時傳 '[]' 清空）。agent copy 仍只搬運源值，沒有覆蓋 flag。
選擇執行時、模型和思考強度
執行時已經對應一款 AI 程式設計工具。選擇執行時後，可以繼續選擇該工具支援的模型和思考強度；部分工具（如 Codex）還可選擇速度檔：
- 留空時，使用執行時或本地 CLI 的預設配置。
- 設定模型後，該 AI 代理之後領取執行時會使用這個覆蓋值。
- 某些執行時自行管理模型，因此不會顯示模型選擇。
不同工具支援的模型、會話恢復、skill 和 MCP 能力不同，見AI 程式設計工具對照。
設定 Access
Access 決定哪些成員可以執行這名 AI 代理（分配、@提及或對話）：
| Access | 含義 |
|---|---|
| 僅自己（Only me） | 只有你可以執行。預設選項。 |
| 整個工作區（Entire workspace） | 所有工作區成員都可以執行。 |
| 指定成員（Specific people） | 只有你和選中的成員可以執行。 |
只有 AI 代理 owner 可以修改 Access，工作區管理員也不行。工作區 owner 和 admin 可以管理其他配置，但不能借管理員身份執行未授權的 AI 代理。
建立後的配置項
開啟 AI 代理詳情頁，可以繼續調整：
| 配置 | 作用 |
|---|---|
| 併發上限 | 同一名 AI 代理最多同時執行多少次執行，預設是 6；達到上限後繼續排隊。 |
| 環境變數 | 在 AI 程式設計工具啟動時注入變數。 |
| 自定義引數 | 逐項追加到 AI 程式設計工具的 CLI 引數中。 |
| MCP | 為支援的 AI 程式設計工具配置 MCP server：可以單獨新增，也可以從工作區共享的 MCP Server 裡選用。 |
| 整合 | 連線這名 AI 代理可以使用的外部服務。 |
執行時所在的守護程式還有一個全域性併發上限（預設 20），實際併發取兩者中的較小值。
修改配置不會改變已經開始的執行。後續執行被執行時領取時，會使用當時儲存的 AI 代理配置。
環境變數與憑據
環境變數適合放這名 AI 代理執行時需要的有限權限憑據，例如只讀 API key 或單一 scope 的 token。
custom_env 的值在 Multica 伺服器的資料庫裡是明文儲存的，不屬於"只留在本機"的資料。agent list/get 介面不再返回任何 env 值，只返回鍵的數量；只有工作區 owner、admin 可以解鎖和修改，並且每次讀取或修改都會留下審計記錄。執行中的 AI 代理不能呼叫管理介面讀取其他 AI 代理的變數。
不要使用生產資料庫的管理員密碼或其他高價值長期憑據。
PATH、HOME 和 MULTICA_* 等執行環境關鍵變數不能透過這裡覆蓋。
自定義引數和 MCP
自定義引數按陣列逐項傳給 AI 程式設計工具，不經過 shell 展開。引數名稱是否有效由對應工具決定；已有獨立欄位的模型配置不需要在這裡重複設定。
建立 AI 代理、修改自定義引數或更換執行時時，執行時介面卡保留的引數會被拒絕，錯誤資訊會指出衝突的引數。例如，Multica 使用 --permission-mode bypassPermissions 執行 Claude Code，在自定義引數裡設定 --permission-mode dontAsk 會被拒絕。已儲存的引數與目標執行時衝突時，可以同時傳入 [] 清空自定義引數，再完成更換。
不要把憑據或其他 secret 放進自定義引數。它們會留在子程式的 argv 中，同機其他程式可能透過 ps 或 /proc 看到；請改用環境變數（custom_env）。守護程式日誌會遮蔽引數值，但無法保護作業系統的程式列表。
MCP 配置可能包含 token，儲存與展示規則和環境變數相同。只有支援託管 MCP 配置的執行時會顯示這一項；不支援的工具不會因為儲存了配置就自動獲得 MCP 能力。AI 代理有 MCP 配置時，守護程式還會合並執行時所在電腦上已配置的 MCP server，見本機 MCP 配置。
AI 代理詳情頁的 MCP 分三組列出這名 AI 代理能用的 MCP server：
| 分組 | 來源 |
|---|---|
| 由 Multica 管理 | 只屬於這名 AI 代理的 server。點選新增 MCP Server，用視覺化表單或 JSON 填寫 STDIO 啟動命令或 Streamable HTTP 地址。 |
| 工作區 MCP Server | 從工作區共享庫裡分配給它的 server，見下一節。 |
| 從執行時繼承 | 執行時所在電腦上 AI 程式設計工具自己的使用者配置，只讀。只有本地執行時線上時才能讀取。 |
名稱相同時，AI 代理自己的配置優先於工作區分配的 server，兩者又都優先於執行時裡的同名 server。被蓋住的一項會標上已覆蓋或已由 Multica 覆蓋。
工作區共享的 MCP Server
同一個 MCP server 要給多名 AI 代理用時，不必在每名 AI 代理裡各填一遍地址和 token。工作區 owner 或 admin 在設定 → MCP 伺服器裡新增一次，再分給需要它的 AI 代理。
管理員開啟設定 → MCP 伺服器，點選新增 MCP Server，填寫名稱和配置。
新增後，這個 server 不屬於任何 AI 代理。開啟要用它的 AI 代理詳情頁的 MCP，在工作區 MCP Server一組點選從工作區新增，選中它。
分配後，每名 AI 代理各有一個開關，可以暫時關掉而不取消分配。改動從這名 AI 代理的下一次執行起生效。
設定 → MCP 伺服器的列表裡，每個 server 下方顯示"已分配給 N 個 AI 代理"或"未分配給任何 AI 代理"。使用時注意：
- 配置只寫不讀：儲存後，地址、命令、請求頭和環境變數的值不會再顯示給任何人，包括 owner。要改配置只能點替換配置，重新填寫一份完整配置；只改名稱不影響配置和已有分配。
- 刪除影響所有 AI 代理：在設定裡刪除一個 server，會把它從所有分配過的 AI 代理上一併移除，從各自的下一次執行起生效。只想讓某一名 AI 代理不再用，在它的 MCP 裡關掉開關或移除即可。
- 權限：普通成員能看到列表，但不能新增或修改。給 AI 代理分配或移除 server，需要該 AI 代理的 owner 或工作區
owner、admin。AI 代理在執行中透過 CLI 不能新增 server，也不能改分配。
用 CLI 也能完成同樣的操作。配置裡通常有 token，用檔案或 stdin 傳入，不要直接寫在命令列引數裡：
multica workspace mcp add linear --server-config-file ./linear.json
multica workspace mcp list
multica agent mcp add <agent-id> <server-id>複製 AI 代理
複製會帶上名稱之外的大部分工作配置，包括指令、對話開場建議、skill、自定義引數、頭像、併發上限和 Access 設定。模型、思考強度和速度檔也會一併帶走；如果原執行時不可用、複製被迫換到其他執行時，這三項會清空，需要重新選擇。
環境變數的值、MCP 配置和工作區 MCP Server 的分配在任何情況下都不會複製，需要在新 AI 代理中重新設定。
使用 CLI 建立
multica agent create \
--name "Frontend Reviewer" \
--runtime-id <runtime-id> \
--description "審查前端 Pull Request" \
--instructions "先閱讀改動和測試，只在 issue 評論中提交審查結論。" \
--conversation-starters '[{"label":"審查 PR","prompt":"審查當前最相關的未合併 Pull Request。"}]'命令列引數中的明文會進入 shell 歷史；stdin 和權限受限的檔案不會。
已有配置相近的 AI 代理時，可以直接複製：
multica agent copy <agent-id>預設複製到同一執行時；加 --runtime-id 換到其他執行時，必須同時指定 --model。環境變數、MCP 配置和 runtime_config 永不復制；執行時繫結本身會保留。完整引數見使用 CLI。
接下來
- 分配任務給 AI 代理 — 用真實工作驗證配置。
- Skills — 建立、匯入和重複使用團隊方法。
- 守護程式與執行時 — 排查線上狀態和執行位置。