附錄：Agent worker 設定

Agent worker 設定#

.ait/agent-workers.json 為一個 AIT Repository 宣告具名的訊息 worker。 1.1.1 支援 telegram、line、discord 和 slack。預設位置可以用 AIT_AGENT_CONFIG_PATH 覆蓋。

先讀 ait-agent-worker：訊息與回覆執行時， 瞭解這個可執行檔案的職責、完整命令面、從訊息到回覆的路徑、傳輸模式、 原生 Codex provider、執行時接納和安全限制。這份附錄是逐欄位的編寫參考。

規範文件形狀#

{
  "version": 1,
  "workers": {
    "telegram/support": {
      "kind": "telegram",
      "name": "support",
      "mode": "poll",
      "username": "support_bot",
      "env_path": ".ait/agent-runtime/telegram.env",
      "request_timeout_seconds": 30,
      "local_reply": {
        "model": "gpt-5.4-mini",
        "reasoning_effort": "low",
        "sandbox": "workspace-write",
        "turn_timeout_seconds": 300
      }
    }
  }
}

作者要寫的就是上面那種直接的 version 加 workers 物件。內部診斷投影 可能會把它包在 config 裡；別把那層包裝寫進儲存庫檔案。

worker 的 key 用確切的 <kind>/<name> 形式。kind 和 name 都必須非空， name 裡不能有 /，顯式寫出的 kind 必須和 key 一致。目前約定下 version 是整數 1。規範化過程中出現問題時，worker 會啟動失敗並直接 關停。

通用 worker 欄位#

執行目標從 .ait/config.json 推導：solo_local 在本地跑；有遠端的工作流程 則需要一個有效的預設遠端 URL。當 worker 沒有設定 model 時，Repository 的 default_model 提供 Telegram 的模型回落值。

憑據來源與優先順序#

憑據欄位必須是非空字串。解析順序是：

1. worker 條目本身；
2. 目前程序環境；
3. worker 的 env_path 檔案。

其他行為類欄位只來自 worker 條目或它們編譯期的預設值；env 檔案覆蓋不了 它們。環境檔案接受 KEY=VALUE 行、空行、# 註釋，以及值兩邊配對的一對 單引號或雙引號。它們不是 shell 指令碼。

別把機密留在提交上去的清單裡。優先用僅所有者可讀的 env 檔案或程序環境， 並使用環境變數附錄 裡那些確切的變數名。

local_reply#

這個巢狀物件裡的未知欄位會被拒絕。

sandbox 的取捨是一條執行邊界，不是訊息偏好。只給這個 worker 完成其 Repository 任務所需的訪問許可權。

Telegram 欄位#

LINE 欄位#

Discord 欄位#

選用哪條 worker 命令，決定了該服務模式下 public_key、bot_token 是必須 其一還是兩者都要。

Slack 欄位#

選用哪條 Slack 命令，決定了必須提供的是 socket 憑據還是 HTTP 簽名金鑰。

驗證#

用完整 CLI 參考裡的 agent worker 檢視和啟動命令。診斷輸出只報告憑據是否 已設定，不會列印它們的值。webhook 監聽器先在環回地址上測試，再透過可信的 反向代理對外暴露。