與擴(kuò)展：TaoToken 統(tǒng)一 Key 接入配置骨架)
1. 為什么二開(kāi)階段必須先把 Key 通道收口OpenClaw Edict 三省六部制這套系統(tǒng)前兩篇把部署啟動(dòng)和日常使用跑通之后真正進(jìn)入二次開(kāi)發(fā)時(shí)最先暴露的問(wèn)題往往不是代碼寫(xiě)不出來(lái)而是模型訪問(wèn)通道太散。根目錄看板主線里dashboard/server.py直接讀環(huán)境變量edict/backend的 FastAPI 服務(wù)層又有一套自己的配置加載邏輯PyQt 啟動(dòng)器里還單獨(dú)彈窗讓用戶輸入 API KeyAgent 的SOUL.md旁邊可能還掛著各自的模型配置。改一個(gè)模型要在四五個(gè)地方同步漏一處就出現(xiàn)「看板能跑、Worker 報(bào) 401」這種典型故障。這一篇聚焦的就是這個(gè)收口動(dòng)作把 TaoToken 作為統(tǒng)一 Key/API 通道在 Edict 的 config.toml 與 settings.json 兩個(gè)配置骨架里落地讓 PyQt 前端、Agent 調(diào)度層、FastAPI 服務(wù)層都從同一份配置讀取模型訪問(wèn)信息。適合已經(jīng)能跑起 Edict、準(zhǔn)備做面板擴(kuò)展、Agent 擴(kuò)展或調(diào)度改造的開(kāi)發(fā)者。讀完之后你應(yīng)該能完成一次可復(fù)制的連通性驗(yàn)證并且知道配置寫(xiě)錯(cuò)時(shí)該去哪個(gè)文件排查。TaoToken 在這里的角色是統(tǒng)一模型訪問(wèn)入口提供兼容 OpenAI 風(fēng)格的 API 通道Edict 各層只需要認(rèn)一個(gè) base_url 和一個(gè) key不用為每個(gè)模型供應(yīng)商單獨(dú)寫(xiě)適配。官網(wǎng)地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不帶 UTM 參數(shù)。2. TaoToken 前置準(zhǔn)備Key 與通道確認(rèn)在動(dòng) Edict 的配置文件之前先把 TaoToken 這邊的訪問(wèn)憑證準(zhǔn)備好。登錄后進(jìn)入控制臺(tái)在 API Keys 頁(yè)面創(chuàng)建一個(gè)新的 Key。建議按用途命名比如edict-dev、edict-prod這樣后面在 Edict 里做多環(huán)境配置時(shí)不會(huì)混。創(chuàng)建完 Key 之后你需要確認(rèn)兩件事一是 API base 地址二是可用模型列表。TaoToken 的 API 入口是https://taotoken.net/api在 Edict 的配置里通常寫(xiě)成https://taotoken.net/api/v1這種帶版本號(hào)的形式具體取決于你調(diào)用的接口路徑。模型列表可以在模型對(duì)話頁(yè)面里直接試確認(rèn)你要用的模型名拼寫(xiě)正確比如claude-sonnet-4-20250514這類完整標(biāo)識(shí)不要憑記憶寫(xiě)簡(jiǎn)寫(xiě)。如果你打算長(zhǎng)期在 Edict 上做編碼類 Agent 的擴(kuò)展可以順帶看一下 Coding Plan 的額度說(shuō)明避免開(kāi)發(fā)到一半發(fā)現(xiàn)調(diào)用量不夠。控制臺(tái)里能看到當(dāng)前 Key 的用量和剩余額度這個(gè)信息在排查「請(qǐng)求突然失敗」時(shí)很有用——有時(shí)候不是配置錯(cuò)了是額度用完了。注意Key 不要直接寫(xiě)進(jìn) Git 倉(cāng)庫(kù)里的配置文件。下面給的 config.toml 和 settings.json 骨架里Key 字段建議用環(huán)境變量占位實(shí)際運(yùn)行時(shí)由啟動(dòng)腳本注入。3. 可復(fù)制配置config.toml 與 settings.json 骨架Edict 的兩條主線對(duì)配置文件的讀取方式不一樣所以這里給兩份骨架你按自己改的那條線選用或者兩份都配上讓它們指向同一個(gè) Key。3.1 config.toml 骨架edict/backend 全棧線全棧線通常用 TOML 做服務(wù)層配置。在edict/backend/config.toml或項(xiàng)目約定的配置目錄下寫(xiě)入下面這段[llm] provider taotoken base_url https://taotoken.net/api/v1 api_key ${TAOTOKEN_API_KEY} default_model claude-sonnet-4-20250514 timeout_seconds 60 max_retries 3 [llm.models] zhongshu claude-sonnet-4-20250514 menxia claude-sonnet-4-20250514 shangshu claude-sonnet-4-20250514 worker_default claude-sonnet-4-20250514 [scheduler] retry_max 3 escalate_threshold_sec 180這里的關(guān)鍵點(diǎn)是api_key用${TAOTOKEN_API_KEY}占位實(shí)際值從環(huán)境變量讀。base_url指向 TaoToken 的 API 入口default_model和分角色模型都寫(xiě)完整模型名。[scheduler]段對(duì)應(yīng)后面調(diào)度擴(kuò)展會(huì)用到的重試和升級(jí)閾值。3.2 settings.json 骨架根目錄看板線 PyQt 啟動(dòng)器根目錄看板主線和 PyQt 啟動(dòng)器更習(xí)慣讀 JSON。在data/settings.json或啟動(dòng)器同級(jí)的配置目錄下寫(xiě){ llm: { provider: taotoken, base_url: https://taotoken.net/api/v1, api_key_env: TAOTOKEN_API_KEY, default_model: claude-sonnet-4-20250514 }, agents: { zhongshu: { model: claude-sonnet-4-20250514 }, menxia: { model: claude-sonnet-4-20250514 }, shangshu: { model: claude-sonnet-4-20250514 } }, launcher: { host: 127.0.0.1, port: 7891, log_dir: .runtime/prod/logs } }注意這里用的是api_key_env而不是直接存 KeyPyQt 啟動(dòng)器讀取時(shí)先查環(huán)境變量查不到再?gòu)棿白層脩襞R時(shí)輸入。這樣既保留了桌面入口的便利性又不會(huì)把密鑰落盤(pán)到源碼目錄。3.3 環(huán)境變量注入無(wú)論用哪份配置啟動(dòng)前都要把 Key 注入環(huán)境變量。Windows 下在啟動(dòng)腳本里加set TAOTOKEN_API_KEY你的KeyLinux/macOS 下export TAOTOKEN_API_KEY你的Key如果你用的是01_setup_prod_env.bat --sync這類引導(dǎo)腳本可以把這行加在腳本開(kāi)頭或者單獨(dú)寫(xiě)一個(gè)env.local.bat并在主腳本里call它避免 Key 進(jìn)入版本控制。4. 驗(yàn)證請(qǐng)求一次可復(fù)制的連通性檢查配置寫(xiě)完不要直接啟動(dòng)整個(gè) Edict先用一個(gè)最小請(qǐng)求確認(rèn)通道是通的。這一步能幫你把「配置錯(cuò)誤」和「業(yè)務(wù)邏輯錯(cuò)誤」分開(kāi)。4.1 用 curl 直接打 TaoToken APIcurl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有choices字段和正常內(nèi)容說(shuō)明 Key 和 base_url 都沒(méi)問(wèn)題。如果返回 401檢查 Key 是否注入成功返回 404檢查 base_url 路徑是否多了或少了/v1。4.2 用 Python 驗(yàn)證 Edict 配置加載在 Edict 項(xiàng)目根目錄下跑一段小腳本確認(rèn)配置文件能被正確解析import os, json, tomllib from pathlib import Path key os.environ.get(TAOTOKEN_API_KEY) assert key, TAOTOKEN_API_KEY 未注入 cfg_path Path(edict/backend/config.toml) if cfg_path.exists(): with cfg_path.open(rb) as f: cfg tomllib.load(f) print(toml base_url:, cfg[llm][base_url]) print(toml model:, cfg[llm][default_model]) s_path Path(data/settings.json) if s_path.exists(): s json.loads(s_path.read_text(encodingutf-8)) print(json base_url:, s[llm][base_url]) print(json key_env:, s[llm][api_key_env])跑通之后再啟動(dòng) Edict 的完整棧docker compose -f edict/docker-compose.yml up -d postgres redis 03_start_prod_stack.bat --open-browser --migrate啟動(dòng)后打開(kāi)看板http://127.0.0.1:7891新建一個(gè)任務(wù)觀察活動(dòng)流里 Agent 是否正常響應(yīng)。如果任務(wù)能推進(jìn)、日志里沒(méi)有 401/403說(shuō)明統(tǒng)一 Key 通道已經(jīng)生效。4.3 PyQt 啟動(dòng)器側(cè)的驗(yàn)證如果你擴(kuò)展了 PyQt 啟動(dòng)器在edict_pyqt_ui.py里加一個(gè)「測(cè)試連接」按鈕點(diǎn)擊后調(diào)用上面那段 curl 等價(jià)的請(qǐng)求把結(jié)果打到日志窗口。核心邏輯可以這樣寫(xiě)def test_connection(self): import os, requests key os.environ.get(TAOTOKEN_API_KEY) if not key: self.log([ERR] TAOTOKEN_API_KEY 未設(shè)置) return try: r requests.post( https://taotoken.net/api/v1/chat/completions, headers{Authorization: fBearer {key}}, json{model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16}, timeout30, ) self.log(f[OK] status{r.status_code}) except Exception as e: self.log(f[ERR] {e})這樣啟動(dòng)器就不只是啟停服務(wù)還能在啟動(dòng)前先確認(rèn)通道可用減少「服務(wù)起來(lái)了但 Agent 不工作」的排查時(shí)間。5. 本篇常見(jiàn)錯(cuò)排查配置階段最容易踩的坑集中在下面幾類按出現(xiàn)頻率排。第一類是 base_url 路徑錯(cuò)誤。TaoToken 的 API 入口是https://taotoken.net/api但實(shí)際調(diào)用 chat completions 時(shí)通常要帶/v1寫(xiě)成https://taotoken.net/api/v1。如果配置里只寫(xiě)了https://taotoken.net/api請(qǐng)求會(huì)打到錯(cuò)誤路徑返回 404。反過(guò)來(lái)如果某些 SDK 會(huì)自動(dòng)補(bǔ)/v1你手動(dòng)寫(xiě)了就會(huì)變成/v1/v1同樣 404。排查方法就是上面那段 curl直接看返回。第二類是 Key 注入失敗。Windows 下set只在當(dāng)前命令行窗口有效如果你在 A 窗口 set 了在 B 窗口啟動(dòng) Edict讀到的就是空值。更穩(wěn)妥的做法是寫(xiě)進(jìn)啟動(dòng)腳本或者用系統(tǒng)環(huán)境變量。PyQt 啟動(dòng)器如果是從桌面快捷方式啟動(dòng)繼承的環(huán)境變量可能和你終端里不一樣這也是為什么啟動(dòng)器里要保留彈窗輸入作為兜底。第三類是模型名拼寫(xiě)錯(cuò)誤。TaoToken 的模型標(biāo)識(shí)要用完整名稱簡(jiǎn)寫(xiě)或舊版本名會(huì)返回 model not found。在模型對(duì)話頁(yè)面里復(fù)制模型名不要手打。第四類是配置文件優(yōu)先級(jí)混亂。Edict 兩條主線如果同時(shí)存在 config.toml 和 settings.json要明確哪份生效。建議在服務(wù)啟動(dòng)日志里打印實(shí)際加載的配置路徑和 base_url一眼就能看出讀的是哪份。第五類是超時(shí)設(shè)置過(guò)短。Agent 調(diào)度涉及多輪調(diào)用timeout_seconds設(shè)成 10 秒很容易在復(fù)雜任務(wù)上超時(shí)。建議至少 60 秒重試次數(shù) 3 次。提示排查時(shí)先跑 curl再跑 Python 配置加載腳本最后才啟動(dòng)完整棧。順序反了會(huì)把配置問(wèn)題和業(yè)務(wù)問(wèn)題混在一起。6. 接入之后的下一步統(tǒng)一 Key 通道配好之后Edict 的擴(kuò)展工作就有了穩(wěn)定底座。接下來(lái)你可以按這個(gè)順序推進(jìn)先補(bǔ)一個(gè)業(yè)務(wù)面板走通「數(shù)據(jù)腳本 → 后端接口 → 前端組件」的完整鏈路再新增一個(gè) Agent在SOUL.md里定義職責(zé)在權(quán)限矩陣?yán)镒?cè)然后完善調(diào)度層的重試和升級(jí)策略讓任務(wù)卡住時(shí)能自動(dòng)恢復(fù)。如果你在接入過(guò)程中遇到 Key 或通道相關(guān)的問(wèn)題可以直接去 API Keys 頁(yè)面重新生成一個(gè) Key 對(duì)比測(cè)試排除是 Key 本身的問(wèn)題還是配置問(wèn)題。接入文檔里有各語(yǔ)言 SDK 的調(diào)用示例對(duì)照著改 Edict 里的請(qǐng)求封裝會(huì)快很多。長(zhǎng)期做編碼類 Agent 擴(kuò)展的話Coding Plan 的額度規(guī)劃也值得提前看一下避免開(kāi)發(fā)中途斷檔。配置這件事一次收口后面每次擴(kuò)展都省事。 【OpenClaw】Edict 三省六部制二開(kāi)與擴(kuò)展：TaoToken 統(tǒng)一 Key 接入配置骨架
1. 為什么二開(kāi)階段必須先把 Key 通道收口OpenClaw Edict 三省六部制這套系統(tǒng)前兩篇把部署啟動(dòng)和日常使用跑通之后真正進(jìn)入二次開(kāi)發(fā)時(shí)最先暴露的問(wèn)題往往不是代碼寫(xiě)不出來(lái)而是模型訪問(wèn)通道太散。根目錄看板主線里dashboard/server.py直接讀環(huán)境變量edict/backend的 FastAPI 服務(wù)層又有一套自己的配置加載邏輯PyQt 啟動(dòng)器里還單獨(dú)彈窗讓用戶輸入 API KeyAgent 的SOUL.md旁邊可能還掛著各自的模型配置。改一個(gè)模型要在四五個(gè)地方同步漏一處就出現(xiàn)「看板能跑、Worker 報(bào) 401」這種典型故障。這一篇聚焦的就是這個(gè)收口動(dòng)作把 TaoToken 作為統(tǒng)一 Key/API 通道在 Edict 的 config.toml 與 settings.json 兩個(gè)配置骨架里落地讓 PyQt 前端、Agent 調(diào)度層、FastAPI 服務(wù)層都從同一份配置讀取模型訪問(wèn)信息。適合已經(jīng)能跑起 Edict、準(zhǔn)備做面板擴(kuò)展、Agent 擴(kuò)展或調(diào)度改造的開(kāi)發(fā)者。讀完之后你應(yīng)該能完成一次可復(fù)制的連通性驗(yàn)證并且知道配置寫(xiě)錯(cuò)時(shí)該去哪個(gè)文件排查。TaoToken 在這里的角色是統(tǒng)一模型訪問(wèn)入口提供兼容 OpenAI 風(fēng)格的 API 通道Edict 各層只需要認(rèn)一個(gè) base_url 和一個(gè) key不用為每個(gè)模型供應(yīng)商單獨(dú)寫(xiě)適配。官網(wǎng)地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不帶 UTM 參數(shù)。2. TaoToken 前置準(zhǔn)備Key 與通道確認(rèn)在動(dòng) Edict 的配置文件之前先把 TaoToken 這邊的訪問(wèn)憑證準(zhǔn)備好。登錄后進(jìn)入控制臺(tái)在 API Keys 頁(yè)面創(chuàng)建一個(gè)新的 Key。建議按用途命名比如edict-dev、edict-prod這樣后面在 Edict 里做多環(huán)境配置時(shí)不會(huì)混。創(chuàng)建完 Key 之后你需要確認(rèn)兩件事一是 API base 地址二是可用模型列表。TaoToken 的 API 入口是https://taotoken.net/api在 Edict 的配置里通常寫(xiě)成https://taotoken.net/api/v1這種帶版本號(hào)的形式具體取決于你調(diào)用的接口路徑。模型列表可以在模型對(duì)話頁(yè)面里直接試確認(rèn)你要用的模型名拼寫(xiě)正確比如claude-sonnet-4-20250514這類完整標(biāo)識(shí)不要憑記憶寫(xiě)簡(jiǎn)寫(xiě)。如果你打算長(zhǎng)期在 Edict 上做編碼類 Agent 的擴(kuò)展可以順帶看一下 Coding Plan 的額度說(shuō)明避免開(kāi)發(fā)到一半發(fā)現(xiàn)調(diào)用量不夠。控制臺(tái)里能看到當(dāng)前 Key 的用量和剩余額度這個(gè)信息在排查「請(qǐng)求突然失敗」時(shí)很有用——有時(shí)候不是配置錯(cuò)了是額度用完了。注意Key 不要直接寫(xiě)進(jìn) Git 倉(cāng)庫(kù)里的配置文件。下面給的 config.toml 和 settings.json 骨架里Key 字段建議用環(huán)境變量占位實(shí)際運(yùn)行時(shí)由啟動(dòng)腳本注入。3. 可復(fù)制配置config.toml 與 settings.json 骨架Edict 的兩條主線對(duì)配置文件的讀取方式不一樣所以這里給兩份骨架你按自己改的那條線選用或者兩份都配上讓它們指向同一個(gè) Key。3.1 config.toml 骨架edict/backend 全棧線全棧線通常用 TOML 做服務(wù)層配置。在edict/backend/config.toml或項(xiàng)目約定的配置目錄下寫(xiě)入下面這段[llm] provider taotoken base_url https://taotoken.net/api/v1 api_key ${TAOTOKEN_API_KEY} default_model claude-sonnet-4-20250514 timeout_seconds 60 max_retries 3 [llm.models] zhongshu claude-sonnet-4-20250514 menxia claude-sonnet-4-20250514 shangshu claude-sonnet-4-20250514 worker_default claude-sonnet-4-20250514 [scheduler] retry_max 3 escalate_threshold_sec 180這里的關(guān)鍵點(diǎn)是api_key用${TAOTOKEN_API_KEY}占位實(shí)際值從環(huán)境變量讀。base_url指向 TaoToken 的 API 入口default_model和分角色模型都寫(xiě)完整模型名。[scheduler]段對(duì)應(yīng)后面調(diào)度擴(kuò)展會(huì)用到的重試和升級(jí)閾值。3.2 settings.json 骨架根目錄看板線 PyQt 啟動(dòng)器根目錄看板主線和 PyQt 啟動(dòng)器更習(xí)慣讀 JSON。在data/settings.json或啟動(dòng)器同級(jí)的配置目錄下寫(xiě){ llm: { provider: taotoken, base_url: https://taotoken.net/api/v1, api_key_env: TAOTOKEN_API_KEY, default_model: claude-sonnet-4-20250514 }, agents: { zhongshu: { model: claude-sonnet-4-20250514 }, menxia: { model: claude-sonnet-4-20250514 }, shangshu: { model: claude-sonnet-4-20250514 } }, launcher: { host: 127.0.0.1, port: 7891, log_dir: .runtime/prod/logs } }注意這里用的是api_key_env而不是直接存 KeyPyQt 啟動(dòng)器讀取時(shí)先查環(huán)境變量查不到再?gòu)棿白層脩襞R時(shí)輸入。這樣既保留了桌面入口的便利性又不會(huì)把密鑰落盤(pán)到源碼目錄。3.3 環(huán)境變量注入無(wú)論用哪份配置啟動(dòng)前都要把 Key 注入環(huán)境變量。Windows 下在啟動(dòng)腳本里加set TAOTOKEN_API_KEY你的KeyLinux/macOS 下export TAOTOKEN_API_KEY你的Key如果你用的是01_setup_prod_env.bat --sync這類引導(dǎo)腳本可以把這行加在腳本開(kāi)頭或者單獨(dú)寫(xiě)一個(gè)env.local.bat并在主腳本里call它避免 Key 進(jìn)入版本控制。4. 驗(yàn)證請(qǐng)求一次可復(fù)制的連通性檢查配置寫(xiě)完不要直接啟動(dòng)整個(gè) Edict先用一個(gè)最小請(qǐng)求確認(rèn)通道是通的。這一步能幫你把「配置錯(cuò)誤」和「業(yè)務(wù)邏輯錯(cuò)誤」分開(kāi)。4.1 用 curl 直接打 TaoToken APIcurl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有choices字段和正常內(nèi)容說(shuō)明 Key 和 base_url 都沒(méi)問(wèn)題。如果返回 401檢查 Key 是否注入成功返回 404檢查 base_url 路徑是否多了或少了/v1。4.2 用 Python 驗(yàn)證 Edict 配置加載在 Edict 項(xiàng)目根目錄下跑一段小腳本確認(rèn)配置文件能被正確解析import os, json, tomllib from pathlib import Path key os.environ.get(TAOTOKEN_API_KEY) assert key, TAOTOKEN_API_KEY 未注入 cfg_path Path(edict/backend/config.toml) if cfg_path.exists(): with cfg_path.open(rb) as f: cfg tomllib.load(f) print(toml base_url:, cfg[llm][base_url]) print(toml model:, cfg[llm][default_model]) s_path Path(data/settings.json) if s_path.exists(): s json.loads(s_path.read_text(encodingutf-8)) print(json base_url:, s[llm][base_url]) print(json key_env:, s[llm][api_key_env])跑通之后再啟動(dòng) Edict 的完整棧docker compose -f edict/docker-compose.yml up -d postgres redis 03_start_prod_stack.bat --open-browser --migrate啟動(dòng)后打開(kāi)看板http://127.0.0.1:7891新建一個(gè)任務(wù)觀察活動(dòng)流里 Agent 是否正常響應(yīng)。如果任務(wù)能推進(jìn)、日志里沒(méi)有 401/403說(shuō)明統(tǒng)一 Key 通道已經(jīng)生效。4.3 PyQt 啟動(dòng)器側(cè)的驗(yàn)證如果你擴(kuò)展了 PyQt 啟動(dòng)器在edict_pyqt_ui.py里加一個(gè)「測(cè)試連接」按鈕點(diǎn)擊后調(diào)用上面那段 curl 等價(jià)的請(qǐng)求把結(jié)果打到日志窗口。核心邏輯可以這樣寫(xiě)def test_connection(self): import os, requests key os.environ.get(TAOTOKEN_API_KEY) if not key: self.log([ERR] TAOTOKEN_API_KEY 未設(shè)置) return try: r requests.post( https://taotoken.net/api/v1/chat/completions, headers{Authorization: fBearer {key}}, json{model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 16}, timeout30, ) self.log(f[OK] status{r.status_code}) except Exception as e: self.log(f[ERR] {e})這樣啟動(dòng)器就不只是啟停服務(wù)還能在啟動(dòng)前先確認(rèn)通道可用減少「服務(wù)起來(lái)了但 Agent 不工作」的排查時(shí)間。5. 本篇常見(jiàn)錯(cuò)排查配置階段最容易踩的坑集中在下面幾類按出現(xiàn)頻率排。第一類是 base_url 路徑錯(cuò)誤。TaoToken 的 API 入口是https://taotoken.net/api但實(shí)際調(diào)用 chat completions 時(shí)通常要帶/v1寫(xiě)成https://taotoken.net/api/v1。如果配置里只寫(xiě)了https://taotoken.net/api請(qǐng)求會(huì)打到錯(cuò)誤路徑返回 404。反過(guò)來(lái)如果某些 SDK 會(huì)自動(dòng)補(bǔ)/v1你手動(dòng)寫(xiě)了就會(huì)變成/v1/v1同樣 404。排查方法就是上面那段 curl直接看返回。第二類是 Key 注入失敗。Windows 下set只在當(dāng)前命令行窗口有效如果你在 A 窗口 set 了在 B 窗口啟動(dòng) Edict讀到的就是空值。更穩(wěn)妥的做法是寫(xiě)進(jìn)啟動(dòng)腳本或者用系統(tǒng)環(huán)境變量。PyQt 啟動(dòng)器如果是從桌面快捷方式啟動(dòng)繼承的環(huán)境變量可能和你終端里不一樣這也是為什么啟動(dòng)器里要保留彈窗輸入作為兜底。第三類是模型名拼寫(xiě)錯(cuò)誤。TaoToken 的模型標(biāo)識(shí)要用完整名稱簡(jiǎn)寫(xiě)或舊版本名會(huì)返回 model not found。在模型對(duì)話頁(yè)面里復(fù)制模型名不要手打。第四類是配置文件優(yōu)先級(jí)混亂。Edict 兩條主線如果同時(shí)存在 config.toml 和 settings.json要明確哪份生效。建議在服務(wù)啟動(dòng)日志里打印實(shí)際加載的配置路徑和 base_url一眼就能看出讀的是哪份。第五類是超時(shí)設(shè)置過(guò)短。Agent 調(diào)度涉及多輪調(diào)用timeout_seconds設(shè)成 10 秒很容易在復(fù)雜任務(wù)上超時(shí)。建議至少 60 秒重試次數(shù) 3 次。提示排查時(shí)先跑 curl再跑 Python 配置加載腳本最后才啟動(dòng)完整棧。順序反了會(huì)把配置問(wèn)題和業(yè)務(wù)問(wèn)題混在一起。6. 接入之后的下一步統(tǒng)一 Key 通道配好之后Edict 的擴(kuò)展工作就有了穩(wěn)定底座。接下來(lái)你可以按這個(gè)順序推進(jìn)先補(bǔ)一個(gè)業(yè)務(wù)面板走通「數(shù)據(jù)腳本 → 后端接口 → 前端組件」的完整鏈路再新增一個(gè) Agent在SOUL.md里定義職責(zé)在權(quán)限矩陣?yán)镒?cè)然后完善調(diào)度層的重試和升級(jí)策略讓任務(wù)卡住時(shí)能自動(dòng)恢復(fù)。如果你在接入過(guò)程中遇到 Key 或通道相關(guān)的問(wèn)題可以直接去 API Keys 頁(yè)面重新生成一個(gè) Key 對(duì)比測(cè)試排除是 Key 本身的問(wèn)題還是配置問(wèn)題。接入文檔里有各語(yǔ)言 SDK 的調(diào)用示例對(duì)照著改 Edict 里的請(qǐng)求封裝會(huì)快很多。長(zhǎng)期做編碼類 Agent 擴(kuò)展的話Coding Plan 的額度規(guī)劃也值得提前看一下避免開(kāi)發(fā)中途斷檔。配置這件事一次收口后面每次擴(kuò)展都省事。