chore(i18n): refresh fa translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
0a3a5368d8
commit
21e78aaa1b
394
docs/fa/ci.md
394
docs/fa/ci.md
@ -1,94 +1,94 @@
|
||||
---
|
||||
read_when:
|
||||
- باید بدانید چرا یک کار یکپارچهسازی پیوسته اجرا شده یا نشده است
|
||||
- باید بدانید چرا یک کار CI اجرا شد یا نشد
|
||||
- شما در حال اشکالزدایی یک بررسی ناموفق GitHub Actions هستید
|
||||
- شما یک اجرای اعتبارسنجی انتشار یا اجرای مجدد آن را هماهنگ میکنید
|
||||
- در حال تغییر ارسال ClawSweeper یا بازارسال فعالیت GitHub هستید
|
||||
summary: نمودار کارهای یکپارچهسازی مداوم، گیتهای محدوده، چترهای انتشار، و معادلهای فرمان محلی
|
||||
- شما در حال هماهنگکردن اجرای اعتبارسنجی انتشار یا اجرای مجدد آن هستید
|
||||
- شما در حال تغییر ارسال ClawSweeper یا بازفرستی فعالیت GitHub هستید
|
||||
summary: گراف وظایف CI، دروازههای دامنه، چترهای انتشار، و معادلهای فرمانهای محلی
|
||||
title: خط لوله CI
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:18:14Z"
|
||||
generated_at: "2026-05-02T23:39:23Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: a8033b928b26adfa340200ea69fd63d339a6e65c21659b8119a68b23b8b16016
|
||||
source_hash: 321fe0a061044f75b8e1d03b4d3e76d4f8dd2dae0ebc58831887fc20af953cf1
|
||||
source_path: ci.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw CI روی هر push به `main` و هر pull request اجرا میشود. کار `preflight` diff را دستهبندی میکند و وقتی فقط بخشهای نامرتبط تغییر کردهاند، laneهای پرهزینه را خاموش میکند. اجراهای دستی `workflow_dispatch` عمدا از scoping هوشمند عبور میکنند و کل graph را برای release candidateها و اعتبارسنجی گسترده پخش میکنند. laneهای Android از طریق `include_android` همچنان opt-in میمانند. پوشش Plugin مختص release در workflow جداگانه [`Plugin Prerelease`](#plugin-prerelease) قرار دارد و فقط از [`Full Release Validation`](#full-release-validation) یا یک dispatch دستی صریح اجرا میشود.
|
||||
OpenClaw CI روی هر push به `main` و هر pull request اجرا میشود. job مربوط به `preflight`، diff را طبقهبندی میکند و وقتی فقط نواحی نامرتبط تغییر کرده باشند، laneهای پرهزینه را غیرفعال میکند. اجراهای دستی `workflow_dispatch` عمدا smart scoping را دور میزنند و کل graph را برای release candidateها و اعتبارسنجی گسترده پخش میکنند. laneهای Android از طریق `include_android` همچنان opt-in میمانند. پوشش Plugin مخصوص release فقط در workflow جداگانه [`Plugin Prerelease`](#plugin-prerelease) قرار دارد و فقط از [`Full Release Validation`](#full-release-validation) یا یک dispatch دستی صریح اجرا میشود.
|
||||
|
||||
## نمای کلی pipeline
|
||||
|
||||
| کار | هدف | زمان اجرا |
|
||||
| Job | هدف | زمان اجرا |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
|
||||
| `preflight` | تشخیص تغییرات فقط docs، scopeهای تغییرکرده، extensionهای تغییرکرده، و ساخت manifest مربوط به CI | همیشه روی pushها و PRهای غیر draft |
|
||||
| `preflight` | تشخیص تغییرات فقط مستندات، scopeهای تغییرکرده، extensionهای تغییرکرده، و ساخت CI manifest | همیشه روی pushها و PRهای غیر draft |
|
||||
| `security-scm-fast` | تشخیص کلید خصوصی و audit workflow از طریق `zizmor` | همیشه روی pushها و PRهای غیر draft |
|
||||
| `security-dependency-audit` | audit فایل lock تولیدی بدون dependency در برابر advisoryهای npm | همیشه روی pushها و PRهای غیر draft |
|
||||
| `security-fast` | aggregate الزامی برای کارهای امنیتی سریع | همیشه روی pushها و PRهای غیر draft |
|
||||
| `check-dependencies` | پاس فقط dependency تولیدی Knip بههمراه guard مربوط به allowlist فایلهای استفادهنشده | تغییرات مرتبط با Node |
|
||||
| `build-artifacts` | ساخت `dist/`، Control UI، بررسیهای built-artifact، و artifactهای downstream قابل استفادهمجدد | تغییرات مرتبط با Node |
|
||||
| `checks-fast-core` | laneهای صحتسنجی سریع Linux مانند بررسیهای bundled/plugin-contract/protocol | تغییرات مرتبط با Node |
|
||||
| `checks-fast-contracts-channels` | بررسیهای sharded قرارداد channel با یک نتیجه aggregate پایدار | تغییرات مرتبط با Node |
|
||||
| `security-dependency-audit` | audit بدون dependency برای production lockfile در برابر advisoryهای npm | همیشه روی pushها و PRهای غیر draft |
|
||||
| `security-fast` | aggregate الزامی برای jobهای امنیتی سریع | همیشه روی pushها و PRهای غیر draft |
|
||||
| `check-dependencies` | پاس production Knip فقط برای dependencyها بههمراه guard مربوط به allowlist فایلهای استفادهنشده | تغییرات مرتبط با Node |
|
||||
| `build-artifacts` | ساخت `dist/`، Control UI، بررسی built-artifactها، و artifactهای قابلاستفاده مجدد برای downstream | تغییرات مرتبط با Node |
|
||||
| `checks-fast-core` | laneهای سریع صحتسنجی Linux مانند بررسیهای bundled/plugin-contract/protocol | تغییرات مرتبط با Node |
|
||||
| `checks-fast-contracts-channels` | بررسیهای sharded برای channel contractها با نتیجه aggregate check پایدار | تغییرات مرتبط با Node |
|
||||
| `checks-node-core-test` | shardهای تست Core Node، بهجز laneهای channel، bundled، contract، و extension | تغییرات مرتبط با Node |
|
||||
| `check` | معادل local gate اصلی بهصورت sharded: prod types، lint، guards، test types، و strict smoke | تغییرات مرتبط با Node |
|
||||
| `check-additional` | معماری، boundary، drift در prompt snapshot، guardهای سطح extension، package-boundary، و shardهای gateway-watch | تغییرات مرتبط با Node |
|
||||
| `build-smoke` | تستهای smoke برای CLI ساختهشده و smoke مربوط به startup-memory | تغییرات مرتبط با Node |
|
||||
| `check` | معادل sharded برای gate محلی اصلی: production types، lint، guardها، test types، و smoke سختگیرانه | تغییرات مرتبط با Node |
|
||||
| `check-additional` | shardهای architecture، boundary، drift در prompt snapshot، guardهای extension-surface، package-boundary، و gateway-watch | تغییرات مرتبط با Node |
|
||||
| `build-smoke` | تستهای smoke برای built-CLI و smoke حافظه startup | تغییرات مرتبط با Node |
|
||||
| `checks` | verifier برای تستهای channel مربوط به built-artifact | تغییرات مرتبط با Node |
|
||||
| `checks-node-compat-node22` | lane ساخت و smoke سازگاری Node 22 | dispatch دستی CI برای releaseها |
|
||||
| `check-docs` | format، lint، و بررسی لینکهای شکسته در docs | تغییر docs |
|
||||
| `skills-python` | Ruff + pytest برای skillهای پشتیبانیشده با Python | تغییرات مرتبط با Python-skill |
|
||||
| `checks-windows` | تستهای مخصوص process/path در Windows بههمراه regressionهای shared runtime import specifier | تغییرات مرتبط با Windows |
|
||||
| `macos-node` | lane تست TypeScript روی macOS با استفاده از artifactهای ساختهشده shared | تغییرات مرتبط با macOS |
|
||||
| `macos-swift` | Swift lint، build، و تستها برای app macOS | تغییرات مرتبط با macOS |
|
||||
| `android` | تستهای واحد Android برای هر دو flavor بههمراه یک ساخت APK debug | تغییرات مرتبط با Android |
|
||||
| `test-performance-agent` | بهینهسازی روزانه تستهای کند Codex پس از فعالیت trusted | موفقیت CI روی main یا dispatch دستی |
|
||||
| `openclaw-performance` | گزارشهای عملکرد روزانه/درخواستی runtime Kova با laneهای mock-provider، deep-profile، و live مربوط به GPT 5.4 | زمانبندیشده و dispatch دستی |
|
||||
| `checks-node-compat-node22` | lane ساخت و smoke برای سازگاری Node 22 | dispatch دستی CI برای releaseها |
|
||||
| `check-docs` | قالببندی مستندات، lint، و بررسی لینکهای شکسته | مستندات تغییر کرده باشد |
|
||||
| `skills-python` | Ruff + pytest برای skillهای مبتنی بر Python | تغییرات مرتبط با Python-skill |
|
||||
| `checks-windows` | تستهای مخصوص process/path در Windows بههمراه رگرسیونهای مشترک runtime import specifier | تغییرات مرتبط با Windows |
|
||||
| `macos-node` | lane تست TypeScript در macOS با استفاده از built artifactهای مشترک | تغییرات مرتبط با macOS |
|
||||
| `macos-swift` | Swift lint، build، و تستها برای اپ macOS | تغییرات مرتبط با macOS |
|
||||
| `android` | تستهای unit در Android برای هر دو flavor بههمراه ساخت یک debug APK | تغییرات مرتبط با Android |
|
||||
| `test-performance-agent` | بهینهسازی روزانه slow-test توسط Codex پس از فعالیت trusted | موفقیت CI اصلی یا dispatch دستی |
|
||||
| `openclaw-performance` | گزارشهای روزانه/درخواستی عملکرد runtime مربوط به Kova با laneهای mock-provider، deep-profile، و live مربوط به GPT 5.4 | زمانبندیشده و dispatch دستی |
|
||||
|
||||
## ترتیب fail-fast
|
||||
|
||||
1. `preflight` تصمیم میگیرد اساسا کدام laneها وجود داشته باشند. منطق `docs-scope` و `changed-scope` مرحلههایی داخل همین کار هستند، نه کارهای مستقل.
|
||||
2. `security-scm-fast`، `security-dependency-audit`، `security-fast`، `check`، `check-additional`، `check-docs`، و `skills-python` بدون انتظار برای کارهای سنگینتر artifact و matrix پلتفرم، سریع fail میشوند.
|
||||
3. `build-artifacts` با laneهای سریع Linux همپوشانی دارد تا مصرفکنندههای downstream بهمحض آماده شدن build مشترک بتوانند شروع کنند.
|
||||
4. سپس laneهای سنگینتر platform و runtime پخش میشوند: `checks-fast-core`، `checks-fast-contracts-channels`، `checks-node-core-test`، `checks`، `checks-windows`، `macos-node`، `macos-swift`، و `android`.
|
||||
1. `preflight` تصمیم میگیرد اساسا کدام laneها وجود داشته باشند. منطق `docs-scope` و `changed-scope` stepهایی داخل همین job هستند، نه jobهای مستقل.
|
||||
2. `security-scm-fast`، `security-dependency-audit`، `security-fast`، `check`، `check-additional`، `check-docs`، و `skills-python` بدون انتظار برای jobهای سنگینتر artifact و platform matrix سریع fail میشوند.
|
||||
3. `build-artifacts` با laneهای سریع Linux همپوشانی دارد تا مصرفکنندگان downstream به محض آماده شدن build مشترک شروع شوند.
|
||||
4. پس از آن laneهای سنگینتر platform و runtime پخش میشوند: `checks-fast-core`، `checks-fast-contracts-channels`، `checks-node-core-test`، `checks`، `checks-windows`، `macos-node`، `macos-swift`، و `android`.
|
||||
|
||||
GitHub ممکن است وقتی push جدیدتری روی همان PR یا ref `main` میآید، کارهای superseded را بهصورت `cancelled` علامتگذاری کند. این را نویز CI در نظر بگیرید، مگر اینکه جدیدترین اجرا برای همان ref هم در حال fail شدن باشد. بررسیهای aggregate shard از `!cancelled() && always()` استفاده میکنند تا همچنان failureهای عادی shard را گزارش کنند، اما پس از آنکه کل workflow از قبل supersede شده است در صف نمانند. کلید concurrency خودکار CI نسخهگذاری شده است (`CI-v7-*`) تا یک zombie سمت GitHub در یک گروه صف قدیمی نتواند اجراهای جدیدتر main را برای مدت نامحدود block کند. اجراهای دستی full-suite از `CI-manual-v1-*` استفاده میکنند و اجراهای در حال انجام را cancel نمیکنند.
|
||||
وقتی یک push جدیدتر روی همان PR یا ref مربوط به `main` قرار میگیرد، GitHub ممکن است jobهای superseded را با وضعیت `cancelled` علامتگذاری کند. مگر اینکه جدیدترین run برای همان ref هم failing باشد، آن را noise مربوط به CI در نظر بگیرید. بررسیهای aggregate shard از `!cancelled() && always()` استفاده میکنند تا همچنان failهای عادی shard را گزارش کنند، اما پس از اینکه کل workflow از قبل superseded شده است در صف نمانند. کلید automatic CI concurrency نسخهگذاری شده است (`CI-v7-*`) تا یک zombie سمت GitHub در یک queue group قدیمی نتواند runهای جدیدتر main را برای مدت نامحدود block کند. اجراهای دستی full-suite از `CI-manual-v1-*` استفاده میکنند و runهای in-progress را cancel نمیکنند.
|
||||
|
||||
## Scope و routing
|
||||
|
||||
منطق scope در `scripts/ci-changed-scope.mjs` قرار دارد و با تستهای واحد در `src/scripts/ci-changed-scope.test.ts` پوشش داده شده است. dispatch دستی از تشخیص changed-scope عبور میکند و باعث میشود manifest مربوط به preflight طوری عمل کند که گویی هر بخش scoped تغییر کرده است.
|
||||
منطق scope در `scripts/ci-changed-scope.mjs` قرار دارد و با تستهای unit در `src/scripts/ci-changed-scope.test.ts` پوشش داده شده است. dispatch دستی، تشخیص changed-scope را رد میکند و باعث میشود preflight manifest طوری رفتار کند که انگار هر ناحیه scoped تغییر کرده است.
|
||||
|
||||
- **ویرایشهای workflow مربوط به CI** graph مربوط به Node CI را بههمراه workflow linting اعتبارسنجی میکنند، اما بهتنهایی buildهای native مربوط به Windows، Android، یا macOS را force نمیکنند؛ آن laneهای پلتفرم همچنان به تغییرات source همان پلتفرم scoped میمانند.
|
||||
- **ویرایشهای فقط routing در CI، ویرایشهای منتخب fixture ارزان core-test، و ویرایشهای محدود helper/test-routing مربوط به plugin contract** از یک مسیر manifest سریع فقط Node استفاده میکنند: `preflight`، security، و یک task واحد `checks-fast-core`. وقتی تغییر به سطحهای routing یا helper محدود باشد که task سریع مستقیما آنها را exercise میکند، آن مسیر artifactهای build، سازگاری Node 22، قراردادهای channel، shardهای کامل core، shardهای bundled-plugin، و matrixهای guard اضافی را skip میکند.
|
||||
- **بررسیهای Windows Node** به wrapperهای مخصوص process/path در Windows، helperهای runner مربوط به npm/pnpm/UI، config مربوط به package manager، و سطحهای workflow مربوط به CI که آن lane را اجرا میکنند scoped هستند؛ تغییرات نامرتبط source، plugin، install-smoke، و فقط test روی laneهای Linux Node میمانند.
|
||||
- **ویرایشهای CI workflow**، graph مربوط به Node CI را بههمراه workflow linting اعتبارسنجی میکنند، اما بهتنهایی buildهای native مربوط به Windows، Android، یا macOS را اجباری نمیکنند؛ آن laneهای platform همچنان به تغییرات source مربوط به platform scoped میمانند.
|
||||
- **ویرایشهای فقط CI routing، ویرایشهای منتخب fixture ارزان core-test، و ویرایشهای محدود helper/test-routing مربوط به plugin contract** از یک مسیر fast Node-only manifest استفاده میکنند: `preflight`، security، و یک task واحد `checks-fast-core`. وقتی تغییر به surfaceهای routing یا helper محدود باشد که task سریع مستقیما آنها را exercise میکند، آن مسیر build artifactها، سازگاری Node 22، channel contractها، shardهای کامل core، shardهای bundled-plugin، و matrixهای guard اضافی را رد میکند.
|
||||
- **بررسیهای Windows Node** به wrapperهای process/path مخصوص Windows، helperهای npm/pnpm/UI runner، پیکربندی package manager، و surfaceهای CI workflow که آن lane را اجرا میکنند scoped هستند؛ تغییرات نامرتبط source، Plugin، install-smoke، و فقط test روی laneهای Linux Node باقی میمانند.
|
||||
|
||||
کندترین خانوادههای تست Node split یا balance شدهاند تا هر کار بدون over-reserve کردن runnerها کوچک بماند: قراردادهای channel بهصورت سه shard وزندار اجرا میشوند، laneهای کوچک unit مربوط به core جفت شدهاند، auto-reply بهصورت چهار worker متوازن اجرا میشود (با subtree مربوط به reply که به shardهای agent-runner، dispatch، و commands/state-routing split شده است)، و configهای agentic gateway/plugin بهجای انتظار برای artifactهای ساختهشده، میان کارهای agentic Node موجود و فقط source پخش شدهاند. تستهای گسترده browser، QA، media، و pluginهای متفرقه بهجای catch-all مشترک plugin از configهای اختصاصی Vitest خود استفاده میکنند. shardهای include-pattern ورودیهای timing را با نام shard مربوط به CI ثبت میکنند، بنابراین `.artifacts/vitest-shard-timings.json` میتواند یک config کامل را از یک shard فیلترشده تشخیص دهد. `check-additional` کار compile/canary مربوط به package-boundary را کنار هم نگه میدارد و معماری runtime topology را از پوشش gateway watch جدا میکند؛ shard مربوط به boundary guard، guardهای کوچک مستقل خود را بهصورت concurrent داخل یک job اجرا میکند، از جمله `pnpm prompt:snapshots:check` تا drift مربوط به prompt مسیر happy-path در Codex به همان PR که باعث آن شده pin شود. Gateway watch، تستهای channel، و shard مربوط به core support-boundary پس از اینکه `dist/` و `dist-runtime/` از قبل ساخته شدند، بهصورت concurrent داخل `build-artifacts` اجرا میشوند.
|
||||
کندترین خانوادههای تست Node تقسیم یا متوازن شدهاند تا هر job بدون رزرو بیشازحد runner کوچک بماند: channel contractها بهصورت سه shard وزندار اجرا میشوند، laneهای unit کوچک core جفت شدهاند، auto-reply بهصورت چهار worker متوازن اجرا میشود (با subtree مربوط به reply که به shardهای agent-runner، dispatch، و commands/state-routing تقسیم شده است)، و configهای agentic مربوط به Gateway/Plugin بهجای انتظار برای built artifactها، در میان jobهای موجود source-only agentic Node پخش شدهاند. تستهای گسترده browser، QA، media، و Pluginهای متفرقه بهجای catch-all مشترک Plugin از configهای اختصاصی Vitest خودشان استفاده میکنند. shardهای include-pattern، entryهای timing را با نام CI shard ثبت میکنند، تا `.artifacts/vitest-shard-timings.json` بتواند یک config کامل را از یک shard فیلترشده تشخیص دهد. `check-additional` کار compile/canary مربوط به package-boundary را کنار هم نگه میدارد و runtime topology architecture را از پوشش gateway watch جدا میکند؛ shard مربوط به boundary guard، guardهای کوچک مستقل خود را بهصورت همزمان داخل یک job اجرا میکند، از جمله `pnpm prompt:snapshots:check` تا drift مربوط به prompt در مسیر happy-path runtime مربوط به Codex به همان PR که باعث آن شده pin شود. Gateway watch، تستهای channel، و shard مربوط به core support-boundary داخل `build-artifacts` پس از اینکه `dist/` و `dist-runtime/` از قبل ساخته شدند، همزمان اجرا میشوند.
|
||||
|
||||
Android CI هر دو `testPlayDebugUnitTest` و `testThirdPartyDebugUnitTest` را اجرا میکند و سپس APK debug مربوط به Play را میسازد. flavor شخص ثالث source set یا manifest جداگانه ندارد؛ lane تست واحد آن همچنان flavor را با flagهای BuildConfig مربوط به SMS/call-log compile میکند، در حالی که از یک کار تکراری packaging برای APK debug در هر push مرتبط با Android جلوگیری میکند.
|
||||
Android CI هر دو `testPlayDebugUnitTest` و `testThirdPartyDebugUnitTest` را اجرا میکند و سپس Play debug APK را میسازد. flavor مربوط به third-party هیچ source set یا manifest جداگانهای ندارد؛ lane مربوط به unit-test آن همچنان flavor را با flagهای BuildConfig مربوط به SMS/call-log کامپایل میکند، در حالی که از یک job تکراری برای packaging مربوط به debug APK روی هر push مرتبط با Android جلوگیری میکند.
|
||||
|
||||
shard مربوط به `check-dependencies` دستور `pnpm deadcode:dependencies` (یک پاس فقط dependency تولیدی Knip که به آخرین نسخه Knip pin شده و minimum release age مربوط به pnpm برای نصب `dlx` غیرفعال شده است) و `pnpm deadcode:unused-files` را اجرا میکند، که یافتههای production unused-file مربوط به Knip را با `scripts/deadcode-unused-files.allowlist.mjs` مقایسه میکند. guard مربوط به unused-file وقتی fail میشود که یک PR فایل استفادهنشده جدید و reviewنشده اضافه کند یا یک entry stale در allowlist باقی بگذارد، در حالی که سطحهای intentional dynamic plugin، generated، build، live-test، و package bridge را که Knip نمیتواند بهصورت static resolve کند حفظ میکند.
|
||||
shard مربوط به `check-dependencies`، `pnpm deadcode:dependencies` (یک پاس production Knip فقط برای dependencyها که به آخرین نسخه Knip pin شده است و minimum release age مربوط به pnpm برای نصب `dlx` غیرفعال است) و `pnpm deadcode:unused-files` را اجرا میکند؛ مورد دوم یافتههای Knip درباره فایلهای استفادهنشده production را با `scripts/deadcode-unused-files.allowlist.mjs` مقایسه میکند. guard مربوط به unused-file وقتی fail میشود که یک PR فایل استفادهنشده جدید و بازبینینشدهای اضافه کند یا یک entry stale در allowlist باقی بگذارد، در حالی که surfaceهای عمدی مربوط به dynamic plugin، generated، build، live-test، و package bridge را که Knip نمیتواند بهصورت static resolve کند حفظ میکند.
|
||||
|
||||
## forwarding فعالیت ClawSweeper
|
||||
## فوروارد کردن فعالیت ClawSweeper
|
||||
|
||||
`.github/workflows/clawsweeper-dispatch.yml` پل سمت target از فعالیت repository مربوط به OpenClaw به ClawSweeper است. این workflow کد pull request غیر trusted را checkout یا اجرا نمیکند. workflow از `CLAWSWEEPER_APP_PRIVATE_KEY` یک token برای GitHub App ایجاد میکند، سپس payloadهای compact مربوط به `repository_dispatch` را به `openclaw/clawsweeper` dispatch میکند.
|
||||
`.github/workflows/clawsweeper-dispatch.yml` پل سمت target از فعالیت repository مربوط به OpenClaw به ClawSweeper است. این workflow کد untrusted مربوط به pull request را check out یا اجرا نمیکند. workflow از `CLAWSWEEPER_APP_PRIVATE_KEY` یک GitHub App token میسازد، سپس payloadهای فشرده `repository_dispatch` را به `openclaw/clawsweeper` dispatch میکند.
|
||||
|
||||
این workflow چهار lane دارد:
|
||||
|
||||
- `clawsweeper_item` برای درخواستهای دقیق review مربوط به issue و pull request؛
|
||||
- `clawsweeper_comment` برای commandهای صریح ClawSweeper در commentهای issue؛
|
||||
- `clawsweeper_commit_review` برای درخواستهای review در سطح commit روی pushهای `main`؛
|
||||
- `github_activity` برای فعالیت عمومی GitHub که agent مربوط به ClawSweeper ممکن است بررسی کند.
|
||||
- `github_activity` برای فعالیت عمومی GitHub که agent مربوط به ClawSweeper ممکن است inspect کند.
|
||||
|
||||
lane مربوط به `github_activity` فقط metadata نرمالشده را forward میکند: نوع event، action، actor، repository، شماره item، URL، title، state، و excerptهای کوتاه برای commentها یا reviewها در صورت وجود. این lane عمدا از forward کردن بدنه کامل webhook پرهیز میکند. workflow دریافتکننده در `openclaw/clawsweeper` برابر `.github/workflows/github-activity.yml` است، که event نرمالشده را برای hook مربوط به OpenClaw Gateway برای agent مربوط به ClawSweeper post میکند.
|
||||
lane مربوط به `github_activity` فقط metadata نرمالشده را فوروارد میکند: event type، action، actor، repository، item number، URL، title، state، و excerptهای کوتاه برای commentها یا reviewها در صورت وجود. این lane عمدا از فوروارد کردن کل webhook body پرهیز میکند. workflow گیرنده در `openclaw/clawsweeper` برابر با `.github/workflows/github-activity.yml` است، که event نرمالشده را برای agent مربوط به ClawSweeper به OpenClaw Gateway hook ارسال میکند.
|
||||
|
||||
فعالیت عمومی observation است، نه delivery-by-default. agent مربوط به ClawSweeper هدف Discord را در prompt خود دریافت میکند و باید فقط وقتی event غیرمنتظره، قابل اقدام، پرریسک، یا از نظر عملیاتی مفید است به `#clawsweeper` post کند. باز شدنهای routine، ویرایشها، churn مربوط به bot، نویز webhook تکراری، و ترافیک عادی review باید به `NO_REPLY` منجر شوند.
|
||||
فعالیت عمومی observation است، نه delivery-by-default. agent مربوط به ClawSweeper هدف Discord را در prompt خود دریافت میکند و فقط وقتی باید به `#clawsweeper` پست کند که event غافلگیرکننده، قابل اقدام، پرریسک، یا از نظر عملیاتی مفید باشد. openها و editهای routine، churn مربوط به bot، noise ناشی از webhook تکراری، و traffic عادی review باید به `NO_REPLY` منجر شوند.
|
||||
|
||||
titleها، commentها، bodyها، متن review، نام branchها، و پیامهای commit در GitHub را در سراسر این مسیر بهعنوان داده غیر trusted در نظر بگیرید. آنها input برای summarization و triage هستند، نه دستور برای workflow یا runtime مربوط به agent.
|
||||
در سراسر این مسیر، titleها، commentها، bodyها، متن review، نام branchها، و commit messageهای GitHub را داده untrusted تلقی کنید. آنها ورودی summarization و triage هستند، نه instruction برای workflow یا runtime مربوط به agent.
|
||||
|
||||
## dispatchهای دستی
|
||||
|
||||
اجرای دستی CI همان گراف job معمول CI را اجرا میکند، اما هر lane محدودهدار غیر Android را فعال میکند: شاردهای Linux Node، شاردهای Plugin همراه، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسیهای مستندات، Python skills، Windows، macOS، و i18n رابط کاربری کنترل. اجرای دستی مستقل CI فقط Android را با `include_android=true` اجرا میکند؛ چتر کامل انتشار با پاسدادن `include_android=true`، Android را فعال میکند. بررسیهای ایستای پیشانتشار Plugin، شارد فقط-انتشار `agentic-plugins`، sweep کامل دستهای افزونهها، و laneهای Docker پیشانتشار Plugin از CI حذف شدهاند. مجموعه پیشانتشار Docker فقط زمانی اجرا میشود که `Full Release Validation` گردشکار جداگانه `Plugin Prerelease` را با gate اعتبارسنجی انتشار فعال dispatch کند.
|
||||
اجرای دستی CI همان گراف کارِ CI معمولی را اجرا میکند، اما همهٔ laneهای scoped غیر Android را روشن میکند: شاردهای Linux Node، شاردهای Plugin بستهبندیشده، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، smoke ساخت، بررسیهای مستندات، Python skills، Windows، macOS، و i18n در Control UI. اجرای دستی مستقل CI فقط Android را با `include_android=true` اجرا میکند؛ چتر کامل انتشار با ارسال `include_android=true`، Android را فعال میکند. بررسیهای ایستای پیشانتشار Plugin، شارد فقط-انتشارِ `agentic-plugins`، sweep کامل batch برای extensionها، و laneهای Docker پیشانتشار Plugin از CI کنار گذاشته شدهاند. مجموعهٔ پیشانتشار Docker فقط زمانی اجرا میشود که `Full Release Validation` گردشکار جداگانهٔ `Plugin Prerelease` را با gate اعتبارسنجی انتشار فعال dispatch کند.
|
||||
|
||||
اجراهای دستی از یک گروه همزمانی یکتا استفاده میکنند تا مجموعه کامل release-candidate با اجرای push یا PR دیگری روی همان ref لغو نشود. ورودی اختیاری `target_ref` به یک فراخواننده معتمد اجازه میدهد آن گراف را روی یک شاخه، tag، یا SHA کامل commit اجرا کند، در حالی که از فایل workflow مربوط به dispatch ref انتخابشده استفاده میشود.
|
||||
اجرای دستی از یک گروه concurrency یکتا استفاده میکند تا مجموعهٔ کامل release-candidate با اجرای push یا PR دیگری روی همان ref لغو نشود. ورودی اختیاری `target_ref` به فراخوانندهٔ مورد اعتماد اجازه میدهد آن گراف را روی یک branch، tag، یا SHA کامل commit اجرا کند، در حالی که فایل workflow از ref انتخابشدهٔ dispatch استفاده میشود.
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref release/YYYY.M.D
|
||||
@ -96,17 +96,17 @@ gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_andro
|
||||
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
|
||||
```
|
||||
|
||||
## Runnerها
|
||||
## اجراکنندهها
|
||||
|
||||
| Runner | Jobها |
|
||||
| اجراکننده | کارها |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`، jobهای امنیتی سریع و تجمیعکنندهها (`security-scm-fast`، `security-dependency-audit`، `security-fast`)، بررسیهای سریع پروتکل/قرارداد/همراه، بررسیهای شاردشده قرارداد کانال، شاردهای `check` بهجز lint، شاردها و تجمیعکنندههای `check-additional`، تأییدکنندههای تجمیعی تست Node، بررسیهای مستندات، Python skills، workflow-sanity، labeler، auto-response؛ preflight مربوط به install-smoke نیز از Ubuntu میزبانیشده GitHub استفاده میکند تا ماتریس Blacksmith زودتر بتواند صف شود |
|
||||
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`، شاردهای سبکتر افزونه، `checks-fast-core`، `checks-node-compat-node22`، `check-prod-types`، و `check-test-types` |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، build-smoke، شاردهای تست Linux Node، شاردهای تست Plugin همراه، `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (بهاندازهای حساس به CPU است که 8 vCPU بیشتر از صرفهجوییاش هزینه داشت)؛ ساختهای Docker مربوط به install-smoke (زمان صف 32-vCPU بیشتر از صرفهجوییاش هزینه داشت) |
|
||||
| `ubuntu-24.04` | `preflight`، کارهای امنیتی سریع و aggregateها (`security-scm-fast`، `security-dependency-audit`، `security-fast`)، بررسیهای سریع پروتکل/قرارداد/بستهبندیشده، بررسیهای sharded قرارداد کانال، شاردهای `check` بهجز lint، شاردها و aggregateهای `check-additional`، اعتبارسنجهای aggregate تست Node، بررسیهای مستندات، Python skills، workflow-sanity، labeler، auto-response؛ preflight مربوط به install-smoke نیز از Ubuntu میزبانیشده در GitHub استفاده میکند تا ماتریس Blacksmith زودتر بتواند در صف قرار بگیرد |
|
||||
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`، شاردهای extension سبکتر، `checks-fast-core`، `checks-node-compat-node22`، `check-prod-types`، و `check-test-types` |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`، build-smoke، شاردهای تست Linux Node، شاردهای تست Plugin بستهبندیشده، `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (آنقدر به CPU حساس است که 8 vCPU بیش از آنچه صرفهجویی کند هزینه داشت)؛ ساختهای Docker برای install-smoke (زمان صف 32-vCPU بیش از آنچه صرفهجویی کند هزینه داشت) |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` روی `openclaw/openclaw`؛ forkها به `macos-latest` برمیگردند |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` روی `openclaw/openclaw`؛ forkها به `macos-latest` برمیگردند |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` روی `openclaw/openclaw`؛ forkها به `macos-latest` fallback میکنند |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` روی `openclaw/openclaw`؛ forkها به `macos-latest` fallback میکنند |
|
||||
|
||||
## معادلهای محلی
|
||||
|
||||
@ -137,30 +137,30 @@ pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.jso
|
||||
|
||||
## عملکرد OpenClaw
|
||||
|
||||
`OpenClaw Performance` workflow عملکرد محصول/runtime است. این workflow هر روز روی `main` اجرا میشود و میتوان آن را بهصورت دستی dispatch کرد:
|
||||
`OpenClaw Performance` گردشکار عملکرد محصول/زمان اجرا است. این workflow هر روز روی `main` اجرا میشود و میتواند بهصورت دستی dispatch شود:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3
|
||||
gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 -f deep_profile=true -f live_gpt54=true
|
||||
```
|
||||
|
||||
این workflow، OCM را از یک انتشار pinشده و Kova را از ورودی pinشده `kova_ref` نصب میکند، سپس سه lane را اجرا میکند:
|
||||
این workflow، OCM را از یک release پینشده و Kova را از ورودی پینشدهٔ `kova_ref` نصب میکند، سپس سه lane را اجرا میکند:
|
||||
|
||||
- `mock-provider`: سناریوهای diagnostic Kova در برابر runtime ساخت محلی با احراز هویت جعلی قطعی و سازگار با OpenAI.
|
||||
- `mock-deep-profile`: profileگیری CPU/heap/trace برای نقاط داغ startup، Gateway، و agent-turn.
|
||||
- `live-gpt54`: یک turn واقعی عامل OpenAI `openai/gpt-5.4`، که وقتی `OPENAI_API_KEY` در دسترس نباشد رد میشود.
|
||||
- `mock-deep-profile`: پروفایلگیری CPU/heap/trace برای نقاط داغ startup، gateway، و agent-turn.
|
||||
- `live-gpt54`: یک agent turn واقعی OpenAI `openai/gpt-5.4` که وقتی `OPENAI_API_KEY` در دسترس نباشد skipped میشود.
|
||||
|
||||
lane مربوط به mock-provider پس از گذر Kova، probeهای منبع بومی OpenClaw را نیز اجرا میکند: زمانبندی boot و حافظه Gateway در حالتهای startup پیشفرض، hook، و 50-Plugin؛ حلقههای تکرارشونده hello با mock-OpenAI `channel-chat-baseline`؛ و فرمانهای startup مربوط به CLI در برابر Gateway bootشده. خلاصه Markdown probe منبع در بسته گزارش، در `source/index.md` قرار دارد و JSON خام کنار آن است.
|
||||
lane مربوط به mock-provider همچنین پس از گذر Kova، probeهای سورس بومی OpenClaw را اجرا میکند: زمان boot و حافظهٔ Gateway در حالتهای startup پیشفرض، hook، و 50-Plugin؛ loopهای hello تکرارشوندهٔ mock-OpenAI `channel-chat-baseline`؛ و فرمانهای startup در CLI در برابر Gateway راهاندازیشده. خلاصهٔ Markdown مربوط به source probe در bundle گزارش، در `source/index.md` قرار دارد و JSON خام کنار آن است.
|
||||
|
||||
هر lane artifactهای GitHub را upload میکند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md`، و artifactهای source-probe را زیر `openclaw-performance/<ref>/<run-id>-<attempt>/<lane>/` در `openclaw/clawgrit-reports` commit میکند. اشارهگر شاخه فعلی بهصورت `openclaw-performance/<ref>/latest-<lane>.json` نوشته میشود.
|
||||
هر lane artifactهای GitHub را upload میکند. وقتی `CLAWGRIT_REPORTS_TOKEN` پیکربندی شده باشد، workflow همچنین `report.json`، `report.md`، bundleها، `index.md`، و artifactهای source-probe را در `openclaw/clawgrit-reports` زیر `openclaw-performance/<ref>/<run-id>-<attempt>/<lane>/` commit میکند. اشارهگر branch فعلی بهصورت `openclaw-performance/<ref>/latest-<lane>.json` نوشته میشود.
|
||||
|
||||
## اعتبارسنجی کامل انتشار
|
||||
|
||||
`Full Release Validation` workflow چتری دستی برای «اجرای همهچیز قبل از انتشار» است. این workflow یک شاخه، tag، یا SHA کامل commit را میپذیرد، workflow دستی `CI` را با آن target dispatch میکند، `Plugin Prerelease` را برای اثبات فقط-انتشار مربوط به Plugin/package/static/Docker dispatch میکند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، suiteهای مسیر انتشار Docker، live/E2E، OpenWebUI، همترازی QA Lab، Matrix، و laneهای Telegram dispatch میکند. با `rerun_group=all` و `release_profile=full`، همچنین `NPM Telegram Beta E2E` را در برابر artifact به نام `release-package-under-test` از release checks اجرا میکند. پس از انتشار، `npm_telegram_package_spec` را پاس دهید تا همان lane بسته Telegram را در برابر بسته npm منتشرشده دوباره اجرا کند.
|
||||
`Full Release Validation` workflow چتری دستی برای «اجرای همهچیز پیش از انتشار» است. یک branch، tag، یا SHA کامل commit را میپذیرد، workflow دستی `CI` را با آن target dispatch میکند، `Plugin Prerelease` را برای اثبات فقط-انتشارِ Plugin/package/static/Docker dispatch میکند، و `OpenClaw Release Checks` را برای install smoke، پذیرش package، مجموعههای مسیر انتشار Docker، live/E2E، OpenWebUI، همارزی QA Lab، Matrix، و laneهای Telegram dispatch میکند. با `rerun_group=all` و `release_profile=full`، همچنین `NPM Telegram Beta E2E` را در برابر artifact مربوط به `release-package-under-test` از release checks اجرا میکند. پس از انتشار، `npm_telegram_package_spec` را ارسال کنید تا همان lane پکیج Telegram را در برابر پکیج npm منتشرشده دوباره اجرا کند.
|
||||
|
||||
برای ماتریس stage، نام دقیق jobهای workflow، تفاوت profileها، artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید.
|
||||
برای ماتریس stage، نام دقیق jobهای workflow، تفاوتهای profile، artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید.
|
||||
|
||||
`OpenClaw Release Publish` workflow انتشار دستی و تغییردهنده است. پس از وجود داشتن tag انتشار و پس از موفقیت preflight مربوط به npm OpenClaw، آن را از `release/YYYY.M.D` یا `main` dispatch کنید. این workflow، `pnpm plugins:sync:check` را تأیید میکند، `Plugin NPM Release` را برای همه بستههای Plugin قابل انتشار dispatch میکند، `Plugin ClawHub Release` را برای همان SHA انتشار dispatch میکند، و فقط پس از آن `OpenClaw NPM Release` را با `preflight_run_id` ذخیرهشده dispatch میکند.
|
||||
`OpenClaw Release Publish` workflow دستی تغییردهندهٔ انتشار است. آن را پس از وجود داشتن tag انتشار و پس از موفقیت preflight مربوط به npm در OpenClaw، از `release/YYYY.M.D` یا `main` dispatch کنید. این workflow، `pnpm plugins:sync:check` را verify میکند، `Plugin NPM Release` را برای همهٔ پکیجهای Plugin قابل انتشار dispatch میکند، `Plugin ClawHub Release` را برای همان SHA انتشار dispatch میکند، و فقط پس از آن `OpenClaw NPM Release` را با `preflight_run_id` ذخیرهشده dispatch میکند.
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -170,35 +170,35 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
برای اثبات commit pinشده روی شاخهای که سریع حرکت میکند، بهجای `gh workflow run ... --ref main -f ref=<sha>` از helper استفاده کنید:
|
||||
برای اثبات commit پینشده روی branch پرتحرک، بهجای `gh workflow run ... --ref main -f ref=<sha>` از helper استفاده کنید:
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
dispatch refهای workflow در GitHub باید شاخه یا tag باشند، نه SHA خام commit. helper یک شاخه موقت `release-ci/<sha>-...` را در SHA هدف push میکند، `Full Release Validation` را از همان ref pinشده dispatch میکند، تأیید میکند که `headSha` هر workflow فرزند با target مطابقت دارد، و پس از کاملشدن اجرا شاخه موقت را حذف میکند. verifier چتری همچنین اگر هر workflow فرزند با SHA متفاوتی اجرا شده باشد fail میشود.
|
||||
refهای dispatch در workflowهای GitHub باید branch یا tag باشند، نه SHA خام commit. این helper یک branch موقت `release-ci/<sha>-...` را در SHA هدف push میکند، `Full Release Validation` را از آن ref پینشده dispatch میکند، verify میکند که `headSha` هر workflow فرزند با target مطابقت دارد، و وقتی run کامل شد branch موقت را حذف میکند. verifier چتری همچنین اگر هر workflow فرزند در SHA متفاوتی اجرا شده باشد fail میشود.
|
||||
|
||||
`release_profile` گستره live/provider پاسدادهشده به release checks را کنترل میکند. workflowهای دستی انتشار بهصورت پیشفرض `stable` هستند؛ فقط زمانی از `full` استفاده کنید که عمدا ماتریس advisory گسترده provider/media را میخواهید.
|
||||
`release_profile` گسترهٔ live/provider ارسالشده به release checks را کنترل میکند. workflowهای دستی release بهصورت پیشفرض روی `stable` هستند؛ فقط وقتی عمداً ماتریس advisory provider/media گسترده را میخواهید از `full` استفاده کنید.
|
||||
|
||||
- `minimum` سریعترین laneهای OpenAI/core حیاتی برای انتشار را نگه میدارد.
|
||||
- `stable` مجموعه پایدار provider/backend را اضافه میکند.
|
||||
- `full` ماتریس advisory گسترده provider/media را اجرا میکند.
|
||||
- `minimum` سریعترین laneهای حیاتی انتشار OpenAI/core را نگه میدارد.
|
||||
- `stable` مجموعهٔ provider/backend پایدار را اضافه میکند.
|
||||
- `full` ماتریس advisory provider/media گسترده را اجرا میکند.
|
||||
|
||||
چتر، run idهای فرزند dispatchشده را ثبت میکند، و job نهایی `Verify full validation` نتیجههای فعلی run فرزند را دوباره بررسی میکند و جدولهای کندترین job را برای هر run فرزند اضافه میکند. اگر یک workflow فرزند دوباره اجرا شود و سبز شود، فقط job verifier والد را rerun کنید تا نتیجه چتری و خلاصه زمانبندی refresh شود.
|
||||
چتر، idهای run فرزند dispatchشده را ثبت میکند، و job نهایی `Verify full validation` نتیجههای فعلی runهای فرزند را دوباره بررسی میکند و جدولهای کندترین job را برای هر run فرزند ضمیمه میکند. اگر یک workflow فرزند دوباره اجرا شود و سبز شود، فقط job verifier والد را rerun کنید تا نتیجهٔ چتر و خلاصهٔ زمانبندی refresh شود.
|
||||
|
||||
برای بازیابی، هر دو `Full Release Validation` و `OpenClaw Release Checks` مقدار `rerun_group` را میپذیرند. برای یک نامزد انتشار از `all`، فقط برای فرزند CI کامل عادی از `ci`، فقط برای فرزند پیشانتشار Plugin از `plugin-prerelease`، برای همه فرزندان انتشار از `release-checks`، یا از یک گروه محدودتر استفاده کنید: `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، یا `npm-telegram` روی چتر. این باعث میشود اجرای دوباره یک جعبه انتشار شکستخورده پس از یک اصلاح متمرکز، محدود بماند.
|
||||
برای بازیابی، هر دو `Full Release Validation` و `OpenClaw Release Checks` مقدار `rerun_group` را میپذیرند. برای یک نامزد انتشار از `all` استفاده کنید، برای فقط فرزند CI کامل معمولی از `ci`، برای فقط فرزند پیشانتشار Plugin از `plugin-prerelease`، برای هر فرزند انتشار از `release-checks`، یا از یک گروه محدودتر استفاده کنید: `install-smoke`، `cross-os`، `live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، یا `npm-telegram` روی چتر. این کار اجرای دوباره یک جعبه انتشار ناموفق را پس از یک اصلاح متمرکز، محدود نگه میدارد.
|
||||
|
||||
`OpenClaw Release Checks` از ref گردشکار قابل اعتماد استفاده میکند تا ref انتخابشده را یکبار به یک tarball به نام `release-package-under-test` تبدیل کند، سپس آن artifact را هم به گردشکار Docker مسیر انتشار live/E2E و هم به شارد پذیرش بسته میدهد. این کار بایتهای بسته را در سراسر جعبههای انتشار یکسان نگه میدارد و از بستهبندی دوباره همان نامزد در چند job فرزند جلوگیری میکند.
|
||||
`OpenClaw Release Checks` از مرجع گردشکار قابل اعتماد استفاده میکند تا مرجع انتخابشده را یکبار به یک tarball به نام `release-package-under-test` تبدیل کند، سپس آن artifact را هم به گردشکار Docker مسیر انتشار زنده/E2E و هم به shard پذیرش بسته میدهد. این کار بایتهای بسته را در جعبههای انتشار یکسان نگه میدارد و از بستهبندی دوباره همان نامزد در چندین job فرزند جلوگیری میکند.
|
||||
|
||||
اجراهای تکراری `Full Release Validation` برای `ref=main` و `rerun_group=all`
|
||||
چتر قدیمیتر را supersede میکنند. مانیتور والد هر گردشکار فرزندی را که
|
||||
قبلا dispatch کرده باشد هنگام لغو والد لغو میکند، بنابراین اعتبارسنجی جدیدتر main
|
||||
پشت یک اجرای کهنه دو ساعته release-check نمیماند. اعتبارسنجی شاخه/برچسب انتشار
|
||||
و گروههای اجرای دوباره متمرکز، `cancel-in-progress: false` را نگه میدارند.
|
||||
چتر قدیمیتر را جایگزین میکنند. پایشگر والد، هر گردشکار فرزندی را که
|
||||
قبلا ارسال کرده است هنگام لغو والد لغو میکند، بنابراین اعتبارسنجی جدیدتر main
|
||||
پشت یک اجرای دو ساعته قدیمی release-check منتظر نمیماند. اعتبارسنجی شاخه/تگ انتشار
|
||||
و گروههای اجرای دوباره متمرکز، `cancel-in-progress: false` را حفظ میکنند.
|
||||
|
||||
## شاردهای live و E2E
|
||||
## Shardهای زنده و E2E
|
||||
|
||||
فرزند release live/E2E پوشش گسترده بومی `pnpm test:live` را نگه میدارد، اما آن را بهجای یک job سریالی، بهصورت شاردهای نامگذاریشده از طریق `scripts/test-live-shard.mjs` اجرا میکند:
|
||||
فرزند زنده/E2E انتشار، پوشش گسترده native `pnpm test:live` را حفظ میکند، اما آن را به جای یک job سریالی، بهصورت shardهای نامگذاریشده از طریق `scripts/test-live-shard.mjs` اجرا میکند:
|
||||
|
||||
- `native-live-src-agents`
|
||||
- `native-live-src-gateway-core`
|
||||
@ -210,61 +210,61 @@ dispatch refهای workflow در GitHub باید شاخه یا tag باشند،
|
||||
- `native-live-extensions-openai`
|
||||
- `native-live-extensions-o-z-other`
|
||||
- `native-live-extensions-xai`
|
||||
- شاردهای جداگانه صوت/ویدئوی media و شاردهای music فیلترشده بر اساس provider
|
||||
- shardهای جداشده صوت/ویدئوی رسانه و shardهای موسیقی فیلترشده بر اساس provider
|
||||
|
||||
این همان پوشش فایل را حفظ میکند و در عین حال اجرای دوباره و عیبیابی شکستهای کند providerهای live را آسانتر میکند. نام شاردهای تجمیعی `native-live-extensions-o-z`، `native-live-extensions-media` و `native-live-extensions-media-music` همچنان برای اجرای دوباره دستی یکباره معتبر میمانند.
|
||||
این کار همان پوشش فایل را حفظ میکند و در عین حال اجرای دوباره و تشخیص خرابیهای کند provider زنده را آسانتر میسازد. نامهای shard تجمیعی `native-live-extensions-o-z`، `native-live-extensions-media`، و `native-live-extensions-media-music` همچنان برای اجرای دوباره دستی یکباره معتبر میمانند.
|
||||
|
||||
شاردهای media بومی live در `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` اجرا میشوند که توسط گردشکار `Live Media Runner Image` ساخته میشود. آن image، `ffmpeg` و `ffprobe` را از قبل نصب میکند؛ jobهای media فقط پیش از راهاندازی، وجود binaryها را بررسی میکنند. مجموعههای live متکی بر Docker را روی runnerهای عادی Blacksmith نگه دارید — jobهای container جای مناسبی برای اجرای تستهای Docker تودرتو نیستند.
|
||||
Shardهای رسانه زنده native در `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04` اجرا میشوند که توسط گردشکار `Live Media Runner Image` ساخته شده است. آن image، `ffmpeg` و `ffprobe` را از پیش نصب میکند؛ jobهای رسانه فقط پیش از راهاندازی، باینریها را تأیید میکنند. مجموعههای زنده متکی به Docker را روی runnerهای معمول Blacksmith نگه دارید — jobهای container جای درستی برای اجرای تستهای Docker تو در تو نیستند.
|
||||
|
||||
شاردهای live مدل/backend متکی بر Docker از یک image مشترک جداگانه `ghcr.io/openclaw/openclaw-live-test:<sha>` برای هر commit انتخابشده استفاده میکنند. گردشکار release live آن image را یکبار میسازد و push میکند، سپس شاردهای مدل live Docker، Gateway شاردشده بر اساس provider، backend CLI، اتصال ACP، و harness کدکس با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا میشوند. شاردهای Docker مربوط به Gateway سقفهای `timeout` صریح در سطح script دارند که پایینتر از timeout job گردشکار است، تا یک container گیرکرده یا مسیر cleanup بهجای مصرف کل بودجه release-check سریع شکست بخورد. اگر آن شاردها هدف Docker کامل source را مستقل دوباره بسازند، اجرای release نادرست پیکربندی شده است و زمان wall clock را برای buildهای image تکراری هدر میدهد.
|
||||
Shardهای زنده model/backend متکی به Docker برای هر commit انتخابشده از یک image مشترک جداگانه `ghcr.io/openclaw/openclaw-live-test:<sha>` استفاده میکنند. گردشکار انتشار زنده، آن image را یکبار میسازد و push میکند، سپس shardهای مدل زنده Docker، Gateway تقسیمشده بر اساس provider، backend CLI، bind مربوط به ACP، و harness مربوط به Codex با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا میشوند. Shardهای Docker مربوط به Gateway سقفهای `timeout` صریح در سطح اسکریپت دارند که پایینتر از timeout job گردشکار است، تا یک container گیرکرده یا مسیر پاکسازی، به جای مصرف کل بودجه release-check، سریع fail شود. اگر آن shardها target کامل Docker منبع را مستقل بازسازی کنند، اجرای انتشار بدپیکربندی شده و زمان واقعی را صرف ساختهای تکراری image خواهد کرد.
|
||||
|
||||
## پذیرش بسته
|
||||
|
||||
وقتی پرسش این است که «آیا این بسته قابل نصب OpenClaw بهعنوان یک محصول کار میکند؟» از `Package Acceptance` استفاده کنید. این با CI عادی فرق دارد: CI عادی source tree را اعتبارسنجی میکند، در حالی که پذیرش بسته یک tarball واحد را از طریق همان harness Docker E2E که کاربران پس از نصب یا بهروزرسانی اجرا میکنند اعتبارسنجی میکند.
|
||||
از `Package Acceptance` زمانی استفاده کنید که پرسش این است: «آیا این بسته نصبشدنی OpenClaw بهعنوان یک محصول کار میکند؟» این با CI معمولی متفاوت است: CI معمولی درخت منبع را اعتبارسنجی میکند، در حالی که پذیرش بسته یک tarball واحد را از طریق همان harness Docker E2E اعتبارسنجی میکند که کاربران پس از نصب یا بهروزرسانی اجرا میکنند.
|
||||
|
||||
### jobها
|
||||
### Jobها
|
||||
|
||||
1. `resolve_package` مقدار `workflow_ref` را checkout میکند، یک نامزد بسته را resolve میکند، `.artifacts/docker-e2e-package/openclaw-current.tgz` را مینویسد، `.artifacts/docker-e2e-package/package-candidate.json` را مینویسد، هر دو را بهعنوان artifact `package-under-test` آپلود میکند، و منبع، ref گردشکار، ref بسته، نسخه، SHA-256، و پروفایل را در خلاصه step گیتهاب چاپ میکند.
|
||||
2. `docker_acceptance`، `openclaw-live-and-e2e-checks-reusable.yml` را با `ref=workflow_ref` و `package_artifact_name=package-under-test` فراخوانی میکند. گردشکار reusable آن artifact را دانلود میکند، موجودی tarball را اعتبارسنجی میکند، در صورت نیاز imageهای Docker با digest بسته را آماده میکند، و laneهای Docker انتخابشده را بهجای بستهبندی checkout گردشکار، در برابر همان بسته اجرا میکند. وقتی یک پروفایل چند `docker_lanes` هدفمند را انتخاب کند، گردشکار reusable بسته و imageهای مشترک را یکبار آماده میکند، سپس آن laneها را بهصورت jobهای Docker هدفمند موازی با artifactهای یکتا fan out میکند.
|
||||
3. `package_telegram` بهصورت اختیاری `NPM Telegram Beta E2E` را فراخوانی میکند. وقتی `telegram_mode` برابر `none` نباشد اجرا میشود و اگر پذیرش بسته یک مورد را resolve کرده باشد، همان artifact `package-under-test` را نصب میکند؛ dispatch مستقل Telegram همچنان میتواند یک spec منتشرشده npm را نصب کند.
|
||||
4. `summary` اگر resolve بسته، پذیرش Docker، یا lane اختیاری Telegram شکست خورده باشد، گردشکار را fail میکند.
|
||||
1. `resolve_package` مقدار `workflow_ref` را checkout میکند، یک نامزد بسته را resolve میکند، `.artifacts/docker-e2e-package/openclaw-current.tgz` را مینویسد، `.artifacts/docker-e2e-package/package-candidate.json` را مینویسد، هر دو را بهعنوان artifact با نام `package-under-test` آپلود میکند، و منبع، مرجع گردشکار، مرجع بسته، نسخه، SHA-256، و profile را در خلاصه step گیتهاب چاپ میکند.
|
||||
2. `docker_acceptance`، `openclaw-live-and-e2e-checks-reusable.yml` را با `ref=workflow_ref` و `package_artifact_name=package-under-test` فراخوانی میکند. گردشکار قابل استفاده مجدد آن artifact را دانلود میکند، موجودی tarball را اعتبارسنجی میکند، در صورت نیاز imageهای Docker با digest بسته را آماده میکند، و laneهای Docker انتخابشده را به جای بستهبندی checkout گردشکار، روی همان بسته اجرا میکند. وقتی یک profile چند `docker_lanes` هدفمند انتخاب کند، گردشکار قابل استفاده مجدد بسته و imageهای مشترک را یکبار آماده میکند، سپس آن laneها را بهصورت jobهای Docker هدفمند موازی با artifactهای یکتا منشعب میکند.
|
||||
3. `package_telegram` بهصورت اختیاری `NPM Telegram Beta E2E` را فراخوانی میکند. وقتی `telegram_mode` برابر `none` نباشد اجرا میشود و اگر Package Acceptance یک بسته را resolve کرده باشد، همان artifact با نام `package-under-test` را نصب میکند؛ ارسال مستقل Telegram همچنان میتواند یک spec منتشرشده npm را نصب کند.
|
||||
4. `summary` اگر resolve بسته، پذیرش Docker، یا lane اختیاری Telegram ناموفق شده باشد، گردشکار را fail میکند.
|
||||
|
||||
### منابع نامزد
|
||||
|
||||
- `source=npm` فقط `openclaw@alpha`، `openclaw@beta`، `openclaw@latest`، یا یک نسخه دقیق انتشار OpenClaw مانند `openclaw@2026.4.27-beta.2` را میپذیرد. از این برای پذیرش پیشانتشار/پایدار منتشرشده استفاده کنید.
|
||||
- `source=ref` یک شاخه، برچسب، یا SHA کامل commit قابل اعتماد `package_ref` را بستهبندی میکند. resolver شاخهها/برچسبهای OpenClaw را fetch میکند، بررسی میکند commit انتخابشده از history شاخه repository یا یک برچسب انتشار قابل دسترسی باشد، dependencyها را در یک worktree detached نصب میکند، و آن را با `scripts/package-openclaw-for-docker.mjs` بستهبندی میکند.
|
||||
- `source=url` یک `.tgz` با HTTPS دانلود میکند؛ `package_sha256` الزامی است.
|
||||
- `source=artifact` یک `.tgz` را از `artifact_run_id` و `artifact_name` دانلود میکند؛ `package_sha256` اختیاری است اما برای artifactهای بهاشتراکگذاشتهشده خارجی باید ارائه شود.
|
||||
- `source=npm` فقط `openclaw@beta`، `openclaw@latest`، یا یک نسخه دقیق انتشار OpenClaw مانند `openclaw@2026.4.27-beta.2` را میپذیرد. از این برای پذیرش پیشانتشار/انتشار پایدار منتشرشده استفاده کنید.
|
||||
- `source=ref` یک شاخه، تگ، یا SHA کامل commit مربوط به `package_ref` قابل اعتماد را بستهبندی میکند. Resolver شاخهها/تگهای OpenClaw را fetch میکند، تأیید میکند commit انتخابشده از تاریخچه شاخه repository یا یک تگ انتشار قابل دسترسی است، وابستگیها را در یک worktree جدا نصب میکند، و آن را با `scripts/package-openclaw-for-docker.mjs` بستهبندی میکند.
|
||||
- `source=url` یک `.tgz` HTTPS را دانلود میکند؛ `package_sha256` الزامی است.
|
||||
- `source=artifact` یک `.tgz` را از `artifact_run_id` و `artifact_name` دانلود میکند؛ `package_sha256` اختیاری است اما برای artifactهای بهاشتراکگذاشتهشده بیرونی باید ارائه شود.
|
||||
|
||||
`workflow_ref` و `package_ref` را جدا نگه دارید. `workflow_ref` کد گردشکار/harness قابل اعتمادی است که تست را اجرا میکند. `package_ref` همان commit منبعی است که وقتی `source=ref` باشد بستهبندی میشود. این اجازه میدهد harness تست فعلی commitهای منبع قدیمیتر و قابل اعتماد را بدون اجرای منطق گردشکار قدیمی اعتبارسنجی کند.
|
||||
`workflow_ref` و `package_ref` را جدا نگه دارید. `workflow_ref` کد گردشکار/harness قابل اعتمادی است که تست را اجرا میکند. `package_ref` commit منبعی است که وقتی `source=ref` باشد بستهبندی میشود. این اجازه میدهد harness تست فعلی، commitهای منبع قابل اعتماد قدیمیتر را بدون اجرای منطق قدیمی گردشکار اعتبارسنجی کند.
|
||||
|
||||
### پروفایلهای مجموعه
|
||||
### Profileهای مجموعه
|
||||
|
||||
- `smoke` — `npm-onboard-channel-agent`، `gateway-network`، `config-reload`
|
||||
- `package` — `npm-onboard-channel-agent`، `doctor-switch`، `update-channel-switch`، `upgrade-survivor`، `published-upgrade-survivor`، `plugins-offline`، `plugin-update`
|
||||
- `product` — `package` بهعلاوه `mcp-channels`، `cron-mcp-cleanup`، `openai-web-search-minimal`، `openwebui`
|
||||
- `full` — قطعههای کامل مسیر انتشار Docker همراه با OpenWebUI
|
||||
- `custom` — مقدار دقیق `docker_lanes`؛ وقتی `suite_profile=custom` باشد الزامی است
|
||||
- `full` — chunkهای کامل مسیر انتشار Docker با OpenWebUI
|
||||
- `custom` — مقدار دقیق `docker_lanes`؛ زمانی که `suite_profile=custom` باشد الزامی است
|
||||
|
||||
پروفایل `package` از پوشش Plugin آفلاین استفاده میکند تا اعتبارسنجی بسته منتشرشده وابسته به دردسترسبودن live ClawHub نباشد. lane اختیاری Telegram در `NPM Telegram Beta E2E` از artifact `package-under-test` دوباره استفاده میکند، و مسیر spec منتشرشده npm برای dispatchهای مستقل حفظ میشود.
|
||||
Profile مربوط به `package` از پوشش آفلاین Plugin استفاده میکند تا اعتبارسنجی بسته منتشرشده به دسترسپذیری زنده ClawHub وابسته نباشد. Lane اختیاری Telegram در `NPM Telegram Beta E2E` همان artifact با نام `package-under-test` را دوباره استفاده میکند، و مسیر spec منتشرشده npm برای ارسالهای مستقل حفظ میشود.
|
||||
|
||||
برای سیاست اختصاصی تست بهروزرسانی و Plugin، شامل commandهای محلی،
|
||||
laneهای Docker، ورودیهای پذیرش بسته، پیشفرضهای release، و triage شکست،
|
||||
به [تست بهروزرسانیها و Pluginها](/fa/help/testing-updates-plugins) مراجعه کنید.
|
||||
برای سیاست اختصاصی تست بهروزرسانی و Plugin، شامل فرمانهای محلی،
|
||||
laneهای Docker، ورودیهای Package Acceptance، پیشفرضهای انتشار، و triage خرابی،
|
||||
[تست بهروزرسانیها و Pluginها](/fa/help/testing-updates-plugins) را ببینید.
|
||||
|
||||
release checkها پذیرش بسته را با `source=artifact`، artifact بسته release آمادهشده، `suite_profile=custom`، `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`، `published_upgrade_survivor_baselines=all-since-2026.4.23`، `published_upgrade_survivor_scenarios=reported-issues` و `telegram_mode=mock-openai` فراخوانی میکنند. این باعث میشود اثبات مهاجرت بسته، بهروزرسانی، پاکسازی dependencyهای stale Plugin، ترمیم نصب Plugin پیکربندیشده، Plugin آفلاین، بهروزرسانی Plugin، و Telegram روی همان tarball بسته resolveشده انجام شود. برای اجرای همان matrix در برابر یک بسته npm ارسالشده، بهجای artifact ساختهشده از SHA، مقدار `package_acceptance_package_spec` را روی Full Release Validation یا OpenClaw Release Checks تنظیم کنید. release checkهای Cross-OS همچنان onboarding، نصبکننده، و رفتار پلتفرمی ویژه OS را پوشش میدهند؛ اعتبارسنجی محصول package/update باید با پذیرش بسته آغاز شود. lane Docker با نام `published-upgrade-survivor` در هر اجرا یک baseline بسته منتشرشده را اعتبارسنجی میکند. در پذیرش بسته، tarball resolveشده `package-under-test` همیشه نامزد است و `published_upgrade_survivor_baseline` baseline منتشرشده fallback را انتخاب میکند، که بهطور پیشفرض `openclaw@latest` است؛ commandهای اجرای دوباره lane شکستخورده همان baseline را حفظ میکنند. برای گسترش Full Release CI روی همه releaseهای پایدار npm از `2026.4.23` تا `latest` مقدار `published_upgrade_survivor_baselines=all-since-2026.4.23` را تنظیم کنید؛ `release-history` برای نمونهگیری دستی گستردهتر با anchor قدیمیتر قبل از تاریخ همچنان دردسترس است. برای گسترش همان baselineها روی fixtureهای شبیه issue برای config فیشو، فایلهای bootstrap/persona حفظشده، نصبهای Plugin پیکربندیشده OpenClaw، مسیرهای log با tilde، و ریشههای stale dependency Plugin قدیمی، مقدار `published_upgrade_survivor_scenarios=reported-issues` را تنظیم کنید. گردشکار جداگانه `Update Migration` وقتی پرسش، پاکسازی کامل بهروزرسانیهای منتشرشده است و نه گستره عادی Full Release CI، از lane Docker `update-migration` همراه با `all-since-2026.4.23` و `plugin-deps-cleanup` استفاده میکند. اجراهای تجمیعی محلی میتوانند specهای دقیق بسته را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` پاس بدهند، یک lane واحد را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` مانند `openclaw@2026.4.15` نگه دارند، یا برای matrix سناریو مقدار `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` را تنظیم کنند. lane منتشرشده baseline را با یک recipe از command آماده `openclaw config set` پیکربندی میکند، stepهای recipe را در `summary.json` ثبت میکند، و پس از شروع Gateway، `/healthz`، `/readyz` و وضعیت RPC را probe میکند. laneهای fresh بستهبندیشده و نصبکننده Windows همچنین بررسی میکنند که یک بسته نصبشده بتواند یک override کنترل مرورگر را از یک مسیر absolute خام Windows import کند. smoke نوبت agent Cross-OS OpenAI در صورت تنظیم بودن بهطور پیشفرض از `OPENCLAW_CROSS_OS_OPENAI_MODEL` استفاده میکند، وگرنه از `openai/gpt-5.4`، تا اثبات نصب و Gateway روی یک مدل تست GPT-5 بماند و از پیشفرضهای GPT-4.x اجتناب شود.
|
||||
بررسیهای انتشار، Package Acceptance را با `source=artifact`، artifact آمادهشده بسته انتشار، `suite_profile=custom`، `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`، `published_upgrade_survivor_baselines=all-since-2026.4.23`، `published_upgrade_survivor_scenarios=reported-issues`، و `telegram_mode=mock-openai` فراخوانی میکنند. این کار اثبات migration بسته، بهروزرسانی، پاکسازی وابستگیهای کهنه Plugin، تعمیر نصب Plugin پیکربندیشده، Plugin آفلاین، بهروزرسانی Plugin، و Telegram را روی همان tarball بسته resolveشده نگه میدارد. برای اجرای همان ماتریس روی یک بسته npm ارسالشده به جای artifact ساختهشده از SHA، مقدار `package_acceptance_package_spec` را روی Full Release Validation یا OpenClaw Release Checks تنظیم کنید. بررسیهای انتشار میانسیستمی هنوز onboarding، نصبکننده، و رفتار platform خاص سیستمعامل را پوشش میدهند؛ اعتبارسنجی محصول بسته/بهروزرسانی باید از Package Acceptance شروع شود. Lane مربوط به Docker با نام `published-upgrade-survivor` در هر اجرا یک baseline بسته منتشرشده را اعتبارسنجی میکند. در Package Acceptance، tarball resolveشده `package-under-test` همیشه نامزد است و `published_upgrade_survivor_baseline`، baseline منتشرشده fallback را انتخاب میکند که پیشفرض آن `openclaw@latest` است؛ فرمانهای اجرای دوباره lane ناموفق آن baseline را حفظ میکنند. برای گسترش Full Release CI روی هر انتشار پایدار npm از `2026.4.23` تا `latest`، مقدار `published_upgrade_survivor_baselines=all-since-2026.4.23` را تنظیم کنید؛ `release-history` همچنان برای نمونهبرداری دستی گستردهتر با anchor قدیمیتر پیش از تاریخ در دسترس میماند. برای گسترش همان baselineها روی fixtureهای شبیه issue برای پیکربندی Feishu، فایلهای bootstrap/persona حفظشده، نصبهای Plugin پیکربندیشده OpenClaw، مسیرهای log با tilde، و ریشههای وابستگی Plugin میراثی کهنه، مقدار `published_upgrade_survivor_scenarios=reported-issues` را تنظیم کنید. گردشکار جداگانه `Update Migration` زمانی از lane Docker با نام `update-migration` همراه با `all-since-2026.4.23` و `plugin-deps-cleanup` استفاده میکند که پرسش، پاکسازی کامل بهروزرسانیهای منتشرشده باشد، نه گستره معمول Full Release CI. اجراهای تجمیعی محلی میتوانند specهای دقیق بسته را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` بدهند، یک lane منفرد را با `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC` مانند `openclaw@2026.4.15` نگه دارند، یا `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` را برای ماتریس scenario تنظیم کنند. Lane منتشرشده، baseline را با یک دستور پختهشده `openclaw config set` پیکربندی میکند، گامهای دستور را در `summary.json` ثبت میکند، و پس از شروع Gateway، `/healthz`، `/readyz`، بهعلاوه وضعیت RPC را probe میکند. Laneهای بستهبندیشده Windows و نصبکننده fresh نیز تأیید میکنند که یک بسته نصبشده میتواند override مربوط به browser-control را از یک مسیر خام absolute در Windows import کند. Smoke مربوط به agent-turn میانسیستمی OpenAI وقتی `OPENCLAW_CROSS_OS_OPENAI_MODEL` تنظیم شده باشد، بهصورت پیشفرض از آن استفاده میکند، وگرنه از `openai/gpt-5.4` استفاده میکند، بنابراین اثبات نصب و Gateway روی یک مدل تست GPT-5 باقی میماند و از پیشفرضهای GPT-4.x پرهیز میکند.
|
||||
|
||||
### پنجرههای سازگاری قدیمی
|
||||
### پنجرههای سازگاری میراثی
|
||||
|
||||
پذیرش بسته برای بستههایی که از قبل منتشر شدهاند پنجرههای bounded سازگاری قدیمی دارد. بستهها تا `2026.4.25`، شامل `2026.4.25-beta.*`، ممکن است از مسیر سازگاری استفاده کنند:
|
||||
Package Acceptance برای بستههایی که از قبل منتشر شدهاند پنجرههای سازگاری میراثی محدود دارد. بستهها تا `2026.4.25`، شامل `2026.4.25-beta.*`، ممکن است از مسیر سازگاری استفاده کنند:
|
||||
|
||||
- ورودیهای private QA شناختهشده در `dist/postinstall-inventory.json` ممکن است به فایلهای حذفشده از tarball اشاره کنند؛
|
||||
- `doctor-switch` ممکن است زیرمورد persistence مربوط به `gateway install --wrapper` را وقتی بسته آن flag را expose نمیکند skip کند؛
|
||||
- `update-channel-switch` ممکن است `pnpm.patchedDependencies` گمشده را از fixture git جعلی مشتقشده از tarball prune کند و ممکن است `update.channel` persisted گمشده را log کند؛
|
||||
- smokeهای Plugin ممکن است مکانهای legacy install-record را بخوانند یا persistence گمشده install-record مربوط به marketplace را بپذیرند؛
|
||||
- `plugin-update` ممکن است مهاجرت metadata مربوط به config را مجاز بداند، در حالی که همچنان الزام میکند install record و رفتار no-reinstall بدون تغییر بمانند.
|
||||
- ورودیهای QA خصوصی شناختهشده در `dist/postinstall-inventory.json` ممکن است به فایلهایی اشاره کنند که از tarball حذف شدهاند؛
|
||||
- `doctor-switch` ممکن است وقتی بسته آن flag را در معرض قرار نمیدهد، زیرمورد persistence مربوط به `gateway install --wrapper` را رد کند؛
|
||||
- `update-channel-switch` ممکن است `pnpm.patchedDependencies` گمشده را از fixture جعلی git مشتقشده از tarball حذف کند و ممکن است `update.channel` persistشده گمشده را log کند؛
|
||||
- smokeهای Plugin ممکن است locationهای میراثی install-record را بخوانند یا persistence گمشده install-record marketplace را بپذیرند؛
|
||||
- `plugin-update` ممکن است migration metadata پیکربندی را مجاز بداند، در حالی که همچنان الزام میکند install record و رفتار no-reinstall بدون تغییر بمانند.
|
||||
|
||||
بسته منتشرشده `2026.4.26` نیز ممکن است برای فایلهای stamp metadata build محلی که قبلا ارسال شده بودند هشدار بدهد. بستههای بعدی باید قراردادهای مدرن را برآورده کنند؛ همان شرایط بهجای هشدار یا skip، fail میشوند.
|
||||
بسته منتشرشده `2026.4.26` نیز ممکن است برای فایلهای stamp metadata ساخت محلی که قبلا ارسال شدهاند هشدار دهد. بستههای بعدی باید قراردادهای مدرن را برآورده کنند؛ همان شرایط به جای هشدار یا skip، fail میشوند.
|
||||
|
||||
### مثالها
|
||||
|
||||
@ -307,110 +307,110 @@ gh workflow run package-acceptance.yml \
|
||||
-f docker_lanes='install-e2e plugin-update'
|
||||
```
|
||||
|
||||
هنگام اشکالزدایی اجرای ناموفق پذیرش بسته، از خلاصه `resolve_package` شروع کنید تا منبع بسته، نسخه و SHA-256 را تایید کنید. سپس اجرای فرزند `docker_acceptance` و آرتیفکتهای Docker آن را بررسی کنید: `.artifacts/docker-tests/**/summary.json`، `failures.json`، لاگهای lane، زمانبندی فازها و فرمانهای اجرای دوباره. بهجای اجرای دوباره اعتبارسنجی کامل انتشار، اجرای دوباره پروفایل بسته ناموفق یا laneهای دقیق Docker را ترجیح دهید.
|
||||
هنگام اشکالزدایی یک اجرای ناموفق پذیرش بسته، از خلاصهی `resolve_package` شروع کنید تا منبع بسته، نسخه و SHA-256 را تأیید کنید. سپس اجرای فرزند `docker_acceptance` و آرتیفکتهای Docker آن را بررسی کنید: `.artifacts/docker-tests/**/summary.json`، `failures.json`، گزارشهای lane، زمانبندیهای phase و فرمانهای اجرای دوباره. بهجای اجرای دوبارهی اعتبارسنجی کامل انتشار، اجرای دوبارهی profile بستهی ناموفق یا laneهای دقیق Docker را ترجیح دهید.
|
||||
|
||||
## دودآزمایی نصب
|
||||
## دودسنجی نصب
|
||||
|
||||
گردشکار جداگانه `Install Smoke` همان اسکریپت دامنه را از طریق job اختصاصی `preflight` خود دوباره استفاده میکند. این گردشکار پوشش دودآزمایی را به `run_fast_install_smoke` و `run_full_install_smoke` تقسیم میکند.
|
||||
workflow جداگانهی `Install Smoke` همان اسکریپت scope را از طریق job اختصاصی `preflight` خود بازاستفاده میکند. این workflow پوشش دودسنجی را به `run_fast_install_smoke` و `run_full_install_smoke` تقسیم میکند.
|
||||
|
||||
- **مسیر سریع** برای pull requestهایی اجرا میشود که سطحهای Docker/بسته، تغییرات بسته/manifest مربوط به Plugin همراه، یا سطحهای هستهای Plugin/کانال/Gateway/Plugin SDK را لمس میکنند که jobهای دودآزمایی Docker آنها را تمرین میدهند. تغییرات فقطمنبع در Pluginهای همراه، ویرایشهای فقطآزمون، و ویرایشهای فقطمستندات workerهای Docker را رزرو نمیکنند. مسیر سریع تصویر Dockerfile ریشه را یکبار میسازد، CLI را بررسی میکند، دودآزمایی CLI حذف agents در workspace مشترک را اجرا میکند، e2e مربوط به Gateway-network کانتینر را اجرا میکند، یک آرگومان ساخت اکستنشن همراه را تایید میکند و پروفایل Docker محدود Plugin همراه را با مهلت زمانی تجمیعی ۲۴۰ ثانیهای برای فرمان اجرا میکند؛ اجرای Docker هر سناریو جداگانه محدود میشود.
|
||||
- **مسیر کامل** پوشش نصب بسته QR و Docker/update نصبکننده را برای اجراهای زمانبندیشده شبانه، dispatchهای دستی، بررسیهای انتشار workflow-call و pull requestهایی نگه میدارد که واقعا سطحهای نصبکننده/بسته/Docker را لمس میکنند. در حالت کامل، install-smoke یک تصویر دودآزمایی GHCR از Dockerfile ریشه برای SHA هدف آماده میکند یا دوباره استفاده میکند، سپس نصب بسته QR، دودآزماییهای Dockerfile/Gateway ریشه، دودآزماییهای نصبکننده/update و E2E سریع Docker مربوط به Plugin همراه را بهصورت jobهای جدا اجرا میکند تا کار نصبکننده پشت دودآزماییهای تصویر ریشه منتظر نماند.
|
||||
- **مسیر سریع** برای pull requestهایی اجرا میشود که سطحهای Docker/بسته، تغییرات بسته/manifest مربوط به Plugin همراه، یا سطحهای Plugin/channel/gateway/Plugin SDK هسته را لمس میکنند که jobهای دودسنجی Docker آنها را تمرین میدهند. تغییرات فقط-منبع در Pluginهای همراه، ویرایشهای فقط-تست و ویرایشهای فقط-مستندات workerهای Docker را رزرو نمیکنند. مسیر سریع image ریشهی Dockerfile را یکبار میسازد، CLI را بررسی میکند، دودسنجی CLI مربوط به حذف agents در shared-workspace را اجرا میکند، e2e مربوط به gateway-network کانتینر را اجرا میکند، build arg مربوط به یک extension همراه را تأیید میکند، و profile محدود Docker برای Plugin همراه را زیر timeout تجمیعی ۲۴۰ ثانیهای فرمان اجرا میکند (اجرای Docker هر سناریو جداگانه محدود میشود).
|
||||
- **مسیر کامل** نصب بستهی QR و پوشش Docker/update نصبکننده را برای اجراهای زمانبندیشدهی شبانه، dispatchهای دستی، بررسیهای انتشار workflow-call و pull requestهایی نگه میدارد که واقعاً سطحهای نصبکننده/بسته/Docker را لمس میکنند. در حالت کامل، install-smoke یک image دودسنجی GHCR از root Dockerfile با target-SHA را آماده یا بازاستفاده میکند، سپس نصب بستهی QR، دودسنجیهای root Dockerfile/gateway، دودسنجیهای installer/update و E2E سریع Docker برای Plugin همراه را بهصورت jobهای جداگانه اجرا میکند تا کار نصبکننده پشت دودسنجیهای image ریشه منتظر نماند.
|
||||
|
||||
pushهای `main`، شامل merge commitها، مسیر کامل را اجباری نمیکنند؛ وقتی منطق دامنه تغییرات روی یک push پوشش کامل را درخواست کند، گردشکار دودآزمایی سریع Docker را نگه میدارد و دودآزمایی کامل نصب را به اعتبارسنجی شبانه یا انتشار واگذار میکند.
|
||||
pushهای `main`، از جمله merge commitها، مسیر کامل را اجباری نمیکنند؛ وقتی منطق changed-scope روی یک push پوشش کامل را درخواست کند، workflow دودسنجی سریع Docker را نگه میدارد و دودسنجی کامل نصب را به اعتبارسنجی شبانه یا انتشار واگذار میکند.
|
||||
|
||||
دودآزمایی کند نصب سراسری Bun برای image-provider جداگانه با `run_bun_global_install_smoke` کنترل میشود. این مورد در زمانبندی شبانه و از گردشکار بررسیهای انتشار اجرا میشود، و dispatchهای دستی `Install Smoke` میتوانند آن را فعال کنند، اما pull requestها و pushهای `main` این کار را نمیکنند. آزمونهای Docker مربوط به QR و نصبکننده Dockerfileهای متمرکز بر نصب خود را حفظ میکنند.
|
||||
دودسنجی کند نصب سراسری Bun برای image-provider جداگانه با `run_bun_global_install_smoke` gate میشود. این دودسنجی در برنامهی شبانه و از workflow بررسیهای انتشار اجرا میشود، و dispatchهای دستی `Install Smoke` میتوانند آن را فعال کنند، اما pull requestها و pushهای `main` این کار را نمیکنند. تستهای Docker مربوط به QR و نصبکننده Dockerfileهای متمرکز بر نصب خودشان را نگه میدارند.
|
||||
|
||||
## E2E محلی Docker
|
||||
|
||||
`pnpm test:docker:all` یک تصویر live-test مشترک را از پیش میسازد، OpenClaw را یکبار بهعنوان tarball npm بستهبندی میکند و دو تصویر مشترک `scripts/e2e/Dockerfile` میسازد:
|
||||
`pnpm test:docker:all` یک image مشترک live-test را از پیش میسازد، OpenClaw را یکبار بهعنوان tarball npm بستهبندی میکند و دو image مشترک `scripts/e2e/Dockerfile` میسازد:
|
||||
|
||||
- یک اجراکننده خام Node/Git برای laneهای نصبکننده/update/وابستگی Plugin؛
|
||||
- یک تصویر کاربردی که همان tarball را برای laneهای عملکرد عادی در `/app` نصب میکند.
|
||||
- یک runner خام Node/Git برای laneهای installer/update/plugin-dependency؛
|
||||
- یک image کاربردی که همان tarball را برای laneهای عملکرد عادی در `/app` نصب میکند.
|
||||
|
||||
تعریفهای laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند، منطق برنامهریز در `scripts/lib/docker-e2e-plan.mjs` قرار دارد، و اجراکننده فقط plan انتخابشده را اجرا میکند. زمانبند تصویر هر lane را با `OPENCLAW_DOCKER_E2E_BARE_IMAGE` و `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` انتخاب میکند، سپس laneها را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا میکند.
|
||||
تعریفهای laneهای Docker در `scripts/lib/docker-e2e-scenarios.mjs` قرار دارند، منطق planner در `scripts/lib/docker-e2e-plan.mjs` قرار دارد، و runner فقط plan انتخابشده را اجرا میکند. scheduler با `OPENCLAW_DOCKER_E2E_BARE_IMAGE` و `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE` برای هر lane image را انتخاب میکند، سپس laneها را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا میکند.
|
||||
|
||||
### تنظیمپذیرها
|
||||
### تنظیمات قابلتغییر
|
||||
|
||||
| متغیر | پیشفرض | هدف |
|
||||
| متغیر | پیشفرض | هدف |
|
||||
| -------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
|
||||
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | تعداد slotهای pool اصلی برای laneهای عادی. |
|
||||
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | تعداد slotهای pool انتهایی حساس به provider. |
|
||||
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | سقف laneهای live همزمان تا providerها throttling نکنند. |
|
||||
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | تعداد slotهای main-pool برای laneهای عادی. |
|
||||
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | تعداد slotهای tail-pool حساس به provider. |
|
||||
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | سقف laneهای live همزمان تا providerها throttle نکنند. |
|
||||
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | سقف laneهای نصب npm همزمان. |
|
||||
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | سقف laneهای چندسرویسی همزمان. |
|
||||
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | فاصلهگذاری بین شروع laneها برای جلوگیری از طوفان ساخت در daemon Docker؛ برای بدون فاصلهگذاری، `0` تنظیم کنید. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | مهلت زمانی fallback برای هر lane، ۱۲۰ دقیقه؛ laneهای منتخب live/tail سقفهای سختگیرانهتری دارند. |
|
||||
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | تنظیمنشده | `1` plan زمانبند را بدون اجرای laneها چاپ میکند. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANES` | تنظیمنشده | فهرست دقیق laneها با جداکننده کاما؛ دودآزمایی پاکسازی را رد میکند تا agents بتوانند یک lane ناموفق را بازتولید کنند. |
|
||||
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | سقف laneهای چندسرویسی همزمان. |
|
||||
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | فاصلهگذاری بین شروع laneها برای جلوگیری از هجوم create در Docker daemon؛ برای نبود فاصلهگذاری `0` بگذارید. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | timeout پشتیبان برای هر lane، ۱۲۰ دقیقه؛ laneهای live/tail منتخب سقفهای سختگیرانهتری دارند. |
|
||||
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` plan زمانبند را بدون اجرای laneها چاپ میکند. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANES` | unset | فهرست دقیق laneها با جداکنندهی ویرگول؛ دودسنجی cleanup را رد میکند تا agents بتوانند یک lane ناموفق را بازتولید کنند. |
|
||||
|
||||
laneای که از سقف موثر خود سنگینتر است همچنان میتواند از یک pool خالی شروع شود، سپس تا آزاد کردن ظرفیت بهتنهایی اجرا میشود. preflightهای تجمیعی محلی Docker را بررسی میکنند، کانتینرهای E2E قدیمی OpenClaw را حذف میکنند، وضعیت laneهای فعال را منتشر میکنند، زمانبندی laneها را برای ترتیب طولانیترین-اول ماندگار میکنند، و بهطور پیشفرض پس از نخستین failure زمانبندی laneهای pooled جدید را متوقف میکنند.
|
||||
laneای که از سقف مؤثر خود سنگینتر است همچنان میتواند از یک pool خالی شروع شود، سپس تا زمان آزاد کردن ظرفیت تنها اجرا میشود. preflightهای تجمیعی محلی Docker را بررسی میکنند، کانتینرهای قدیمی OpenClaw E2E را حذف میکنند، وضعیت laneهای فعال را منتشر میکنند، زمانبندیهای lane را برای ترتیب طولانیترین-اول ماندگار میکنند، و بهصورت پیشفرض پس از نخستین شکست زمانبندی laneهای pooled جدید را متوقف میکنند.
|
||||
|
||||
### گردشکار reusable live/E2E
|
||||
### workflow بازاستفادهپذیر live/E2E
|
||||
|
||||
گردشکار reusable live/E2E از `scripts/test-docker-all.mjs --plan-json` میپرسد کدام بسته، نوع تصویر، تصویر live، lane و پوشش credential لازم است. سپس `scripts/docker-e2e.mjs` آن plan را به خروجیها و خلاصههای GitHub تبدیل میکند. این گردشکار یا OpenClaw را از طریق `scripts/package-openclaw-for-docker.mjs` بستهبندی میکند، یا یک آرتیفکت بسته از اجرای جاری دانلود میکند، یا یک آرتیفکت بسته را از `package_artifact_run_id` دانلود میکند؛ inventory tarball را اعتبارسنجی میکند؛ وقتی plan به laneهای دارای بسته نصبشده نیاز داشته باشد، تصاویر E2E خام/کاربردی Docker در GHCR با tag مبتنی بر digest بسته را از طریق cache لایه Docker مربوط به Blacksmith میسازد و push میکند؛ و بهجای ساخت دوباره، ورودیهای ارائهشده `docker_e2e_bare_image`/`docker_e2e_functional_image` یا تصاویر موجود مبتنی بر digest بسته را دوباره استفاده میکند. pullهای تصویر Docker با مهلت زمانی محدود ۱۸۰ ثانیهای برای هر تلاش دوباره امتحان میشوند تا جریان گیرکرده registry/cache، بهجای مصرف بیشتر مسیر بحرانی CI، سریع دوباره تلاش شود.
|
||||
workflow بازاستفادهپذیر live/E2E از `scripts/test-docker-all.mjs --plan-json` میپرسد کدام بسته، نوع image، image live، lane و پوشش credential لازم است. سپس `scripts/docker-e2e.mjs` آن plan را به خروجیها و خلاصههای GitHub تبدیل میکند. این workflow یا OpenClaw را از طریق `scripts/package-openclaw-for-docker.mjs` بستهبندی میکند، یا آرتیفکت بستهی اجرای جاری را دانلود میکند، یا آرتیفکت بسته را از `package_artifact_run_id` دانلود میکند؛ موجودی tarball را اعتبارسنجی میکند؛ وقتی plan به laneهای دارای بستهی نصبشده نیاز دارد، imageهای bare/functional Docker E2E در GHCR را با tag مبتنی بر digest بسته از طریق cache لایهی Docker متعلق به Blacksmith میسازد و push میکند؛ و بهجای بازسازی، ورودیهای ارائهشدهی `docker_e2e_bare_image`/`docker_e2e_functional_image` یا imageهای موجود مبتنی بر digest بسته را بازاستفاده میکند. pullهای image Docker با timeout محدود ۱۸۰ ثانیهای برای هر تلاش دوبارهامتحان میشوند تا stream گیرکردهی registry/cache بهجای مصرف بیشتر مسیر حیاتی CI، سریع دوبارهامتحان شود.
|
||||
|
||||
### chunkهای مسیر انتشار
|
||||
|
||||
پوشش Docker انتشار jobهای chunkشده کوچکتری را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا میکند تا هر chunk فقط نوع تصویری را که لازم دارد pull کند و چند lane را از طریق همان زمانبند weighted اجرا کند:
|
||||
پوشش Docker انتشار jobهای chunkشدهی کوچکتری را با `OPENCLAW_SKIP_DOCKER_BUILD=1` اجرا میکند تا هر chunk فقط نوع image موردنیازش را pull کند و چند lane را از طریق همان scheduler وزندار اجرا کند:
|
||||
|
||||
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
|
||||
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h`
|
||||
|
||||
chunkهای فعلی Docker انتشار عبارتاند از `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، و `plugins-runtime-install-a` تا `plugins-runtime-install-h`. `plugins-runtime-core`، `plugins-runtime`، و `plugins-integrations` همچنان aliasهای تجمیعی Plugin/runtime هستند. alias lane `install-e2e` همچنان alias تجمیعی اجرای دوباره دستی برای هر دو lane نصبکننده provider باقی میماند.
|
||||
chunkهای فعلی Docker انتشار عبارتاند از `core`، `package-update-openai`، `package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`، `plugins-runtime-services`، و `plugins-runtime-install-a` تا `plugins-runtime-install-h`. `plugins-runtime-core`، `plugins-runtime` و `plugins-integrations` همچنان aliasهای تجمیعی Plugin/runtime باقی میمانند. alias lane `install-e2e` همچنان alias تجمیعی اجرای دوبارهی دستی برای هر دو lane نصبکنندهی provider است.
|
||||
|
||||
وقتی پوشش کامل release-path آن را درخواست کند، OpenWebUI در `plugins-runtime-services` ادغام میشود، و chunk مستقل `openwebui` را فقط برای dispatchهای فقط OpenWebUI نگه میدارد. laneهای update کانالهای همراه برای failureهای گذرای شبکه npm یکبار دوباره تلاش میکنند.
|
||||
OpenWebUI وقتی پوشش کامل release-path آن را درخواست کند در `plugins-runtime-services` ادغام میشود و فقط برای dispatchهای مخصوص OpenWebUI یک chunk مستقل `openwebui` نگه میدارد. laneهای بهروزرسانی bundled-channel برای خطاهای گذرای شبکهی npm یکبار دوباره تلاش میکنند.
|
||||
|
||||
هر chunk، `.artifacts/docker-tests/` را همراه با لاگهای lane، زمانبندیها، `summary.json`، `failures.json`، زمانبندی فازها، JSON مربوط به plan زمانبند، جدولهای slow-lane، و فرمانهای اجرای دوباره برای هر lane آپلود میکند. ورودی `docker_lanes` گردشکار laneهای انتخابشده را بهجای jobهای chunk روی تصاویر آمادهشده اجرا میکند؛ این کار اشکالزدایی lane ناموفق را به یک job هدفمند Docker محدود نگه میدارد و آرتیفکت بسته را برای آن اجرا آماده، دانلود یا دوباره استفاده میکند؛ اگر یک lane انتخابشده live Docker lane باشد، job هدفمند تصویر live-test را بهصورت محلی برای آن اجرای دوباره میسازد. فرمانهای تولیدشده GitHub برای اجرای دوباره هر lane، وقتی این مقادیر وجود داشته باشند، `package_artifact_run_id`، `package_artifact_name` و ورودیهای تصویر آمادهشده را شامل میشوند تا یک lane ناموفق بتواند همان بسته و تصاویر دقیق اجرای ناموفق را دوباره استفاده کند.
|
||||
هر chunk، `.artifacts/docker-tests/` را با گزارشهای lane، زمانبندیها، `summary.json`، `failures.json`، زمانبندیهای phase، JSON plan زمانبند، جدولهای laneهای کند و فرمانهای اجرای دوبارهی هر lane آپلود میکند. ورودی `docker_lanes` در workflow، laneهای انتخابشده را بهجای jobهای chunk در برابر imageهای آمادهشده اجرا میکند؛ این کار اشکالزدایی lane ناموفق را به یک job هدفمند Docker محدود نگه میدارد و آرتیفکت بسته را برای آن اجرا آماده، دانلود یا بازاستفاده میکند؛ اگر یک lane انتخابشده lane live Docker باشد، job هدفمند image live-test را بهصورت محلی برای آن اجرای دوباره میسازد. فرمانهای اجرای دوبارهی GitHub تولیدشده برای هر lane وقتی این مقدارها وجود داشته باشند شامل `package_artifact_run_id`، `package_artifact_name` و ورودیهای image آمادهشده هستند، تا یک lane ناموفق بتواند دقیقاً همان بسته و imageهای اجرای ناموفق را بازاستفاده کند.
|
||||
|
||||
```bash
|
||||
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
|
||||
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
|
||||
```
|
||||
|
||||
گردشکار زمانبندیشده live/E2E مجموعه کامل Docker مربوط به release-path را روزانه اجرا میکند.
|
||||
workflow زمانبندیشدهی live/E2E هر روز suite کامل Docker مربوط به release-path را اجرا میکند.
|
||||
|
||||
## پیشانتشار Plugin
|
||||
|
||||
`Plugin Prerelease` پوشش محصول/بسته گرانتری است، بنابراین یک گردشکار جداگانه است که توسط `Full Release Validation` یا یک operator صریح dispatch میشود. pull requestهای عادی، pushهای `main` و dispatchهای دستی مستقل CI آن suite را خاموش نگه میدارند. این گردشکار آزمونهای Pluginهای همراه را بین هشت worker اکستنشن متوازن میکند؛ آن jobهای shard اکستنشن همزمان تا دو گروه پیکربندی Plugin را با یک worker Vitest برای هر گروه و heap بزرگتر Node اجرا میکنند تا batchهای Plugin سنگین از نظر import jobهای CI اضافی ایجاد نکنند. مسیر Docker پیشانتشار مخصوص انتشار، laneهای هدفمند Docker را در گروههای کوچک batch میکند تا از رزرو دهها runner برای jobهای یک تا سه دقیقهای جلوگیری کند.
|
||||
`Plugin Prerelease` پوشش محصول/بستهی پرهزینهتری است، بنابراین workflow جداگانهای است که توسط `Full Release Validation` یا یک operator صریح dispatch میشود. pull requestهای عادی، pushهای `main` و dispatchهای دستی مستقل CI آن suite را خاموش نگه میدارند. این workflow تستهای Plugin همراه را میان هشت worker مربوط به extension متعادل میکند؛ آن jobهای shard مربوط به extension همزمان تا دو گروه config مربوط به Plugin را با یک worker Vitest برای هر گروه و heap بزرگتر Node اجرا میکنند تا batchهای Plugin با import سنگین jobهای CI اضافی ایجاد نکنند. مسیر prerelease فقط-انتشار Docker، laneهای هدفمند Docker را در گروههای کوچک batch میکند تا دهها runner برای jobهای یک تا سه دقیقهای رزرو نشوند.
|
||||
|
||||
## آزمایشگاه QA
|
||||
|
||||
QA Lab laneهای اختصاصی CI خارج از گردشکار اصلی smart-scoped دارد. برابری agentic زیر harnessهای گسترده QA و انتشار تو در تو است، نه یک گردشکار مستقل PR. وقتی parity باید همراه یک اجرای اعتبارسنجی گسترده باشد، از `Full Release Validation` با `rerun_group=qa-parity` استفاده کنید.
|
||||
آزمایشگاه QA laneهای اختصاصی CI خارج از workflow اصلی smart-scoped دارد. parity عاملی زیر harnessهای گستردهی QA و انتشار تودرتو است، نه یک workflow مستقل PR. وقتی parity باید همراه یک اجرای اعتبارسنجی گسترده حرکت کند، از `Full Release Validation` با `rerun_group=qa-parity` استفاده کنید.
|
||||
|
||||
- گردشکار `QA-Lab - All Lanes` هر شب روی `main` و در dispatch دستی اجرا میشود؛ این گردشکار lane برابری mock، lane live Matrix و laneهای live Telegram و Discord را بهعنوان jobهای موازی fan out میکند. jobهای live از محیط `qa-live-shared` استفاده میکنند، و Telegram/Discord از leaseهای Convex استفاده میکنند.
|
||||
- workflow `QA-Lab - All Lanes` هر شب روی `main` و با dispatch دستی اجرا میشود؛ این workflow lane برابری mock، lane live Matrix و laneهای live Telegram و Discord را بهعنوان jobهای موازی fan out میکند. jobهای live از environment `qa-live-shared` استفاده میکنند، و Telegram/Discord از leaseهای Convex استفاده میکنند.
|
||||
|
||||
بررسیهای انتشار، laneهای transport زنده Matrix و Telegram را با provider mock قطعی و مدلهای mock-qualified (`mock-openai/gpt-5.5` و `mock-openai/gpt-5.5-alt`) اجرا میکنند تا قرارداد کانال از latency مدل زنده و startup عادی provider-plugin جدا شود. Gateway transport زنده جستوجوی حافظه را غیرفعال میکند، زیرا parity QA رفتار حافظه را جداگانه پوشش میدهد؛ اتصال provider توسط suiteهای جداگانه مدل زنده، provider بومی و provider Docker پوشش داده میشود.
|
||||
بررسیهای انتشار، laneهای transport زندهی Matrix و Telegram را با provider mock قطعی و مدلهای واجد mock، یعنی `mock-openai/gpt-5.5` و `mock-openai/gpt-5.5-alt`، اجرا میکنند تا قرارداد channel از تأخیر مدل live و راهاندازی عادی Plugin provider جدا شود. Gateway مربوط به transport live جستوجوی memory را غیرفعال میکند، چون برابری QA رفتار memory را جداگانه پوشش میدهد؛ اتصال provider توسط suiteهای جداگانهی مدل live، provider بومی و provider Docker پوشش داده میشود.
|
||||
|
||||
Matrix برای gateهای زمانبندیشده و انتشار از `--profile fast` استفاده میکند، و فقط زمانی `--fail-fast` را اضافه میکند که CLI checkoutشده از آن پشتیبانی کند. پیشفرض CLI و ورودی گردشکار دستی همچنان `all` باقی میمانند؛ dispatch دستی `matrix_profile=all` همیشه پوشش کامل Matrix را به jobهای `transport`، `media`، `e2ee-smoke`، `e2ee-deep` و `e2ee-cli` shard میکند.
|
||||
Matrix برای gateهای زمانبندیشده و انتشار از `--profile fast` استفاده میکند و فقط زمانی `--fail-fast` را اضافه میکند که CLI checkoutشده از آن پشتیبانی کند. پیشفرض CLI و ورودی workflow دستی همچنان `all` میمانند؛ dispatch دستی `matrix_profile=all` همیشه پوشش کامل Matrix را به jobهای `transport`، `media`، `e2ee-smoke`، `e2ee-deep` و `e2ee-cli` shard میکند.
|
||||
|
||||
`OpenClaw Release Checks` همچنین laneهای release-critical مربوط به QA Lab را پیش از تایید انتشار اجرا میکند؛ gate برابری QA آن بستههای candidate و baseline را بهعنوان jobهای موازی lane اجرا میکند، سپس هر دو آرتیفکت را در یک job کوچک گزارش دانلود میکند تا مقایسه نهایی parity انجام شود.
|
||||
`OpenClaw Release Checks` همچنین laneهای حیاتی انتشار QA Lab را پیش از تأیید انتشار اجرا میکند؛ gate برابری QA آن packهای candidate و baseline را بهعنوان jobهای lane موازی اجرا میکند، سپس هر دو آرتیفکت را در یک job گزارش کوچک دانلود میکند تا مقایسهی نهایی برابری انجام شود.
|
||||
|
||||
برای PRهای عادی، بهجای تلقی parity بهعنوان status الزامی، از شواهد scoped CI/check پیروی کنید.
|
||||
برای PRهای عادی، بهجای تلقی کردن parity بهعنوان یک status الزامی، شواهد scoped CI/check را دنبال کنید.
|
||||
|
||||
## CodeQL
|
||||
|
||||
گردشکار `CodeQL` عمداً یک اسکنر امنیتی گذر اول و محدود است، نه جاروب کامل مخزن. اجراهای نگهبان روزانه، دستی، و درخواست کشش غیرپیشنویس، کد گردشکار Actions بههمراه پرریسکترین سطوح JavaScript/TypeScript را با کوئریهای امنیتی با اطمینان بالا که به `security-severity` بالا/بحرانی فیلتر شدهاند اسکن میکنند.
|
||||
گردشکار `CodeQL` عمداً یک اسکنر امنیتی محدود برای گذر اول است، نه جاروب کامل مخزن. اجراهای نگهبان روزانه، دستی، و درخواستهای pull غیرپیشنویس، کد گردشکار Actions بههمراه پرریسکترین سطوح JavaScript/TypeScript را با پرسوجوهای امنیتی با اطمینان بالا که به `security-severity` با high/critical محدود شدهاند اسکن میکنند.
|
||||
|
||||
نگهبان درخواست کشش سبک میماند: فقط برای تغییرات زیر `.github/actions`، `.github/codeql`، `.github/workflows`، `packages`، یا `src` شروع میشود، و همان ماتریس امنیتی با اطمینان بالا را اجرا میکند که گردشکار زمانبندیشده اجرا میکند. CodeQL مربوط به Android و macOS از پیشفرضهای PR بیرون میمانند.
|
||||
نگهبان درخواست pull سبک میماند: فقط برای تغییرات زیر `.github/actions`، `.github/codeql`، `.github/workflows`، `packages`، یا `src` شروع میشود، و همان ماتریس امنیتی با اطمینان بالا را مانند گردشکار زمانبندیشده اجرا میکند. CodeQL مربوط به Android و macOS از پیشفرضهای PR بیرون میماند.
|
||||
|
||||
### دستههای امنیتی
|
||||
### دستهبندیهای امنیتی
|
||||
|
||||
| دسته | سطح |
|
||||
| دستهبندی | سطح |
|
||||
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-security-high/core-auth-secrets` | احراز هویت، اسرار، sandbox، Cron، و خط پایه Gateway |
|
||||
| `/codeql-security-high/channel-runtime-boundary` | قراردادهای پیادهسازی کانال هسته بههمراه زمان اجرای Plugin کانال، Gateway، Plugin SDK، اسرار، نقاط تماس audit |
|
||||
| `/codeql-security-high/network-ssrf-boundary` | سطوح SSRF هسته، تجزیه IP، نگهبان شبکه، web-fetch، و سیاست SSRF در Plugin SDK |
|
||||
| `/codeql-security-high/mcp-process-tool-boundary` | سرورهای MCP، helperهای اجرای فرایند، تحویل خروجی، و gateهای اجرای ابزار agent |
|
||||
| `/codeql-security-high/plugin-trust-boundary` | نصب Plugin، loader، manifest، registry، نصب package-manager، source-loading، و سطوح اعتماد قرارداد بسته Plugin SDK |
|
||||
| `/codeql-security-high/core-auth-secrets` | خط مبنای احراز هویت، اسرار، sandbox، cron، و gateway |
|
||||
| `/codeql-security-high/channel-runtime-boundary` | قراردادهای پیادهسازی کانال هسته بهعلاوه زماناجرای Plugin کانال، gateway، Plugin SDK، اسرار، و نقاط تماس ممیزی |
|
||||
| `/codeql-security-high/network-ssrf-boundary` | سطوح خطمشی SSRF هسته، تجزیه IP، نگهبان شبکه، web-fetch، و SSRF در Plugin SDK |
|
||||
| `/codeql-security-high/mcp-process-tool-boundary` | سرورهای MCP، کمکگرهای اجرای فرایند، تحویل خروجی، و دروازههای اجرای ابزار agent |
|
||||
| `/codeql-security-high/plugin-trust-boundary` | سطوح اعتماد نصب Plugin، loader، manifest، registry، نصب package-manager، source-loading، و قرارداد بسته Plugin SDK |
|
||||
|
||||
### shardهای امنیتی ویژه پلتفرم
|
||||
### قطعههای امنیتی ویژه پلتفرم
|
||||
|
||||
- `CodeQL Android Critical Security` — shard امنیتی زمانبندیشده Android. برنامه Android را برای CodeQL بهصورت دستی روی کوچکترین runner لینوکسی Blacksmith که workflow sanity میپذیرد میسازد. زیر `/codeql-critical-security/android` آپلود میکند.
|
||||
- `CodeQL macOS Critical Security` — shard امنیتی هفتگی/دستی macOS. برنامه macOS را برای CodeQL بهصورت دستی روی Blacksmith macOS میسازد، نتایج build وابستگی را از SARIF آپلودشده فیلتر میکند، و زیر `/codeql-critical-security/macos` آپلود میکند. بیرون از پیشفرضهای روزانه نگه داشته شده چون build macOS حتی در حالت clean هم بر زمان اجرا غالب است.
|
||||
- `CodeQL Android Critical Security` — قطعه امنیتی زمانبندیشده Android. برنامه Android را برای CodeQL بهصورت دستی روی کوچکترین runner لینوکسی Blacksmith که workflow sanity میپذیرد میسازد. زیر `/codeql-critical-security/android` بارگذاری میکند.
|
||||
- `CodeQL macOS Critical Security` — قطعه امنیتی هفتگی/دستی macOS. برنامه macOS را برای CodeQL بهصورت دستی روی Blacksmith macOS میسازد، نتایج ساخت وابستگی را از SARIF بارگذاریشده فیلتر میکند، و زیر `/codeql-critical-security/macos` بارگذاری میکند. چون ساخت macOS حتی در حالت پاک هم زماناجرا را غالب میکند، خارج از پیشفرضهای روزانه نگه داشته شده است.
|
||||
|
||||
### دستههای کیفیت بحرانی
|
||||
### دستهبندیهای کیفیت بحرانی
|
||||
|
||||
`CodeQL Critical Quality` shard غیرامنیتی متناظر است. این shard فقط کوئریهای کیفیت JavaScript/TypeScript با شدت خطا و غیرامنیتی را روی سطوح محدود و پرارزش روی runner کوچکتر لینوکسی Blacksmith اجرا میکند. نگهبان درخواست کشش آن عمداً کوچکتر از پروفایل زمانبندیشده است: PRهای غیرپیشنویس فقط shardهای متناظر `agent-runtime-boundary`، `config-boundary`، `core-auth-secrets`، `channel-runtime-boundary`، `gateway-runtime-boundary`، `memory-runtime-boundary`، `mcp-process-runtime-boundary`، `provider-runtime-boundary`، `session-diagnostics-boundary`، `plugin-boundary`، `plugin-sdk-package-contract`، و `plugin-sdk-reply-runtime` را برای تغییرات کد اجرای command/model/tool agent و dispatch پاسخ، کد schema/migration/IO پیکربندی، کد auth/secrets/sandbox/security، زمان اجرای کانال هسته و Plugin کانال همراه، Gateway protocol/server-method، چسب runtime/SDK حافظه، MCP/process/outbound delivery، کاتالوگ provider runtime/model، session diagnostics/delivery queues، Plugin loader، Plugin SDK/package-contract، یا Plugin SDK reply runtime اجرا میکنند. تغییرات پیکربندی CodeQL و گردشکار کیفیت، هر دوازده shard کیفیت PR را اجرا میکنند.
|
||||
`CodeQL Critical Quality` قطعه غیرامنیتی متناظر است. فقط پرسوجوهای کیفیت JavaScript/TypeScript غیرامنیتی با شدت خطا را روی سطوح محدود و باارزش بالا در runner لینوکسی کوچکتر Blacksmith اجرا میکند. نگهبان درخواست pull آن عمداً کوچکتر از پروفایل زمانبندیشده است: PRهای غیرپیشنویس فقط قطعههای متناظر `agent-runtime-boundary`، `config-boundary`، `core-auth-secrets`، `channel-runtime-boundary`، `gateway-runtime-boundary`، `memory-runtime-boundary`، `mcp-process-runtime-boundary`، `provider-runtime-boundary`، `session-diagnostics-boundary`، `plugin-boundary`، `plugin-sdk-package-contract`، و `plugin-sdk-reply-runtime` را برای تغییرات کد اجرای دستور/مدل/ابزار agent و dispatch پاسخ، کد schema/migration/IO پیکربندی، کد auth/secrets/sandbox/security، زماناجرای کانال هسته و Plugin کانال bundled، پروتکل Gateway/server-method، زماناجرای memory/چسب SDK، MCP/process/outbound delivery، زماناجرای provider/کاتالوگ مدل، تشخیص نشست/صفهای تحویل، loader Plugin، قرارداد Plugin SDK/package-contract، یا زماناجرای پاسخ Plugin SDK اجرا میکنند. تغییرات پیکربندی CodeQL و گردشکار کیفیت، هر دوازده قطعه کیفیت PR را اجرا میکنند.
|
||||
|
||||
dispatch دستی میپذیرد:
|
||||
|
||||
@ -418,40 +418,40 @@ dispatch دستی میپذیرد:
|
||||
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
|
||||
```
|
||||
|
||||
پروفایلهای محدود، hookهای آموزش/تکرار برای اجرای یک shard کیفیت بهصورت ایزوله هستند.
|
||||
پروفایلهای محدود، قلابهای آموزش/تکرار برای اجرای یک قطعه کیفیت بهصورت ایزوله هستند.
|
||||
|
||||
| دسته | سطح |
|
||||
| دستهبندی | سطح |
|
||||
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-critical-quality/core-auth-secrets` | کد مرز امنیتی احراز هویت، اسرار، sandbox، Cron، و Gateway |
|
||||
| `/codeql-critical-quality/config-boundary` | قراردادهای schema پیکربندی، migration، normalization، و IO |
|
||||
| `/codeql-critical-quality/gateway-runtime-boundary` | schemaهای پروتکل Gateway و قراردادهای method سرور |
|
||||
| `/codeql-critical-quality/channel-runtime-boundary` | قراردادهای پیادهسازی کانال هسته و Plugin کانال همراه |
|
||||
| `/codeql-critical-quality/agent-runtime-boundary` | اجرای command، dispatch مدل/provider، dispatch و صفهای auto-reply، و قراردادهای runtime سطح کنترل ACP |
|
||||
| `/codeql-critical-quality/mcp-process-runtime-boundary` | سرورهای MCP و پلهای ابزار، helperهای نظارت بر فرایند، و قراردادهای تحویل خروجی |
|
||||
| `/codeql-critical-quality/memory-runtime-boundary` | SDK میزبان حافظه، facadeهای runtime حافظه، aliasهای حافظه در Plugin SDK، چسب فعالسازی runtime حافظه، و commandهای doctor حافظه |
|
||||
| `/codeql-critical-quality/session-diagnostics-boundary` | internals صف پاسخ، صفهای تحویل session، helperهای اتصال/تحویل session خروجی، سطوح diagnostic event/log bundle، و قراردادهای CLI مربوط به session doctor |
|
||||
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | dispatch پاسخ ورودی Plugin SDK، helperهای reply payload/chunking/runtime، گزینههای پاسخ کانال، صفهای تحویل، و helperهای اتصال session/thread |
|
||||
| `/codeql-critical-quality/provider-runtime-boundary` | normalization کاتالوگ مدل، auth و discovery مربوط به provider، ثبت provider runtime، defaults/catalogs مربوط به provider، و registryهای web/search/fetch/embedding |
|
||||
| `/codeql-critical-quality/ui-control-plane` | bootstrap رابط کنترل، persistence محلی، جریانهای کنترل Gateway، و قراردادهای runtime سطح کنترل task |
|
||||
| `/codeql-critical-quality/web-media-runtime-boundary` | fetch/search وب هسته، media IO، درک رسانه، image-generation، و قراردادهای runtime مربوط به media-generation |
|
||||
| `/codeql-critical-quality/plugin-boundary` | قراردادهای loader، registry، public-surface، و entrypointهای Plugin SDK |
|
||||
| `/codeql-critical-quality/plugin-sdk-package-contract` | سورس منتشرشده Plugin SDK در سمت بسته و helperهای قرارداد بسته Plugin |
|
||||
| `/codeql-critical-quality/core-auth-secrets` | کد مرز امنیتی احراز هویت، اسرار، sandbox، cron، و gateway |
|
||||
| `/codeql-critical-quality/config-boundary` | قراردادهای schema، migration، normalization، و IO پیکربندی |
|
||||
| `/codeql-critical-quality/gateway-runtime-boundary` | schemaهای پروتکل Gateway و قراردادهای متد سرور |
|
||||
| `/codeql-critical-quality/channel-runtime-boundary` | قراردادهای پیادهسازی کانال هسته و Plugin کانال bundled |
|
||||
| `/codeql-critical-quality/agent-runtime-boundary` | اجرای دستور، dispatch مدل/provider، dispatch و صفهای auto-reply، و قراردادهای زماناجرای صفحه کنترل ACP |
|
||||
| `/codeql-critical-quality/mcp-process-runtime-boundary` | سرورهای MCP و پلهای ابزار، کمکگرهای نظارت بر فرایند، و قراردادهای تحویل خروجی |
|
||||
| `/codeql-critical-quality/memory-runtime-boundary` | SDK میزبان memory، نماهای زماناجرای memory، aliasهای Plugin SDK مربوط به memory، چسب فعالسازی زماناجرای memory، و دستورهای doctor مربوط به memory |
|
||||
| `/codeql-critical-quality/session-diagnostics-boundary` | اجزای داخلی صف پاسخ، صفهای تحویل نشست، کمکگرهای اتصال/تحویل نشست خروجی، سطوح بسته رویداد/لاگ تشخیصی، و قراردادهای CLI مربوط به session doctor |
|
||||
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | dispatch پاسخ ورودی Plugin SDK، کمکگرهای payload/chunking/runtime پاسخ، گزینههای پاسخ کانال، صفهای تحویل، و کمکگرهای اتصال نشست/thread |
|
||||
| `/codeql-critical-quality/provider-runtime-boundary` | normalization کاتالوگ مدل، احراز هویت و discovery provider، ثبت زماناجرای provider، پیشفرضها/کاتالوگهای provider، و registryهای web/search/fetch/embedding |
|
||||
| `/codeql-critical-quality/ui-control-plane` | bootstrap رابط کنترل، ماندگاری محلی، جریانهای کنترل gateway، و قراردادهای زماناجرای صفحه کنترل task |
|
||||
| `/codeql-critical-quality/web-media-runtime-boundary` | fetch/search وب هسته، IO رسانه، درک رسانه، تولید تصویر، و قراردادهای زماناجرای تولید رسانه |
|
||||
| `/codeql-critical-quality/plugin-boundary` | قراردادهای loader، registry، سطح عمومی، و نقطه ورود Plugin SDK |
|
||||
| `/codeql-critical-quality/plugin-sdk-package-contract` | منبع Plugin SDK در سمت بسته منتشرشده و کمکگرهای قرارداد بسته Plugin |
|
||||
|
||||
کیفیت از امنیت جدا میماند تا یافتههای کیفیت بتوانند زمانبندی، اندازهگیری، غیرفعال، یا گسترش داده شوند بدون آنکه سیگنال امنیتی را مبهم کنند. گسترش CodeQL برای Swift، Python، و Pluginهای همراه باید فقط بعد از پایدار شدن runtime و سیگنال پروفایلهای محدود، بهعنوان کار پیگیری scoped یا sharded اضافه شود.
|
||||
کیفیت جدا از امنیت میماند تا یافتههای کیفیت بتوانند بدون مبهم کردن سیگنال امنیتی زمانبندی، اندازهگیری، غیرفعال، یا گسترش داده شوند. گسترش CodeQL برای Swift، Python، و Pluginهای bundled باید فقط پس از پایدار شدن زماناجرا و سیگنال پروفایلهای محدود، بهعنوان کار پیگیری scoped یا sharded دوباره اضافه شود.
|
||||
|
||||
## گردشکارهای نگهداری
|
||||
## گردشکارهای نگهداری
|
||||
|
||||
### عامل مستندات
|
||||
|
||||
گردشکار `Docs Agent` یک مسیر نگهداری event-driven در Codex برای همسو نگه داشتن مستندات موجود با تغییرات تازه land شده است. schedule خالص ندارد: یک اجرای CI موفق push غیرbot روی `main` میتواند آن را trigger کند، و dispatch دستی میتواند آن را مستقیماً اجرا کند. invocationهای workflow-run وقتی `main` جلو رفته باشد یا وقتی یک اجرای non-skipped دیگر Docs Agent در یک ساعت گذشته ساخته شده باشد skip میشوند. وقتی اجرا میشود، بازه commit از SHA منبع Docs Agent غیر skip شده قبلی تا `main` فعلی را review میکند، بنابراین یک اجرای ساعتی میتواند همه تغییرات main انباشتهشده از آخرین گذر مستندات را پوشش دهد.
|
||||
گردشکار `Docs Agent` یک مسیر نگهداری Codex رویدادمحور برای همسو نگه داشتن مستندات موجود با تغییرات تازه land شده است. schedule خالص ندارد: اجرای موفق CI مربوط به push غیررباتی روی `main` میتواند آن را تحریک کند، و dispatch دستی میتواند آن را مستقیم اجرا کند. فراخوانیهای workflow-run وقتی `main` جلو رفته باشد یا وقتی در یک ساعت گذشته اجرای غیر skipped دیگری از Docs Agent ساخته شده باشد، skip میشوند. هنگام اجرا، بازه commit از SHA منبع قبلی غیر skipped Docs Agent تا `main` فعلی را بازبینی میکند، بنابراین یک اجرای ساعتی میتواند همه تغییرات main انباشتهشده از آخرین گذر مستندات را پوشش دهد.
|
||||
|
||||
### عامل کارایی تست
|
||||
|
||||
گردشکار `Test Performance Agent` یک مسیر نگهداری event-driven در Codex برای تستهای کند است. schedule خالص ندارد: یک اجرای CI موفق push غیرbot روی `main` میتواند آن را trigger کند، اما اگر invocation دیگری از workflow-run همان روز UTC قبلاً اجرا شده باشد یا در حال اجرا باشد skip میشود. dispatch دستی از آن gate فعالیت روزانه عبور میکند. این مسیر یک گزارش کارایی Vitest گروهبندیشده برای full-suite میسازد، به Codex اجازه میدهد فقط fixهای کوچک و coverage-preserving برای کارایی تست انجام دهد نه refactorهای گسترده، سپس گزارش full-suite را دوباره اجرا میکند و تغییراتی را که شمار تستهای baseline پاسشده را کاهش دهند reject میکند. اگر baseline تستهای failing داشته باشد، Codex فقط میتواند failureهای obvious را fix کند و گزارش full-suite بعد از agent باید pass شود پیش از آنکه چیزی commit شود. وقتی `main` قبل از land شدن push bot جلو میرود، این مسیر patch اعتبارسنجیشده را rebase میکند، `pnpm check:changed` را دوباره اجرا میکند، و push را retry میکند؛ patchهای stale متضاد skip میشوند. از Ubuntu میزبانیشده GitHub استفاده میکند تا action مربوط به Codex بتواند همان وضعیت ایمنی drop-sudo را مانند docs agent حفظ کند.
|
||||
گردشکار `Test Performance Agent` یک مسیر نگهداری Codex رویدادمحور برای تستهای کند است. schedule خالص ندارد: اجرای موفق CI مربوط به push غیررباتی روی `main` میتواند آن را تحریک کند، اما اگر فراخوانی workflow-run دیگری در همان روز UTC قبلاً اجرا شده یا در حال اجرا باشد، skip میشود. dispatch دستی آن دروازه فعالیت روزانه را دور میزند. این مسیر یک گزارش کارایی Vitest گروهبندیشده برای مجموعه کامل میسازد، به Codex اجازه میدهد فقط اصلاحات کوچک کارایی تست را که پوشش را حفظ میکنند انجام دهد نه refactorهای گسترده، سپس گزارش مجموعه کامل را دوباره اجرا میکند و تغییراتی را که تعداد تستهای پاسشده baseline را کاهش دهند رد میکند. اگر baseline تستهای failing داشته باشد، Codex فقط میتواند failureهای آشکار را اصلاح کند و گزارش مجموعه کامل پس از agent باید پیش از commit شدن هر چیزی pass شود. وقتی `main` پیش از land شدن push ربات جلو میرود، مسیر patch اعتبارسنجیشده را rebase میکند، `pnpm check:changed` را دوباره اجرا میکند، و push را retry میکند؛ patchهای stale متعارض skip میشوند. از Ubuntu میزبانیشده GitHub استفاده میکند تا action مربوط به Codex بتواند همان وضعیت ایمنی drop-sudo را مانند عامل مستندات حفظ کند.
|
||||
|
||||
### PRهای تکراری پس از Merge
|
||||
### درخواستهای PR تکراری پس از Merge
|
||||
|
||||
گردشکار `Duplicate PRs After Merge` یک گردشکار دستی maintainer برای پاکسازی duplicate پس از land است. بهصورت پیشفرض dry-run است و فقط زمانی PRهای صراحتاً فهرستشده را میبندد که `apply=true` باشد. پیش از mutation در GitHub، بررسی میکند که PR land شده merge شده باشد و هر duplicate یا یک issue referenced مشترک داشته باشد یا hunkهای changed همپوشان.
|
||||
گردشکار `Duplicate PRs After Merge` یک گردشکار دستی maintainer برای پاکسازی duplicate پس از land است. بهصورت پیشفرض dry-run است و فقط وقتی `apply=true` باشد PRهای صراحتاً فهرستشده را میبندد. پیش از تغییر GitHub، بررسی میکند که PR land شده merge شده باشد و هر duplicate یا issue ارجاعشده مشترک داشته باشد یا hunkهای تغییر یافته همپوشان داشته باشد.
|
||||
|
||||
```bash
|
||||
gh workflow run duplicate-after-merge.yml \
|
||||
@ -460,29 +460,29 @@ gh workflow run duplicate-after-merge.yml \
|
||||
-f apply=true
|
||||
```
|
||||
|
||||
## gateهای بررسی محلی و مسیریابی تغییرات
|
||||
## دروازههای بررسی محلی و مسیریابی تغییرات
|
||||
|
||||
منطق changed-lane محلی در `scripts/changed-lanes.mjs` قرار دارد و توسط `scripts/check-changed.mjs` اجرا میشود. آن gate بررسی محلی نسبت به محدوده گسترده پلتفرم CI درباره مرزهای architecture سختگیرتر است:
|
||||
منطق changed-lane محلی در `scripts/changed-lanes.mjs` قرار دارد و توسط `scripts/check-changed.mjs` اجرا میشود. آن دروازه بررسی محلی نسبت به دامنه گسترده پلتفرم CI درباره مرزهای معماری سختگیرتر است:
|
||||
|
||||
- تغییرات production هسته، typecheck مربوط به core prod و core test بههمراه lint/guardهای هسته را اجرا میکنند؛
|
||||
- تغییرات فقط تست هسته، فقط typecheck مربوط به core test بههمراه lint هسته را اجرا میکنند؛
|
||||
- تغییرات production در extension، typecheck مربوط به extension prod و extension test بههمراه lint extension را اجرا میکنند؛
|
||||
- تغییرات فقط تست extension، typecheck مربوط به extension test بههمراه lint extension را اجرا میکنند؛
|
||||
- تغییرات public Plugin SDK یا plugin-contract به typecheck extension گسترش مییابند چون extensionها به آن قراردادهای هسته وابستهاند (sweepهای Vitest extension کار تست explicit باقی میمانند)؛
|
||||
- version bumpهای فقط release metadata، checkهای targeted مربوط به version/config/root-dependency را اجرا میکنند؛
|
||||
- تغییرات ناشناخته root/config بهصورت fail-safe به همه check laneها میروند.
|
||||
- تغییرات تولیدی هسته، typecheck تولید و تست هسته بهعلاوه lint/guardهای هسته را اجرا میکنند؛
|
||||
- تغییرات فقط تست هسته، فقط typecheck تست هسته بهعلاوه lint هسته را اجرا میکنند؛
|
||||
- تغییرات تولیدی extension، typecheck تولید و تست extension بهعلاوه lint extension را اجرا میکنند؛
|
||||
- تغییرات فقط تست extension، typecheck تست extension بهعلاوه lint extension را اجرا میکنند؛
|
||||
- تغییرات عمومی Plugin SDK یا plugin-contract به typecheck extension گسترش مییابند، چون extensions به آن قراردادهای هسته وابستهاند (جاروبهای Vitest مربوط به extension همچنان کار تست صریح میمانند)؛
|
||||
- افزایش نسخههای فقط metadata انتشار، بررسیهای هدفمند version/config/root-dependency را اجرا میکنند؛
|
||||
- تغییرات ناشناخته root/config برای fail safe به همه مسیرهای بررسی میروند.
|
||||
|
||||
مسیریابی changed-test محلی در `scripts/test-projects.test-support.mjs` قرار دارد و عمداً از `check:changed` ارزانتر است: ویرایشهای مستقیم تست خودشان را اجرا میکنند، ویرایشهای source mappingهای explicit را ترجیح میدهند، سپس تستهای sibling و dependentهای import-graph. پیکربندی shared group-room delivery یکی از mappingهای explicit است: تغییرات در پیکربندی visible-reply گروه، حالت source reply delivery، یا system prompt ابزار پیام از مسیر تستهای پاسخ هسته بههمراه regressionهای تحویل Discord و Slack عبور میکنند تا یک تغییر پیشفرض shared پیش از اولین push PR fail شود. از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` فقط وقتی استفاده کنید که تغییر به اندازهای harness-wide باشد که مجموعه mapped ارزان proxy قابل اعتمادی نباشد.
|
||||
مسیریابی changed-test محلی در `scripts/test-projects.test-support.mjs` قرار دارد و عمداً از `check:changed` ارزانتر است: ویرایشهای مستقیم تست خودشان را اجرا میکنند، ویرایشهای source نگاشتهای صریح را ترجیح میدهند، سپس تستهای sibling و وابستههای import-graph را اجرا میکنند. پیکربندی shared group-room delivery یکی از نگاشتهای صریح است: تغییرات در پیکربندی visible-reply گروه، حالت تحویل پاسخ source، یا prompt سیستمی message-tool از مسیر تستهای پاسخ هسته بهعلاوه regressionهای تحویل Discord و Slack عبور میکنند تا تغییر پیشفرض مشترک پیش از نخستین push PR شکست بخورد. فقط وقتی تغییر آنقدر در سطح harness گسترده است که مجموعه نگاشتشده ارزان proxy قابل اعتمادی نیست، از `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` استفاده کنید.
|
||||
|
||||
## اعتبارسنجی Testbox
|
||||
|
||||
Testbox را از ریشهی مخزن اجرا کنید و برای راستیآزمایی گسترده، یک باکس گرمشدهی تازه را ترجیح دهید. پیش از صرف کردن یک گیت زمانبر روی باکسی که دوباره استفاده شده، منقضی شده، یا همین حالا همگامسازی غیرمنتظرهای بزرگ را گزارش کرده است، ابتدا `pnpm testbox:sanity` را داخل باکس اجرا کنید.
|
||||
Testbox را از ریشه مخزن اجرا کنید و برای اعتبارسنجی گسترده، یک باکس گرمشده تازه را ترجیح دهید. پیش از صرف یک گیت کند روی باکسی که دوباره استفاده شده، منقضی شده، یا همین حالا همگامسازی غیرمنتظره بزرگی گزارش کرده است، ابتدا `pnpm testbox:sanity` را داخل باکس اجرا کنید.
|
||||
|
||||
بررسی سلامت وقتی فایلهای ریشهی لازم مانند `pnpm-lock.yaml` ناپدید شده باشند یا وقتی `git status --short` دستکم ۲۰۰ حذف ردیابیشده را نشان دهد، سریع شکست میخورد. این معمولاً یعنی وضعیت همگامسازی ریموت نسخهی قابلاعتمادی از درخواست کشش نیست؛ بهجای عیبیابی شکست تست محصول، آن باکس را متوقف کنید و یک باکس تازه را گرم کنید. برای درخواستهای کشش با حذفهای بزرگ و عمدی، برای آن اجرای سلامت `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` را تنظیم کنید.
|
||||
بررسی سلامت وقتی فایلهای ضروری ریشه مانند `pnpm-lock.yaml` ناپدید شده باشند یا وقتی `git status --short` دستکم ۲۰۰ حذف ردیابیشده نشان دهد، سریع شکست میخورد. این معمولاً یعنی وضعیت همگامسازی راهدور کپی قابل اعتمادی از درخواست کشش نیست؛ بهجای اشکالزدایی شکست تست محصول، آن باکس را متوقف کنید و یک باکس تازه را گرم کنید. برای درخواستهای کشش با حذفهای بزرگ عمدی، برای آن اجرای سلامت `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` را تنظیم کنید.
|
||||
|
||||
`pnpm testbox:run` همچنین اجرای محلی Blacksmith CLI را که بیش از پنج دقیقه بدون خروجی پس از همگامسازی در مرحلهی همگامسازی بماند، خاتمه میدهد. برای غیرفعال کردن این محافظ، `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` را تنظیم کنید، یا برای اختلافهای محلی غیرمعمول بزرگ، مقدار بزرگتری بر حسب میلیثانیه استفاده کنید.
|
||||
`pnpm testbox:run` همچنین فراخوانی محلی Blacksmith CLI را که بیش از پنج دقیقه بدون خروجی پس از همگامسازی در مرحله همگامسازی بماند، خاتمه میدهد. برای غیرفعال کردن آن محافظ، `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0` را تنظیم کنید، یا برای تغییرات محلی غیرعادی بزرگ، مقدار بزرگتری بر حسب میلیثانیه استفاده کنید.
|
||||
|
||||
Crabbox مسیر دوم باکس ریموتِ متعلق به مخزن برای راستیآزمایی Linux است، وقتی Blacksmith در دسترس نیست یا وقتی ظرفیت ابری تحت مالکیت ترجیح دارد. یک باکس را گرم کنید، آن را از طریق گردشکار پروژه آبرسانی کنید، سپس فرمانها را از طریق Crabbox CLI اجرا کنید:
|
||||
Crabbox مسیر دوم باکس راهدور متعلق به مخزن برای اعتبارسنجی Linux است، وقتی Blacksmith در دسترس نیست یا ظرفیت ابری مالکیتشده ترجیح دارد. یک باکس را گرم کنید، آن را از طریق گردشکار پروژه هیدراته کنید، سپس فرمانها را از طریق Crabbox CLI اجرا کنید:
|
||||
|
||||
```bash
|
||||
pnpm crabbox:warmup -- --idle-timeout 90m
|
||||
@ -491,7 +491,7 @@ pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed
|
||||
pnpm crabbox:stop -- <cbx_id>
|
||||
```
|
||||
|
||||
`.crabbox.yaml` مالک پیشفرضهای ارائهدهنده، همگامسازی، و آبرسانی GitHub Actions است. این فایل `.git` محلی را مستثنا میکند تا checkout آبرسانیشدهی Actions بهجای همگامسازی ریموتها و انبارهای آبجکتِ محلیِ نگهدارنده، فرادادهی Git ریموت خودش را نگه دارد، و آرتیفکتهای محلی زمان اجرا/ساخت را که هرگز نباید منتقل شوند مستثنا میکند. `.github/workflows/crabbox-hydrate.yml` مالک checkout، راهاندازی Node/pnpm، دریافت `origin/main`، و تحویل محیط غیرمحرمانهای است که فرمانهای بعدی `crabbox run --id <cbx_id>` از آن source میکنند.
|
||||
`.crabbox.yaml` مالک پیشفرضهای ارائهدهنده، همگامسازی و هیدراتهسازی GitHub Actions است. این فایل `.git` محلی را مستثنی میکند تا checkout هیدراتهشده Actions بهجای همگامسازی remoteها و object storeهای محلی نگهدارنده، فراداده Git راهدور خودش را نگه دارد، و آرتیفکتهای runtime/build محلی را که هرگز نباید منتقل شوند مستثنی میکند. `.github/workflows/crabbox-hydrate.yml` مالک checkout، راهاندازی Node/pnpm، دریافت `origin/main`، و تحویل محیط غیرمحرمانهای است که فرمانهای بعدی `crabbox run --id <cbx_id>` از آن source میکنند.
|
||||
|
||||
## مرتبط
|
||||
|
||||
|
||||
@ -1,151 +1,147 @@
|
||||
---
|
||||
read_when:
|
||||
- ویرایش متن پرامپت سیستم، فهرست ابزارها، یا بخشهای زمان/Heartbeat
|
||||
- تغییر رفتار بوتاسترپ فضای کاری یا تزریق Skills
|
||||
summary: پرامپت سیستمی OpenClaw شامل چه چیزهایی است و چگونه گردآوری میشود
|
||||
- تغییر رفتار راهاندازی اولیهٔ فضای کاری یا تزریق Skills
|
||||
summary: محتوای پرامپت سیستم OpenClaw و نحوهٔ مونتاژ آن
|
||||
title: پرامپت سیستم
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T22:19:17Z"
|
||||
generated_at: "2026-05-02T23:39:08Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 3b8761a8722bb328b937e0832774be7b4e99602ae032c9a255f26843237c110c
|
||||
source_hash: f8e0234453812c16cf5d273096d335049bf435ca76ade36200caf4bb344624e5
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw برای هر اجرای عامل، یک پرامپت سیستمی سفارشی میسازد. این پرامپت **متعلق به OpenClaw** است و از پرامپت پیشفرض pi-coding-agent استفاده نمیکند.
|
||||
OpenClaw برای هر اجرای عامل، یک اعلان سیستمی سفارشی میسازد. این اعلان **متعلق به OpenClaw** است و از اعلان پیشفرض pi-coding-agent استفاده نمیکند.
|
||||
|
||||
پرامپت توسط OpenClaw مونتاژ میشود و به هر اجرای عامل تزریق میشود.
|
||||
اعلان توسط OpenClaw سرهمبندی میشود و در هر اجرای عامل تزریق میشود.
|
||||
|
||||
Pluginهای ارائهدهنده میتوانند راهنمایی پرامپت آگاه از کش را بدون جایگزینکردن
|
||||
کل پرامپت متعلق به OpenClaw اضافه کنند. runtime ارائهدهنده میتواند:
|
||||
Pluginهای ارائهدهنده میتوانند راهنمایی اعلانِ آگاه از کش را بدون جایگزینکردن
|
||||
کل اعلان متعلق به OpenClaw اضافه کنند. runtime ارائهدهنده میتواند:
|
||||
|
||||
- مجموعه کوچکی از بخشهای هسته نامدار را جایگزین کند (`interaction_style`,
|
||||
- مجموعه کوچکی از بخشهای هستهای نامدار را جایگزین کند (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- یک **پیشوند پایدار** را بالای مرز کش پرامپت تزریق کند
|
||||
- یک **پسوند پویا** را پایین مرز کش پرامپت تزریق کند
|
||||
- یک **پیشوند پایدار** بالای مرز کش اعلان تزریق کند
|
||||
- یک **پسوند پویا** پایین مرز کش اعلان تزریق کند
|
||||
|
||||
از مشارکتهای متعلق به ارائهدهنده برای تنظیم مخصوص خانواده مدل استفاده کنید. جهش پرامپت قدیمی
|
||||
`before_prompt_build` را برای سازگاری یا تغییرات واقعا سراسری پرامپت نگه دارید،
|
||||
از مشارکتهای متعلق به ارائهدهنده برای تنظیمهای خاص خانواده مدل استفاده کنید. جهش اعلانِ قدیمی
|
||||
`before_prompt_build` را برای سازگاری یا تغییرات واقعاً سراسری اعلان نگه دارید،
|
||||
نه رفتار عادی ارائهدهنده.
|
||||
|
||||
همپوشانی خانواده OpenAI GPT-5 قانون اجرای هسته را کوچک نگه میدارد و
|
||||
راهنماییهای مخصوص مدل را برای قفلشدن پرسونا، خروجی مختصر، انضباط ابزار،
|
||||
جستوجوی موازی، پوشش خروجیهای قابل تحویل، راستیآزمایی، زمینه گمشده، و
|
||||
لایه OpenAI خانواده GPT-5 قاعده اجرای هسته را کوچک نگه میدارد و
|
||||
راهنمایی ویژه مدل را برای چسبیدن به پرسونا، خروجی مختصر، انضباط ابزار،
|
||||
جستوجوی موازی، پوشش تحویلدادنیها، راستیآزمایی، زمینه مفقود، و
|
||||
بهداشت ابزار ترمینال اضافه میکند.
|
||||
|
||||
## ساختار
|
||||
|
||||
پرامپت عمدا فشرده است و از بخشهای ثابت استفاده میکند:
|
||||
اعلان عمداً فشرده است و از بخشهای ثابت استفاده میکند:
|
||||
|
||||
- **ابزارها**: یادآور منبع حقیقت ابزار ساختیافته همراه با راهنمای استفاده از ابزار در runtime.
|
||||
- **سوگیری اجرا**: راهنمای پیگیری فشرده: روی درخواستهای قابل اقدام در همان نوبت
|
||||
عمل کن، تا اتمام یا مسدودشدن ادامه بده، از نتایج ضعیف ابزار بازیابی کن،
|
||||
وضعیت تغییرپذیر را زنده بررسی کن، و پیش از نهاییکردن راستیآزمایی کن.
|
||||
- **ابزارها**: یادآور منبع حقیقت ابزار ساختیافته بهعلاوه راهنمایی runtime برای استفاده از ابزار.
|
||||
- **سوگیری اجرا**: راهنمایی فشرده برای پیگیری تا پایان: روی درخواستهای
|
||||
قابل اقدام در همان نوبت عمل کنید، تا انجامشدن یا مسدودشدن ادامه دهید، از نتایج
|
||||
ضعیف ابزار بازیابی کنید، وضعیت قابل تغییر را زنده بررسی کنید، و پیش از نهاییکردن راستیآزمایی کنید.
|
||||
- **ایمنی**: یادآور کوتاه حفاظتی برای پرهیز از رفتار قدرتطلبانه یا دورزدن نظارت.
|
||||
- **Skills** (در صورت وجود): به مدل میگوید چگونه دستورالعملهای skill را هنگام نیاز بارگذاری کند.
|
||||
- **خودبهروزرسانی OpenClaw**: چگونگی بررسی امن پیکربندی با
|
||||
`config.schema.lookup`، وصلهکردن پیکربندی با `config.patch`، جایگزینکردن کل
|
||||
پیکربندی با `config.apply`، و اجرای `update.run` فقط با درخواست صریح کاربر.
|
||||
- **Skills** (در صورت موجودبودن): به مدل میگوید چگونه دستورالعملهای skill را هنگام نیاز بارگذاری کند.
|
||||
- **خودبهروزرسانی OpenClaw**: نحوه بررسی ایمن پیکربندی با
|
||||
`config.schema.lookup`، وصلهکردن پیکربندی با `config.patch`، جایگزینی کامل
|
||||
پیکربندی با `config.apply`، و اجرای `update.run` فقط در صورت درخواست صریح کاربر.
|
||||
ابزار فقط-مالک `gateway` همچنین از بازنویسی
|
||||
`tools.exec.ask` / `tools.exec.security` خودداری میکند، از جمله نامهای مستعار قدیمی
|
||||
`tools.bash.*` که به آن مسیرهای exec محافظتشده نرمالسازی میشوند.
|
||||
- **فضای کاری**: پوشه کاری (`agents.defaults.workspace`).
|
||||
- **مستندات**: مسیر محلی مستندات OpenClaw (repo یا بسته npm) و زمان خواندن آنها.
|
||||
- **فایلهای فضای کاری (تزریقشده)**: نشان میدهد فایلهای bootstrap در پایین آمدهاند.
|
||||
- **Sandbox** (در صورت فعالبودن): runtime سندباکسشده، مسیرهای sandbox، و اینکه exec ارتقایافته در دسترس است یا نه را نشان میدهد.
|
||||
- **تاریخ و زمان فعلی**: زمان محلی کاربر، منطقه زمانی، و قالب زمان.
|
||||
`tools.exec.ask` / `tools.exec.security` خودداری میکند، از جمله نامهای مستعار قدیمی `tools.bash.*`
|
||||
که به آن مسیرهای محافظتشده exec نرمالسازی میشوند.
|
||||
- **Workspace**: پوشه کاری (`agents.defaults.workspace`).
|
||||
- **مستندات**: مسیر محلی به مستندات OpenClaw (repo یا بسته npm) و زمان خواندن آنها.
|
||||
- **فایلهای Workspace (تزریقشده)**: نشان میدهد فایلهای راهاندازی در ادامه گنجانده شدهاند.
|
||||
- **Sandbox** (وقتی فعال باشد): runtime سندباکسشده، مسیرهای sandbox، و اینکه exec ارتقایافته در دسترس است یا نه را نشان میدهد.
|
||||
- **تاریخ و زمان کنونی**: زمان محلی کاربر، منطقه زمانی، و قالب زمان.
|
||||
- **برچسبهای پاسخ**: نحو اختیاری برچسب پاسخ برای ارائهدهندگان پشتیبانیشده.
|
||||
- **Heartbeatها**: پرامپت Heartbeat و رفتار تایید، وقتی Heartbeatها برای عامل پیشفرض فعال هستند.
|
||||
- **Runtime**: میزبان، سیستمعامل، node، مدل، ریشه repo (در صورت تشخیص)، سطح تفکر (یک خط).
|
||||
- **استدلال**: سطح دید فعلی + راهنمای toggle /reasoning.
|
||||
- **Heartbeatها**: اعلان Heartbeat و رفتار ack، وقتی Heartbeatها برای عامل پیشفرض فعال باشند.
|
||||
- **Runtime**: میزبان، OS، node، مدل، ریشه repo (وقتی شناسایی شود)، سطح تفکر (یک خط).
|
||||
- **استدلال**: سطح دیدپذیری کنونی + راهنمای تغییر وضعیت /reasoning.
|
||||
|
||||
OpenClaw محتوای پایدار بزرگ، از جمله **زمینه پروژه**، را بالای
|
||||
مرز کش داخلی پرامپت نگه میدارد. بخشهای فرّار کانال/نشست مانند
|
||||
راهنمای embed رابط کنترل، **پیامرسانی**، **صدا**، **زمینه گفتوگوی گروهی**،
|
||||
OpenClaw محتوای بزرگ و پایدار، از جمله **زمینه پروژه**، را بالای
|
||||
مرز داخلی کش اعلان نگه میدارد. بخشهای ناپایدار کانال/نشست مانند
|
||||
راهنمای جاسازی Control UI، **پیامرسانی**، **صدا**، **زمینه گفتوگوی گروهی**،
|
||||
**واکنشها**، **Heartbeatها**، و **Runtime** پایین آن مرز افزوده میشوند
|
||||
تا backendهای محلی با کشهای پیشوند بتوانند از پیشوند پایدار فضای کاری
|
||||
در نوبتهای کانال دوباره استفاده کنند. توضیحات ابزار نیز به همین شکل باید از
|
||||
درج نامهای فعلی کانال خودداری کنند، وقتی schema پذیرفتهشده از قبل آن جزئیات runtime را حمل میکند.
|
||||
تا backendهای محلی با کشهای پیشوند بتوانند پیشوند پایدار workspace را
|
||||
در نوبتهای کانال بازاستفاده کنند. توضیحات ابزار نیز باید از جاسازی نامهای
|
||||
کنونی کانال خودداری کنند، وقتی schema پذیرفتهشده همان جزئیات runtime را از قبل حمل میکند.
|
||||
|
||||
بخش ابزارها همچنین راهنمای runtime برای کارهای طولانیمدت را شامل میشود:
|
||||
بخش ابزارها همچنین راهنمایی runtime برای کارهای طولانیمدت را شامل میشود:
|
||||
|
||||
- از cron برای پیگیری آینده (`check back later`، یادآورها، کارهای تکرارشونده)
|
||||
بهجای حلقههای sleep در `exec`، ترفندهای تاخیر `yieldMs`، یا polling تکراری
|
||||
`process` استفاده کنید
|
||||
- از `exec` / `process` فقط برای فرمانهایی استفاده کنید که اکنون شروع میشوند و
|
||||
در پسزمینه ادامه پیدا میکنند
|
||||
- وقتی wake تکمیل خودکار فعال است، فرمان را یک بار شروع کنید و به مسیر wake مبتنی بر push
|
||||
هنگام تولید خروجی یا شکست آن تکیه کنید
|
||||
- وقتی لازم است یک فرمان در حال اجرا را بررسی کنید، برای لاگها، وضعیت، ورودی، یا مداخله
|
||||
از `process` استفاده کنید
|
||||
- اگر کار بزرگتر است، `sessions_spawn` را ترجیح دهید؛ تکمیل زیرعامل
|
||||
مبتنی بر push است و خودکار به درخواستکننده اعلام میشود
|
||||
- برای پیگیری آینده (`check back later`، یادآورها، کارهای تکرارشونده) از cron استفاده کنید
|
||||
بهجای حلقههای sleep در `exec`، ترفندهای تأخیر `yieldMs`، یا polling تکراری `process`
|
||||
- از `exec` / `process` فقط برای دستورهایی استفاده کنید که اکنون شروع میشوند و
|
||||
در پسزمینه به اجرا ادامه میدهند
|
||||
- وقتی بیدارباش تکمیل خودکار فعال است، دستور را یکبار شروع کنید و به
|
||||
مسیر بیدارباش push-based تکیه کنید وقتی خروجی منتشر میکند یا شکست میخورد
|
||||
- وقتی لازم است یک دستور در حال اجرا را بررسی کنید، از `process` برای لاگها، وضعیت، ورودی، یا مداخله استفاده کنید
|
||||
- اگر وظیفه بزرگتر است، `sessions_spawn` را ترجیح دهید؛ تکمیل زیرعامل
|
||||
push-based است و خودکار به درخواستکننده اعلام میشود
|
||||
- فقط برای انتظار تکمیل، `subagents list` / `sessions_list` را در حلقه poll نکنید
|
||||
|
||||
وقتی ابزار آزمایشی `update_plan` فعال است، ابزارها همچنین به
|
||||
مدل میگوید که فقط برای کارهای چندمرحلهای غیرساده از آن استفاده کند، دقیقا یک
|
||||
مرحله `in_progress` نگه دارد، و پس از هر بهروزرسانی کل برنامه را تکرار نکند.
|
||||
وقتی ابزار آزمایشی `update_plan` فعال باشد، بخش ابزارها همچنین به
|
||||
مدل میگوید آن را فقط برای کارهای چندمرحلهای غیرساده استفاده کند، دقیقاً یک
|
||||
گام `in_progress` نگه دارد، و از تکرار کل برنامه پس از هر بهروزرسانی خودداری کند.
|
||||
|
||||
حفاظهای ایمنی در پرامپت سیستمی مشورتی هستند. آنها رفتار مدل را هدایت میکنند اما سیاست را enforce نمیکنند. برای enforce سخت از سیاست ابزار، تاییدهای exec، sandboxing، و allowlistهای کانال استفاده کنید؛ اپراتورها طبق طراحی میتوانند اینها را غیرفعال کنند.
|
||||
حفاظهای ایمنی در اعلان سیستمی جنبه راهنمایی دارند. آنها رفتار مدل را هدایت میکنند اما سیاست را اعمال نمیکنند. برای اعمال سختگیرانه از سیاست ابزار، تأییدهای exec، sandboxing، و allowlistهای کانال استفاده کنید؛ اپراتورها عمداً میتوانند اینها را غیرفعال کنند.
|
||||
|
||||
در کانالهایی با کارتها/دکمههای تایید بومی، پرامپت runtime اکنون به
|
||||
عامل میگوید ابتدا به همان رابط تایید بومی تکیه کند. فقط وقتی نتیجه ابزار میگوید تاییدهای چت در دسترس نیستند یا
|
||||
تایید دستی تنها مسیر است، باید فرمان دستی
|
||||
`/approve` را شامل کند.
|
||||
در کانالهایی با کارتها/دکمههای تأیید بومی، اعلان runtime اکنون به
|
||||
عامل میگوید ابتدا به همان UI تأیید بومی تکیه کند. فقط وقتی باید دستور دستی
|
||||
`/approve` را درج کند که نتیجه ابزار بگوید تأییدهای چت در دسترس نیستند یا
|
||||
تأیید دستی تنها مسیر است.
|
||||
|
||||
## حالتهای پرامپت
|
||||
## حالتهای اعلان
|
||||
|
||||
OpenClaw میتواند پرامپتهای سیستمی کوچکتری برای زیرعاملها render کند. runtime برای هر اجرا یک
|
||||
`promptMode` تنظیم میکند (نه یک پیکربندی قابل مشاهده برای کاربر):
|
||||
OpenClaw میتواند اعلانهای سیستمی کوچکتری برای زیرعاملها رندر کند. runtime برای هر اجرا یک
|
||||
`promptMode` تنظیم میکند (نه یک پیکربندی رو به کاربر):
|
||||
|
||||
- `full` (پیشفرض): همه بخشهای بالا را شامل میشود.
|
||||
- `minimal`: برای زیرعاملها استفاده میشود؛ **Skills**، **Memory Recall**، **خودبهروزرسانی OpenClaw**،
|
||||
**نامهای مستعار مدل**، **هویت کاربر**، **برچسبهای پاسخ**،
|
||||
**پیامرسانی**، **پاسخهای بیصدا**، و **Heartbeatها** را حذف میکند. ابزارها، **ایمنی**،
|
||||
فضای کاری، Sandbox، تاریخ و زمان فعلی (در صورت دانستهبودن)، Runtime، و زمینه تزریقشده
|
||||
در دسترس میمانند.
|
||||
**پیامرسانی**، **پاسخهای خاموش**، و **Heartbeatها** را حذف میکند. ابزارها، **ایمنی**،
|
||||
Workspace، Sandbox، تاریخ و زمان کنونی (وقتی شناخته شده باشد)، Runtime، و زمینه تزریقشده
|
||||
همچنان در دسترس میمانند.
|
||||
- `none`: فقط خط هویت پایه را برمیگرداند.
|
||||
|
||||
وقتی `promptMode=minimal` باشد، پرامپتهای تزریقشده اضافی بهجای **زمینه گفتوگوی گروهی**
|
||||
با **زمینه زیرعامل** برچسبگذاری میشوند.
|
||||
وقتی `promptMode=minimal` باشد، اعلانهای تزریقشده اضافی بهجای **زمینه گفتوگوی گروهی** با برچسب **زمینه زیرعامل** مشخص میشوند.
|
||||
|
||||
برای اجراهای پاسخ خودکار کانال، OpenClaw میتواند بخش عمومی **پاسخهای بیصدا**
|
||||
را حذف کند، وقتی زمینه چت مستقیم/گروهی از قبل رفتار
|
||||
`NO_REPLY` مخصوص گفتوگوی حلشده را شامل میشود. این کار از تکرار مکانیک توکن
|
||||
در هر دو پرامپت سیستمی سراسری و زمینه کانال جلوگیری میکند.
|
||||
برای اجراهای پاسخ خودکار کانال، OpenClaw میتواند بخش عمومی **پاسخهای خاموش**
|
||||
را حذف کند وقتی زمینه چت مستقیم/گروهی از قبل رفتار
|
||||
مختص گفتوگوی حلشده `NO_REPLY` را شامل میشود. این کار از تکرار مکانیک توکن
|
||||
هم در اعلان سیستمی سراسری و هم در زمینه کانال جلوگیری میکند.
|
||||
|
||||
## snapshotهای پرامپت
|
||||
## snapshotهای اعلان
|
||||
|
||||
OpenClaw snapshotهای مسیر موفق commitشده را برای runtime ابزار پیام/Codex
|
||||
در `test/fixtures/agents/prompt-snapshots/happy-path/` نگه میدارد. آنها
|
||||
پارامترهای منتخب thread/turn سرور برنامه را همراه با یک stack بازسازیشده لایههای پرامپت متصل به مدل
|
||||
برای نوبتهای مستقیم Telegram، گروه Discord، و heartbeat render میکنند. آن stack
|
||||
شامل یک fixture پینشده پرامپت مدل Codex `gpt-5.5` است که از شکل کاتالوگ/کش مدل Codex
|
||||
تولید شده، متن developer مجوز مسیر موفق Codex،
|
||||
دستورالعملهای developer OpenClaw، ورودی نوبت کاربر، و ارجاعهایی به مشخصات ابزار پویا.
|
||||
OpenClaw snapshotهای اعلان commitشده را برای مسیر موفق runtime Codex زیر
|
||||
`test/fixtures/agents/prompt-snapshots/codex-runtime-happy-path/` نگه میدارد. آنها
|
||||
پارامترهای منتخب thread/turn سرور برنامه بهعلاوه یک پشته لایه اعلان بازسازیشده متصل به مدل
|
||||
را برای نوبتهای مستقیم Telegram، گروه Discord، و Heartbeat رندر میکنند. آن پشته
|
||||
شامل یک fixture اعلان مدل Codex `gpt-5.5` پینشده است که از شکل catalog/cache مدل Codex تولید شده،
|
||||
متن توسعهدهنده مجوز مسیر موفق Codex،
|
||||
دستورالعملهای توسعهدهنده OpenClaw، ورودی نوبت کاربر، و ارجاعها به مشخصات پویای ابزار را شامل میشود.
|
||||
|
||||
fixture پینشده پرامپت مدل Codex را با
|
||||
fixture اعلان مدل Codex پینشده را با
|
||||
`pnpm prompt:snapshots:sync-codex-model` تازهسازی کنید. بهطور پیشفرض، اسکریپت ابتدا بهدنبال
|
||||
کش runtime مربوط به Codex در `$CODEX_HOME/models_cache.json`، سپس
|
||||
`~/.codex/models_cache.json` میگردد، و فقط بعد از آن به قرارداد checkout نگهدارنده Codex
|
||||
در `~/code/codex/codex-rs/models-manager/models.json` fallback میکند. اگر
|
||||
هیچکدام از این منابع وجود نداشته باشند، فرمان بدون تغییر fixture commitشده
|
||||
خارج میشود. برای تازهسازی از یک فایل مشخص `models_cache.json`
|
||||
یا `models.json`، `--catalog <path>` را پاس دهید.
|
||||
کش runtime Codex در `$CODEX_HOME/models_cache.json` میگردد، سپس
|
||||
`~/.codex/models_cache.json`، و فقط بعد از آن به قرارداد checkout نگهدارنده Codex
|
||||
در `~/code/codex/codex-rs/models-manager/models.json` برمیگردد. اگر
|
||||
هیچیک از آن منابع وجود نداشته باشند، دستور بدون تغییر fixture commitشده خارج میشود.
|
||||
برای تازهسازی از یک فایل مشخص `models_cache.json` یا `models.json`، `--catalog <path>` را پاس دهید.
|
||||
|
||||
این snapshotها هنوز capture خام byte-for-byte از درخواست OpenAI نیستند. Codex
|
||||
میتواند زمینه فضای کاری متعلق به runtime مانند `AGENTS.md`، زمینه محیط،
|
||||
این snapshotها هنوز capture خام بایتبهبایت درخواست OpenAI نیستند. Codex
|
||||
میتواند زمینه workspace متعلق به runtime مانند `AGENTS.md`، زمینه محیط،
|
||||
خاطرهها، دستورالعملهای برنامه/Plugin، و دستورالعملهای آینده حالت همکاری
|
||||
را پس از ارسال پارامترهای thread و turn توسط OpenClaw، داخل runtime Codex اضافه کند.
|
||||
را پس از اینکه OpenClaw پارامترهای thread و turn را میفرستد، داخل runtime Codex اضافه کند.
|
||||
|
||||
آنها را با `pnpm prompt:snapshots:gen` دوباره تولید کنید و drift را با
|
||||
`pnpm prompt:snapshots:check` راستیآزمایی کنید. CI بررسی drift را در shard مرزی اضافی اجرا میکند
|
||||
تا تغییرات پرامپت و بهروزرسانیهای snapshot به همان PR متصل بمانند.
|
||||
آنها را با `pnpm prompt:snapshots:gen` بازتولید کنید و drift را با
|
||||
`pnpm prompt:snapshots:check` راستیآزمایی کنید. CI بررسی drift را در shard مرزی
|
||||
اضافی اجرا میکند تا تغییرات اعلان و بهروزرسانیهای snapshot به همان PR متصل بمانند.
|
||||
|
||||
## تزریق bootstrap فضای کاری
|
||||
## تزریق راهاندازی Workspace
|
||||
|
||||
فایلهای bootstrap کوتاهسازی میشوند و زیر **زمینه پروژه** افزوده میشوند تا مدل زمینه هویت و پروفایل را بدون نیاز به خواندن صریح ببیند:
|
||||
فایلهای راهاندازی کوتاه میشوند و زیر **زمینه پروژه** افزوده میشوند تا مدل بدون نیاز به خواندن صریح، زمینه هویت و پروفایل را ببیند:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -153,48 +149,53 @@ fixture پینشده پرامپت مدل Codex را با
|
||||
- `IDENTITY.md`
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (فقط روی فضاهای کاری کاملا جدید)
|
||||
- `MEMORY.md` در صورت وجود
|
||||
- `BOOTSTRAP.md` (فقط در workspaceهای کاملاً جدید)
|
||||
- `MEMORY.md` وقتی موجود باشد
|
||||
|
||||
همه این فایلها در هر نوبت **به پنجره زمینه تزریق میشوند**، مگر اینکه
|
||||
gate مخصوص فایل اعمال شود. `HEARTBEAT.md` در اجراهای عادی وقتی
|
||||
همه این فایلها در هر نوبت **به پنجره زمینه تزریق میشوند** مگر اینکه
|
||||
یک gate مختص فایل اعمال شود. `HEARTBEAT.md` در اجراهای عادی حذف میشود وقتی
|
||||
Heartbeatها برای عامل پیشفرض غیرفعال باشند یا
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` برابر false باشد، حذف میشود. فایلهای تزریقشده
|
||||
را مختصر نگه دارید — بهویژه `MEMORY.md`، که میتواند به مرور زمان رشد کند و باعث
|
||||
مصرف غیرمنتظره بالای زمینه و Compaction مکررتر شود.
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` برابر false باشد. فایلهای تزریقشده
|
||||
را مختصر نگه دارید — بهویژه `MEMORY.md` که میتواند با گذر زمان رشد کند و به
|
||||
مصرف زمینه غیرمنتظره بالا و Compaction مکررتر منجر شود.
|
||||
|
||||
وقتی یک نشست روی harness بومی Codex اجرا میشود، Codex فایل `AGENTS.md`
|
||||
را از طریق کشف سند پروژه خودش بارگذاری میکند. OpenClaw همچنان فایلهای راهاندازی باقیمانده
|
||||
را resolve میکند و آنها را بهعنوان دستورالعملهای پیکربندی Codex ارسال میکند، بنابراین `SOUL.md`،
|
||||
`TOOLS.md`، `IDENTITY.md`، `USER.md`، `HEARTBEAT.md`، `BOOTSTRAP.md`، و
|
||||
`MEMORY.md` همان نقش زمینه workspace را بدون تکرار
|
||||
`AGENTS.md` حفظ میکنند.
|
||||
|
||||
<Note>
|
||||
فایلهای روزانه `memory/*.md` بخشی از زمینه پروژه bootstrap عادی **نیستند**. در نوبتهای معمولی، آنها در صورت نیاز از طریق ابزارهای `memory_search` و `memory_get` دسترسیپذیر هستند، بنابراین مگر اینکه مدل صراحتا آنها را بخواند، در پنجره زمینه حساب نمیشوند. نوبتهای ساده `/new` و `/reset` استثنا هستند: runtime میتواند حافظه روزانه اخیر را بهعنوان یک بلوک startup-context یکباره برای آن نوبت نخست prepend کند.
|
||||
فایلهای روزانه `memory/*.md` بخشی از زمینه پروژه راهاندازی عادی **نیستند**. در نوبتهای معمولی، آنها در صورت نیاز از طریق ابزارهای `memory_search` و `memory_get` در دسترس قرار میگیرند، بنابراین در پنجره زمینه حساب نمیشوند مگر اینکه مدل صراحتاً آنها را بخواند. نوبتهای خالی `/new` و `/reset` استثنا هستند: runtime میتواند حافظه روزانه اخیر را بهعنوان یک بلوک زمینه راهاندازی یکباره برای همان نوبت اول پیشوند کند.
|
||||
</Note>
|
||||
|
||||
فایلهای بزرگ با یک نشانگر truncation کوتاه میشوند. حداکثر اندازه هر فایل توسط
|
||||
`agents.defaults.bootstrapMaxChars` کنترل میشود (پیشفرض: 12000). کل محتوای bootstrap تزریقشده
|
||||
در میان فایلها با `agents.defaults.bootstrapTotalMaxChars` محدود میشود
|
||||
(پیشفرض: 60000). فایلهای گمشده یک نشانگر کوتاه فایل گمشده تزریق میکنند. وقتی truncation
|
||||
فایلهای بزرگ با یک نشانگر کوتاه میشوند. بیشینه اندازه هر فایل توسط
|
||||
`agents.defaults.bootstrapMaxChars` کنترل میشود (پیشفرض: 12000). کل محتوای راهاندازی تزریقشده
|
||||
در همه فایلها با `agents.defaults.bootstrapTotalMaxChars` محدود میشود
|
||||
(پیشفرض: 60000). فایلهای مفقود یک نشانگر کوتاه فایل-مفقود تزریق میکنند. وقتی کوتاهسازی
|
||||
رخ میدهد، OpenClaw میتواند یک بلوک هشدار در زمینه پروژه تزریق کند؛ این را با
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` کنترل کنید (`off`، `once`، `always`؛
|
||||
پیشفرض: `once`).
|
||||
|
||||
نشستهای زیرعامل فقط `AGENTS.md` و `TOOLS.md` را تزریق میکنند (سایر فایلهای bootstrap
|
||||
نشستهای زیرعامل فقط `AGENTS.md` و `TOOLS.md` را تزریق میکنند (فایلهای راهاندازی دیگر
|
||||
برای کوچک نگهداشتن زمینه زیرعامل فیلتر میشوند).
|
||||
|
||||
hookهای داخلی میتوانند این مرحله را از طریق `agent:bootstrap` intercept کنند تا
|
||||
فایلهای bootstrap تزریقشده را جهش دهند یا جایگزین کنند (برای مثال تعویض `SOUL.md` با یک پرسونای جایگزین).
|
||||
hookهای داخلی میتوانند این گام را از طریق `agent:bootstrap` رهگیری کنند تا فایلهای راهاندازی تزریقشده را تغییر دهند یا جایگزین کنند (مثلاً جایگزینکردن `SOUL.md` با یک پرسونای جایگزین).
|
||||
|
||||
اگر میخواهید عامل کمتر عمومی بهنظر برسد، از
|
||||
اگر میخواهید عامل کمتر عمومی بهنظر برسد، با
|
||||
[راهنمای شخصیت SOUL.md](/fa/concepts/soul) شروع کنید.
|
||||
|
||||
برای بررسی اینکه هر فایل تزریقشده چقدر مشارکت دارد (خام در برابر تزریقشده، truncation، بهعلاوه سربار schema ابزار)، از `/context list` یا `/context detail` استفاده کنید. [زمینه](/fa/concepts/context) را ببینید.
|
||||
برای بررسی اینکه هر فایل تزریقشده چه مقدار سهم دارد (خام در برابر تزریقشده، کوتاهسازی، بهعلاوه سربار schema ابزار)، از `/context list` یا `/context detail` استفاده کنید. [زمینه](/fa/concepts/context) را ببینید.
|
||||
|
||||
## مدیریت زمان
|
||||
|
||||
پرامپت سیستمی وقتی منطقه زمانی کاربر معلوم باشد، یک بخش اختصاصی **تاریخ و زمان فعلی** را شامل میشود.
|
||||
برای پایدار نگهداشتن کش پرامپت، اکنون فقط
|
||||
اعلان سیستمی وقتی منطقه زمانی کاربر شناخته شده باشد، یک بخش اختصاصی **تاریخ و زمان کنونی** دارد. برای پایدار نگهداشتن کش اعلان، اکنون فقط
|
||||
**منطقه زمانی** را شامل میشود (بدون ساعت پویا یا قالب زمان).
|
||||
|
||||
وقتی عامل به زمان فعلی نیاز دارد، از `session_status` استفاده کنید؛ کارت وضعیت
|
||||
یک خط timestamp دارد. همان ابزار میتواند بهصورت اختیاری override مدل برای هر نشست را تنظیم کند
|
||||
(`model=default` آن را پاک میکند).
|
||||
وقتی عامل به زمان کنونی نیاز دارد، از `session_status` استفاده کنید؛ کارت وضعیت
|
||||
یک خط timestamp را شامل میشود. همان ابزار میتواند بهصورت اختیاری یک override مدل مختص نشست
|
||||
تنظیم کند (`model=default` آن را پاک میکند).
|
||||
|
||||
با اینها پیکربندی کنید:
|
||||
|
||||
@ -205,19 +206,19 @@ hookهای داخلی میتوانند این مرحله را از طریق `
|
||||
|
||||
## Skills
|
||||
|
||||
وقتی skillهای واجد شرایط وجود داشته باشند، OpenClaw یک **فهرست skillهای موجود** فشرده را تزریق میکند
|
||||
(`formatSkillsForPrompt`) که **مسیر فایل** هر skill را شامل میشود. این
|
||||
پرامپت به مدل دستور میدهد از `read` برای بارگذاری SKILL.md در مکان فهرستشده
|
||||
(فضای کاری، مدیریتشده، یا bundled) استفاده کند. اگر هیچ skill واجد شرایطی نباشد، بخش
|
||||
Skills حذف میشود.
|
||||
وقتی skillهای واجد شرایط وجود داشته باشند، OpenClaw یک **فهرست skillهای موجود** فشرده
|
||||
(`formatSkillsForPrompt`) تزریق میکند که **مسیر فایل** هر skill را شامل میشود. اعلان
|
||||
به مدل دستور میدهد از `read` برای بارگذاری SKILL.md در مکان فهرستشده
|
||||
(workspace، مدیریتشده، یا bundled) استفاده کند. اگر هیچ skill واجد شرایطی وجود نداشته باشد،
|
||||
بخش Skills حذف میشود.
|
||||
|
||||
واجد شرایط بودن شامل gateهای metadata skill، بررسیهای محیط/پیکربندی runtime،
|
||||
و allowlist موثر skill عامل وقتی `agents.defaults.skills` یا
|
||||
واجد شرایط بودن شامل gateهای metadata مربوط به skill، بررسیهای محیط/پیکربندی runtime،
|
||||
و allowlist مؤثر skill عامل است وقتی `agents.defaults.skills` یا
|
||||
`agents.list[].skills` پیکربندی شده باشد.
|
||||
|
||||
skillهای bundled در Plugin فقط وقتی واجد شرایط هستند که Plugin مالک آنها فعال باشد.
|
||||
این اجازه میدهد Pluginهای ابزار راهنماهای عملیاتی عمیقتری را بدون embed کردن همه
|
||||
آن راهنماییها مستقیما در هر توضیح ابزار، ارائه کنند.
|
||||
skillهای bundled همراه Plugin فقط وقتی واجد شرایط هستند که Plugin مالکشان فعال باشد.
|
||||
این اجازه میدهد Pluginهای ابزار راهنماهای عملیاتی عمیقتر را بدون جاسازی همه
|
||||
آن راهنمایی مستقیماً در هر توضیح ابزار ارائه کنند.
|
||||
|
||||
```
|
||||
<available_skills>
|
||||
@ -229,26 +230,39 @@ skillهای bundled در Plugin فقط وقتی واجد شرایط هستند
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
این کار پرامپت پایه را کوچک نگه میدارد و در عین حال استفاده هدفمند از skill را ممکن میکند.
|
||||
این کار اعلان پایه را کوچک نگه میدارد و همچنان استفاده هدفمند از skill را ممکن میکند.
|
||||
|
||||
بودجه فهرست skillها متعلق به زیرسیستم skills است:
|
||||
بودجه فهرست skillها متعلق به زیرسامانه skillها است:
|
||||
|
||||
- پیشفرض سراسری: `skills.limits.maxSkillsPromptChars`
|
||||
- override برای هر عامل: `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
- override در سطح هر عامل: `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
excerptهای runtime محدود و عمومی از سطح متفاوتی استفاده میکنند:
|
||||
گزیدههای عمومی محدودشده runtime از یک سطح متفاوت استفاده میکنند:
|
||||
|
||||
- `agents.defaults.contextLimits.*`
|
||||
- `agents.list[].contextLimits.*`
|
||||
|
||||
این جداسازی، اندازهگذاری skills را از اندازهگذاری خواندن/تزریق runtime مانند
|
||||
`memory_get`، نتایج ابزار زنده، و تازهسازیهای AGENTS.md پس از Compaction جدا نگه میدارد.
|
||||
این تفکیک، اندازهگذاری Skills را از اندازهگذاری خواندن/تزریق در زمان اجرا جدا نگه میدارد؛
|
||||
مانند `memory_get`، نتایج زندهٔ ابزار، و تازهسازیهای AGENTS.md پس از Compaction.
|
||||
|
||||
## مستندات
|
||||
|
||||
پرامپت سیستم شامل بخش **مستندات** است. وقتی مستندات محلی در دسترس باشند، به پوشهٔ مستندات محلی OpenClaw اشاره میکند (`docs/` در یک checkout از Git یا مستندات بستهٔ npm همراه). اگر مستندات محلی در دسترس نباشند، به [https://docs.openclaw.ai](https://docs.openclaw.ai) برمیگردد.
|
||||
اعلان سیستمی شامل بخشی با عنوان **مستندات** است. وقتی مستندات محلی در دسترس باشند، به
|
||||
دایرکتوری مستندات محلی OpenClaw اشاره میکند (`docs/` در یک checkout گیت یا مستندات بستهٔ
|
||||
npm همراه). اگر مستندات محلی در دسترس نباشند، به
|
||||
[https://docs.openclaw.ai](https://docs.openclaw.ai) بازمیگردد.
|
||||
|
||||
همان بخش همچنین شامل محل منبع OpenClaw است. checkoutهای Git ریشهٔ منبع محلی را در اختیار میگذارند تا عامل بتواند کد را مستقیماً بررسی کند. نصبهای بسته شامل URL منبع GitHub هستند و به عامل میگویند هر زمان مستندات ناقص یا قدیمی باشند، منبع را آنجا بررسی کند. پرامپت همچنین به آینهٔ عمومی مستندات، Discord جامعه، و ClawHub ([https://clawhub.ai](https://clawhub.ai)) برای کشف Skills اشاره میکند. به مدل میگوید برای رفتار، فرمانها، پیکربندی، یا معماری OpenClaw ابتدا به مستندات مراجعه کند، و در صورت امکان خودش `openclaw status` را اجرا کند (فقط وقتی دسترسی ندارد از کاربر بپرسد). بهطور خاص برای پیکربندی، عاملها را برای مستندات دقیق در سطح فیلد و محدودیتها به کنش ابزار `gateway` یعنی `config.schema.lookup`، و سپس برای راهنمایی گستردهتر به `docs/gateway/configuration.md` و `docs/gateway/configuration-reference.md` ارجاع میدهد.
|
||||
همین بخش همچنین محل منبع OpenClaw را هم شامل میشود. checkoutهای گیت، ریشهٔ منبع محلی را
|
||||
در اختیار عامل میگذارند تا بتواند کد را مستقیماً بررسی کند. نصبهای بسته شامل URL منبع
|
||||
GitHub هستند و به عامل میگویند هر زمان مستندات ناقص یا قدیمی بود، منبع را آنجا مرور کند.
|
||||
اعلان همچنین به آینهٔ مستندات عمومی، Discord جامعه، و ClawHub
|
||||
([https://clawhub.ai](https://clawhub.ai)) برای کشف Skills اشاره میکند. این اعلان به مدل
|
||||
میگوید برای رفتار، فرمانها، پیکربندی، یا معماری OpenClaw ابتدا مستندات را بررسی کند و
|
||||
هر زمان ممکن بود خودش `openclaw status` را اجرا کند (تنها زمانی از کاربر بپرسد که دسترسی
|
||||
نداشته باشد). بهطور خاص برای پیکربندی، عاملها را به کنش ابزار `gateway` یعنی
|
||||
`config.schema.lookup` برای مستندات و محدودیتهای دقیق در سطح فیلد هدایت میکند، سپس برای
|
||||
راهنمایی گستردهتر به `docs/gateway/configuration.md` و
|
||||
`docs/gateway/configuration-reference.md` ارجاع میدهد.
|
||||
|
||||
## مرتبط
|
||||
|
||||
|
||||
@ -1,52 +1,53 @@
|
||||
---
|
||||
read_when:
|
||||
- تغییر رونویسی صوتی یا مدیریت رسانه
|
||||
summary: نحوهٔ دانلود صوتها/یادداشتهای صوتی ورودی، تبدیل آنها به متن و درج آنها در پاسخها
|
||||
summary: نحوهٔ دانلود، رونویسی و تزریق صدای ورودی/پیامهای صوتی در پاسخها
|
||||
title: صدا و یادداشتهای صوتی
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T23:07:45Z"
|
||||
generated_at: "2026-05-02T23:39:02Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 35074d79104f767ee252064462202a8ec21ac26f6db25c39e67f31f6b40edeb7
|
||||
source_hash: 91cd6951f80c6137061a7d4e82415b0872bc92c6d6ad136273a2e9ad7ec00ac1
|
||||
source_path: nodes/audio.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# صدا / یادداشتهای صوتی (2026-01-17)
|
||||
# یادداشتهای صوتی / صوت (2026-01-17)
|
||||
|
||||
## آنچه کار میکند
|
||||
|
||||
- **درک رسانه (صدا)**: اگر درک صدا فعال باشد (یا بهصورت خودکار شناسایی شود)، OpenClaw:
|
||||
- **درک رسانه (صوت)**: اگر درک صوت فعال باشد (یا بهصورت خودکار تشخیص داده شود)، OpenClaw:
|
||||
1. نخستین پیوست صوتی (مسیر محلی یا URL) را پیدا میکند و در صورت نیاز آن را دانلود میکند.
|
||||
2. پیش از ارسال به هر ورودی مدل، `maxBytes` را اعمال میکند.
|
||||
3. نخستین ورودی مدل واجد شرایط را بهترتیب اجرا میکند (ارائهدهنده یا CLI).
|
||||
4. اگر شکست بخورد یا رد شود (اندازه/مهلت زمانی)، ورودی بعدی را امتحان میکند.
|
||||
5. در صورت موفقیت، `Body` را با یک بلوک `[Audio]` جایگزین میکند و `{{Transcript}}` را تنظیم میکند.
|
||||
- **تجزیه فرمان**: وقتی رونویسی موفق میشود، `CommandBody`/`RawBody` روی متن رونویسی تنظیم میشوند تا فرمانهای اسلش همچنان کار کنند.
|
||||
- **ثبت گزارش مفصل**: در `--verbose`، هنگام اجرای رونویسی و هنگام جایگزین کردن بدنه، گزارش ثبت میکنیم.
|
||||
- **تجزیه فرمان**: وقتی رونویسی موفق باشد، `CommandBody`/`RawBody` روی متن رونویسی تنظیم میشوند تا فرمانهای اسلش همچنان کار کنند.
|
||||
- **ثبت گزارش تفصیلی**: در `--verbose`، زمانی را که رونویسی اجرا میشود و زمانی را که بدنه را جایگزین میکند ثبت میکنیم.
|
||||
- **دیکته در رابط کنترل**: سازنده پیام Chat میتواند یک کلیپ میکروفون ضبطشده در مرورگر را به `chat.transcribeAudio` بفرستد. آن RPC در Gateway کلیپ را در یک فایل محلی موقت مینویسد، همین خط لوله رونویسی صوتی را اجرا میکند، متن پیشنویس را به مرورگر برمیگرداند و فایل موقت را حذف میکند. این کار بهتنهایی اجرای عامل ایجاد نمیکند.
|
||||
|
||||
## شناسایی خودکار (پیشفرض)
|
||||
## تشخیص خودکار (پیشفرض)
|
||||
|
||||
اگر **مدلها را پیکربندی نکنید** و `tools.media.audio.enabled` روی `false` تنظیم نشده باشد،
|
||||
OpenClaw به این ترتیب شناسایی خودکار انجام میدهد و در نخستین گزینه عملیاتی متوقف میشود:
|
||||
اگر **مدلها را پیکربندی نکنید** و `tools.media.audio.enabled` روی `false` تنظیم **نشده باشد**،
|
||||
OpenClaw به این ترتیب بهصورت خودکار تشخیص میدهد و در نخستین گزینه فعال متوقف میشود:
|
||||
|
||||
1. **مدل پاسخ فعال** وقتی ارائهدهنده آن از درک صدا پشتیبانی میکند.
|
||||
2. **CLIهای محلی** (در صورت نصب بودن)
|
||||
- `sherpa-onnx-offline` (به `SHERPA_ONNX_MODEL_DIR` همراه با encoder/decoder/joiner/tokens نیاز دارد)
|
||||
- `whisper-cli` (از `whisper-cpp`؛ از `WHISPER_CPP_MODEL` یا مدل کوچکِ همراه استفاده میکند)
|
||||
- `whisper` (Python CLI؛ مدلها را بهصورت خودکار دانلود میکند)
|
||||
1. **مدل پاسخ فعال** وقتی ارائهدهنده آن از درک صوت پشتیبانی کند.
|
||||
2. **CLIهای محلی** (اگر نصب شده باشند)
|
||||
- `sherpa-onnx-offline` (به `SHERPA_ONNX_MODEL_DIR` با encoder/decoder/joiner/tokens نیاز دارد)
|
||||
- `whisper-cli` (از `whisper-cpp`؛ از `WHISPER_CPP_MODEL` یا مدل کوچک همراه استفاده میکند)
|
||||
- `whisper` (CLI پایتون؛ مدلها را بهصورت خودکار دانلود میکند)
|
||||
3. **Gemini CLI** (`gemini`) با استفاده از `read_many_files`
|
||||
4. **احراز هویت ارائهدهنده**
|
||||
- ابتدا ورودیهای پیکربندیشده `models.providers.*` که از صدا پشتیبانی میکنند امتحان میشوند
|
||||
- ورودیهای پیکربندیشده `models.providers.*` که از صوت پشتیبانی میکنند ابتدا امتحان میشوند
|
||||
- ترتیب جایگزین همراه: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral
|
||||
|
||||
برای غیرفعال کردن شناسایی خودکار، `tools.media.audio.enabled: false` را تنظیم کنید.
|
||||
برای غیرفعالکردن تشخیص خودکار، `tools.media.audio.enabled: false` را تنظیم کنید.
|
||||
برای سفارشیسازی، `tools.media.audio.models` را تنظیم کنید.
|
||||
نکته: شناسایی باینری در macOS/Linux/Windows بر پایه بهترین تلاش است؛ مطمئن شوید CLI روی `PATH` قرار دارد (ما `~` را گسترش میدهیم)، یا یک مدل CLI صریح با مسیر کامل فرمان تنظیم کنید.
|
||||
نکته: تشخیص باینری در macOS/Linux/Windows بهصورت بهترین تلاش است؛ مطمئن شوید CLI روی `PATH` قرار دارد (ما `~` را گسترش میدهیم)، یا یک مدل CLI صریح با مسیر کامل فرمان تنظیم کنید.
|
||||
|
||||
## نمونههای پیکربندی
|
||||
|
||||
### ارائهدهنده + جایگزین CLI (OpenAI + Whisper CLI)
|
||||
### جایگزین ارائهدهنده + CLI (OpenAI + Whisper CLI)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -134,7 +135,7 @@ OpenClaw به این ترتیب شناسایی خودکار انجام مید
|
||||
}
|
||||
```
|
||||
|
||||
### بازتاب متن رونویسی به چت (اختیاری)
|
||||
### بازتاب متن رونویسی به گفتوگو (اختیاری)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -151,30 +152,30 @@ OpenClaw به این ترتیب شناسایی خودکار انجام مید
|
||||
}
|
||||
```
|
||||
|
||||
## نکتهها و محدودیتها
|
||||
## نکات و محدودیتها
|
||||
|
||||
- احراز هویت ارائهدهنده از ترتیب استاندارد احراز هویت مدل پیروی میکند (پروفایلهای احراز هویت، متغیرهای محیطی، `models.providers.*.apiKey`).
|
||||
- جزئیات راهاندازی Groq: [Groq](/fa/providers/groq).
|
||||
- وقتی `provider: "deepgram"` استفاده شود، Deepgram مقدار `DEEPGRAM_API_KEY` را دریافت میکند.
|
||||
- جزئیات راهاندازی Deepgram: [Deepgram (رونویسی صدا)](/fa/providers/deepgram).
|
||||
- وقتی از `provider: "deepgram"` استفاده شود، Deepgram از `DEEPGRAM_API_KEY` استفاده میکند.
|
||||
- جزئیات راهاندازی Deepgram: [Deepgram (رونویسی صوتی)](/fa/providers/deepgram).
|
||||
- جزئیات راهاندازی Mistral: [Mistral](/fa/providers/mistral).
|
||||
- وقتی `provider: "senseaudio"` استفاده شود، SenseAudio مقدار `SENSEAUDIO_API_KEY` را دریافت میکند.
|
||||
- وقتی از `provider: "senseaudio"` استفاده شود، SenseAudio از `SENSEAUDIO_API_KEY` استفاده میکند.
|
||||
- جزئیات راهاندازی SenseAudio: [SenseAudio](/fa/providers/senseaudio).
|
||||
- ارائهدهندگان صدا میتوانند `baseUrl`، `headers` و `providerOptions` را از طریق `tools.media.audio` بازنویسی کنند.
|
||||
- سقف اندازه پیشفرض 20MB است (`tools.media.audio.maxBytes`). صدای بزرگتر از حد برای آن مدل رد میشود و ورودی بعدی امتحان میشود.
|
||||
- فایلهای صوتی بسیار کوچک/خالی زیر 1024 بایت پیش از رونویسی ارائهدهنده/CLI رد میشوند.
|
||||
- مقدار پیشفرض `maxChars` برای صدا **تنظیم نشده** است (متن کامل رونویسی). برای کوتاه کردن خروجی، `tools.media.audio.maxChars` یا `maxChars` هر ورودی را تنظیم کنید.
|
||||
- ارائهدهندگان صوت میتوانند `baseUrl`، `headers`، و `providerOptions` را از طریق `tools.media.audio` بازنویسی کنند.
|
||||
- سقف اندازه پیشفرض 20MB است (`tools.media.audio.maxBytes`). صوت بزرگتر از حد برای آن مدل رد میشود و ورودی بعدی امتحان میشود.
|
||||
- فایلهای صوتی بسیار کوچک/خالی کمتر از 1024 بایت پیش از رونویسی ارائهدهنده/CLI رد میشوند.
|
||||
- مقدار پیشفرض `maxChars` برای صوت **تنظیم نشده** است (متن رونویسی کامل). برای کوتاهکردن خروجی، `tools.media.audio.maxChars` یا `maxChars` هر ورودی را تنظیم کنید.
|
||||
- پیشفرض خودکار OpenAI برابر `gpt-4o-mini-transcribe` است؛ برای دقت بالاتر `model: "gpt-4o-transcribe"` را تنظیم کنید.
|
||||
- برای پردازش چند یادداشت صوتی از `tools.media.audio.attachments` استفاده کنید (`mode: "all"` + `maxAttachments`).
|
||||
- متن رونویسی برای قالبها بهصورت `{{Transcript}}` در دسترس است.
|
||||
- `tools.media.audio.echoTranscript` بهصورت پیشفرض خاموش است؛ آن را فعال کنید تا پیش از پردازش عامل، تأییدیه رونویسی به چت مبدأ ارسال شود.
|
||||
- `tools.media.audio.echoFormat` متن بازتاب را سفارشی میکند (جاینگهدار: `{transcript}`).
|
||||
- خروجی stdout در CLI محدود است (5MB)؛ خروجی CLI را مختصر نگه دارید.
|
||||
- `args` در CLI باید از `{{MediaPath}}` برای مسیر فایل صوتی محلی استفاده کند. برای مهاجرت جاینگهدارهای منسوخ `{input}` از پیکربندیهای قدیمیتر `audio.transcription.command`، `openclaw doctor --fix` را اجرا کنید.
|
||||
- متن رونویسی با `{{Transcript}}` در قالبها در دسترس است.
|
||||
- `tools.media.audio.echoTranscript` بهصورت پیشفرض خاموش است؛ آن را فعال کنید تا پیش از پردازش عامل، تأیید متن رونویسی به گفتوگوی مبدأ ارسال شود.
|
||||
- `tools.media.audio.echoFormat` متن بازتاب را سفارشی میکند (placeholder: `{transcript}`).
|
||||
- stdout در CLI محدود است (5MB)؛ خروجی CLI را مختصر نگه دارید.
|
||||
- `args` در CLI باید از `{{MediaPath}}` برای مسیر فایل صوتی محلی استفاده کند. برای مهاجرت placeholderهای منسوخ `{input}` از پیکربندیهای قدیمیتر `audio.transcription.command`، `openclaw doctor --fix` را اجرا کنید.
|
||||
|
||||
### پشتیبانی از محیط پراکسی
|
||||
### پشتیبانی از محیط پروکسی
|
||||
|
||||
رونویسی صوتی مبتنی بر ارائهدهنده از متغیرهای محیطی استاندارد پراکسی خروجی پیروی میکند:
|
||||
رونویسی صوتی مبتنی بر ارائهدهنده، متغیرهای محیطی استاندارد پروکسی خروجی را رعایت میکند:
|
||||
|
||||
- `HTTPS_PROXY`
|
||||
- `HTTP_PROXY`
|
||||
@ -183,42 +184,42 @@ OpenClaw به این ترتیب شناسایی خودکار انجام مید
|
||||
- `http_proxy`
|
||||
- `all_proxy`
|
||||
|
||||
اگر هیچ متغیر محیطی پراکسی تنظیم نشده باشد، خروج مستقیم استفاده میشود. اگر پیکربندی پراکسی نادرست باشد، OpenClaw یک هشدار ثبت میکند و به دریافت مستقیم برمیگردد.
|
||||
اگر هیچ متغیر محیطی پروکسی تنظیم نشده باشد، خروج مستقیم استفاده میشود. اگر پیکربندی پروکسی نادرست باشد، OpenClaw یک هشدار ثبت میکند و به دریافت مستقیم برمیگردد.
|
||||
|
||||
## شناسایی منشن در گروهها
|
||||
## تشخیص اشاره در گروهها
|
||||
|
||||
وقتی `requireMention: true` برای یک چت گروهی تنظیم شده باشد، OpenClaw اکنون صدا را **پیش از** بررسی منشنها رونویسی میکند. این باعث میشود یادداشتهای صوتی حتی وقتی شامل منشن هستند پردازش شوند.
|
||||
وقتی `requireMention: true` برای یک گفتوگوی گروهی تنظیم شده باشد، OpenClaw اکنون صوت را **پیش از** بررسی اشارهها رونویسی میکند. این کار اجازه میدهد یادداشتهای صوتی حتی وقتی شامل اشارهها هستند پردازش شوند.
|
||||
|
||||
**نحوه کار:**
|
||||
|
||||
1. اگر یک پیام صوتی بدنه متنی نداشته باشد و گروه به منشن نیاز داشته باشد، OpenClaw یک رونویسی «پیشپرواز» انجام میدهد.
|
||||
2. متن رونویسی برای الگوهای منشن بررسی میشود (برای مثال، `@BotName`، محرکهای ایموجی).
|
||||
3. اگر منشن پیدا شود، پیام از خط لوله کامل پاسخ عبور میکند.
|
||||
4. متن رونویسی برای شناسایی منشن استفاده میشود تا یادداشتهای صوتی بتوانند از گیت منشن عبور کنند.
|
||||
1. اگر یک پیام صوتی بدنه متنی نداشته باشد و گروه به اشارهها نیاز داشته باشد، OpenClaw یک رونویسی "preflight" انجام میدهد.
|
||||
2. متن رونویسی برای الگوهای اشاره بررسی میشود (مثلاً `@BotName`، محرکهای ایموجی).
|
||||
3. اگر اشارهای پیدا شود، پیام از خط لوله کامل پاسخ عبور میکند.
|
||||
4. متن رونویسی برای تشخیص اشاره استفاده میشود تا یادداشتهای صوتی بتوانند از دروازه اشاره عبور کنند.
|
||||
|
||||
**رفتار جایگزین:**
|
||||
|
||||
- اگر رونویسی در طول پیشپرواز شکست بخورد (مهلت زمانی، خطای API و غیره)، پیام بر پایه شناسایی منشن فقطمتنی پردازش میشود.
|
||||
- این تضمین میکند که پیامهای ترکیبی (متن + صدا) هرگز بهاشتباه حذف نشوند.
|
||||
- اگر رونویسی هنگام preflight شکست بخورد (مهلت زمانی، خطای API، و غیره)، پیام بر اساس تشخیص اشاره فقطمتنی پردازش میشود.
|
||||
- این تضمین میکند پیامهای ترکیبی (متن + صوت) هرگز بهاشتباه حذف نشوند.
|
||||
|
||||
**انصراف برای هر گروه/موضوع Telegram:**
|
||||
|
||||
- برای رد کردن بررسیهای منشن در رونویسی پیشپرواز برای آن گروه، `channels.telegram.groups.<chatId>.disableAudioPreflight: true` را تنظیم کنید.
|
||||
- برای بازنویسی در سطح هر موضوع، `channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight` را تنظیم کنید (`true` برای رد کردن، `false` برای اجبار به فعالسازی).
|
||||
- پیشفرض `false` است (وقتی شرایط وابسته به منشن برقرار باشد، پیشپرواز فعال است).
|
||||
- برای ردکردن بررسیهای اشاره متن رونویسی preflight برای آن گروه، `channels.telegram.groups.<chatId>.disableAudioPreflight: true` را تنظیم کنید.
|
||||
- برای بازنویسی در سطح هر موضوع، `channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight` را تنظیم کنید (`true` برای ردکردن، `false` برای فعالسازی اجباری).
|
||||
- پیشفرض `false` است (وقتی شرایط وابسته به اشاره برقرار باشد، preflight فعال است).
|
||||
|
||||
**مثال:** کاربری در یک گروه Telegram با `requireMention: true` یک یادداشت صوتی میفرستد که میگوید «Hey @Claude, what's the weather?». یادداشت صوتی رونویسی میشود، منشن شناسایی میشود و عامل پاسخ میدهد.
|
||||
**مثال:** کاربری در یک گروه Telegram با `requireMention: true` یک یادداشت صوتی میفرستد که میگوید "Hey @Claude, what's the weather?". یادداشت صوتی رونویسی میشود، اشاره تشخیص داده میشود و عامل پاسخ میدهد.
|
||||
|
||||
## نکات مهم
|
||||
## نکات احتیاطی
|
||||
|
||||
- قوانین دامنه از اصل اولین تطابق برنده است استفاده میکنند. `chatType` به `direct`، `group` یا `room` نرمالسازی میشود.
|
||||
- قوانین دامنه از نخستین تطابق پیروی میکنند. `chatType` به `direct`، `group`، یا `room` نرمالسازی میشود.
|
||||
- مطمئن شوید CLI شما با کد 0 خارج میشود و متن ساده چاپ میکند؛ JSON باید از طریق `jq -r .text` پردازش شود.
|
||||
- برای `parakeet-mlx`، اگر `--output-dir` را ارسال کنید، وقتی `--output-format` برابر `txt` باشد (یا حذف شده باشد)، OpenClaw فایل `<output-dir>/<media-basename>.txt` را میخواند؛ قالبهای خروجی غیر از `txt` به تجزیه stdout برمیگردند.
|
||||
- برای جلوگیری از مسدود شدن صف پاسخ، مهلتهای زمانی را منطقی نگه دارید (`timeoutSeconds`، پیشفرض 60s).
|
||||
- رونویسی پیشپرواز فقط **نخستین** پیوست صوتی را برای شناسایی منشن پردازش میکند. صدای اضافی در مرحله اصلی درک رسانه پردازش میشود.
|
||||
- برای `parakeet-mlx`، اگر `--output-dir` را پاس دهید، وقتی `--output-format` برابر `txt` باشد (یا حذف شده باشد)، OpenClaw فایل `<output-dir>/<media-basename>.txt` را میخواند؛ قالبهای خروجی غیر از `txt` به تجزیه stdout برمیگردند.
|
||||
- برای جلوگیری از مسدودشدن صف پاسخ، مهلتهای زمانی را منطقی نگه دارید (`timeoutSeconds`، پیشفرض 60s).
|
||||
- رونویسی preflight فقط **نخستین** پیوست صوتی را برای تشخیص اشاره پردازش میکند. صوتهای اضافی در مرحله اصلی درک رسانه پردازش میشوند.
|
||||
|
||||
## مرتبط
|
||||
|
||||
- [درک رسانه](/fa/nodes/media-understanding)
|
||||
- [حالت گفتوگو](/fa/nodes/talk)
|
||||
- [بیدارباش صوتی](/fa/nodes/voicewake)
|
||||
- [بیدارسازی صوتی](/fa/nodes/voicewake)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -5,17 +5,17 @@ read_when:
|
||||
summary: راهاندازی Arcee AI (احراز هویت + انتخاب مدل)
|
||||
title: Arcee AI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T23:22:53Z"
|
||||
generated_at: "2026-05-02T23:39:07Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 54989e1706901fedc8a0c816ca7ee7f877fa4b973697540dd90cb9182420043f
|
||||
source_hash: 622ee5288aec3ae0b45d3f06ba65fd6f972e07d7a7596ae3905d6fbdac0bf737
|
||||
source_path: providers/arcee.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
[Arcee AI](https://arcee.ai) دسترسی به خانواده Trinity از مدلهای mixture-of-experts را از طریق یک API سازگار با OpenAI فراهم میکند. همه مدلهای Trinity تحت مجوز Apache 2.0 منتشر شدهاند.
|
||||
|
||||
مدلهای Arcee AI را میتوان مستقیما از طریق پلتفرم Arcee یا از طریق [OpenRouter](/fa/providers/openrouter) در دسترس داشت.
|
||||
مدلهای Arcee AI را میتوان مستقیماً از طریق پلتفرم Arcee یا از طریق [OpenRouter](/fa/providers/openrouter) استفاده کرد.
|
||||
|
||||
| ویژگی | مقدار |
|
||||
| -------- | ------------------------------------------------------------------------------------- |
|
||||
@ -27,17 +27,17 @@ x-i18n:
|
||||
## شروع به کار
|
||||
|
||||
<Tabs>
|
||||
<Tab title="مستقیم (پلتفرم Arcee)">
|
||||
<Tab title="Direct (Arcee platform)">
|
||||
<Steps>
|
||||
<Step title="دریافت کلید API">
|
||||
<Step title="Get an API key">
|
||||
در [Arcee AI](https://chat.arcee.ai/) یک کلید API بسازید.
|
||||
</Step>
|
||||
<Step title="اجرای راهاندازی اولیه">
|
||||
<Step title="Run onboarding">
|
||||
```bash
|
||||
openclaw onboard --auth-choice arceeai-api-key
|
||||
```
|
||||
</Step>
|
||||
<Step title="تنظیم مدل پیشفرض">
|
||||
<Step title="Set a default model">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -51,17 +51,17 @@ x-i18n:
|
||||
</Steps>
|
||||
</Tab>
|
||||
|
||||
<Tab title="از طریق OpenRouter">
|
||||
<Tab title="Via OpenRouter">
|
||||
<Steps>
|
||||
<Step title="دریافت کلید API">
|
||||
<Step title="Get an API key">
|
||||
در [OpenRouter](https://openrouter.ai/keys) یک کلید API بسازید.
|
||||
</Step>
|
||||
<Step title="اجرای راهاندازی اولیه">
|
||||
<Step title="Run onboarding">
|
||||
```bash
|
||||
openclaw onboard --auth-choice arceeai-openrouter
|
||||
```
|
||||
</Step>
|
||||
<Step title="تنظیم مدل پیشفرض">
|
||||
<Step title="Set a default model">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -72,7 +72,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
همان ارجاعهای مدل برای هر دو پیکربندی مستقیم و OpenRouter کار میکنند (برای مثال `arcee/trinity-large-thinking`).
|
||||
همان ارجاعهای مدل برای هر دو راهاندازی مستقیم و OpenRouter کار میکنند (برای مثال `arcee/trinity-large-thinking`).
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -82,7 +82,7 @@ x-i18n:
|
||||
## راهاندازی غیرتعاملی
|
||||
|
||||
<Tabs>
|
||||
<Tab title="مستقیم (پلتفرم Arcee)">
|
||||
<Tab title="Direct (Arcee platform)">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
@ -91,7 +91,7 @@ x-i18n:
|
||||
```
|
||||
</Tab>
|
||||
|
||||
<Tab title="از طریق OpenRouter">
|
||||
<Tab title="Via OpenRouter">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
@ -105,35 +105,35 @@ x-i18n:
|
||||
|
||||
OpenClaw در حال حاضر این کاتالوگ Arcee همراه را ارائه میکند:
|
||||
|
||||
| ارجاع مدل | نام | ورودی | زمینه | هزینه (ورودی/خروجی بهازای هر ۱ میلیون) | یادداشتها |
|
||||
| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ----------------------------------------- |
|
||||
| `arcee/trinity-large-thinking` | Trinity Large Thinking | text | 256K | $0.25 / $0.90 | مدل پیشفرض؛ استدلال فعال است |
|
||||
| `arcee/trinity-large-preview` | Trinity Large Preview | text | 128K | $0.25 / $1.00 | همهمنظوره؛ 400B پارامتر، 13B فعال |
|
||||
| `arcee/trinity-mini` | Trinity Mini 26B | text | 128K | $0.045 / $0.15 | سریع و مقرونبهصرفه؛ فراخوانی تابع |
|
||||
| ارجاع مدل | نام | ورودی | زمینه | هزینه (ورودی/خروجی به ازای هر ۱ میلیون) | یادداشتها |
|
||||
| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ------------------------------------------ |
|
||||
| `arcee/trinity-large-thinking` | Trinity Large Thinking | متن | 256K | $0.25 / $0.90 | مدل پیشفرض؛ استدلال فعال؛ بدون ابزار |
|
||||
| `arcee/trinity-large-preview` | Trinity Large Preview | متن | 128K | $0.25 / $1.00 | همهمنظوره؛ 400B پارامتر، 13B فعال |
|
||||
| `arcee/trinity-mini` | Trinity Mini 26B | متن | 128K | $0.045 / $0.15 | سریع و مقرونبهصرفه؛ فراخوانی تابع |
|
||||
|
||||
<Tip>
|
||||
پیشتنظیم راهاندازی اولیه، `arcee/trinity-large-thinking` را بهعنوان مدل پیشفرض تنظیم میکند.
|
||||
پیشتنظیم onboarding، `arcee/trinity-large-thinking` را به عنوان مدل پیشفرض تنظیم میکند. این مدل فقط متنی/استدلالی است و از استفاده از ابزار یا فراخوانی تابع پشتیبانی نمیکند.
|
||||
</Tip>
|
||||
|
||||
## قابلیتهای پشتیبانیشده
|
||||
|
||||
| قابلیت | پشتیبانی |
|
||||
| --------------------------------------------- | ---------------------------- |
|
||||
| جریاندهی | بله |
|
||||
| استفاده از ابزار / فراخوانی تابع | بله |
|
||||
| خروجی ساختاریافته (حالت JSON و طرحواره JSON) | بله |
|
||||
| تفکر توسعهیافته | بله (Trinity Large Thinking) |
|
||||
| قابلیت | پشتیبانی |
|
||||
| --------------------------------------------- | ------------------------------------------- |
|
||||
| استریمینگ | بله |
|
||||
| استفاده از ابزار / فراخوانی تابع | وابسته به مدل؛ نه Trinity Large Thinking |
|
||||
| خروجی ساختیافته (حالت JSON و طرحواره JSON) | بله |
|
||||
| تفکر توسعهیافته | بله (Trinity Large Thinking) |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="یادداشت محیط">
|
||||
<Accordion title="Environment note">
|
||||
اگر Gateway بهصورت daemon (launchd/systemd) اجرا میشود، مطمئن شوید `ARCEEAI_API_KEY`
|
||||
(یا `OPENROUTER_API_KEY`) برای آن فرایند در دسترس است (برای مثال، در
|
||||
(یا `OPENROUTER_API_KEY`) در دسترس آن فرایند است (برای مثال، در
|
||||
`~/.openclaw/.env` یا از طریق `env.shellEnv`).
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="مسیریابی OpenRouter">
|
||||
<Accordion title="OpenRouter routing">
|
||||
هنگام استفاده از مدلهای Arcee از طریق OpenRouter، همان ارجاعهای مدل `arcee/*` اعمال میشوند.
|
||||
OpenClaw مسیریابی را بر اساس انتخاب احراز هویت شما بهصورت شفاف مدیریت میکند. برای جزئیات پیکربندی اختصاصی OpenRouter، به
|
||||
OpenClaw مسیریابی را بر اساس انتخاب احراز هویت شما بهصورت شفاف مدیریت میکند. برای جزئیات پیکربندی ویژه OpenRouter، به
|
||||
[مستندات ارائهدهنده OpenRouter](/fa/providers/openrouter) مراجعه کنید.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -144,7 +144,7 @@ OpenClaw در حال حاضر این کاتالوگ Arcee همراه را ارا
|
||||
<Card title="OpenRouter" href="/fa/providers/openrouter" icon="shuffle">
|
||||
به مدلهای Arcee و بسیاری مدلهای دیگر از طریق یک کلید API واحد دسترسی پیدا کنید.
|
||||
</Card>
|
||||
<Card title="انتخاب مدل" href="/fa/concepts/model-providers" icon="layers">
|
||||
<Card title="Model selection" href="/fa/concepts/model-providers" icon="layers">
|
||||
انتخاب ارائهدهندگان، ارجاعهای مدل، و رفتار failover.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,182 +1,173 @@
|
||||
---
|
||||
read_when:
|
||||
- در حال جستوجوی تعریفهای کانالهای انتشار عمومی
|
||||
- در حال جستوجوی تعاریف کانالهای انتشار عمومی
|
||||
- اجرای اعتبارسنجی انتشار یا پذیرش بسته
|
||||
- در جستوجوی نامگذاری نسخهها و تناوب انتشار
|
||||
summary: مسیرهای انتشار، چکلیست اپراتور، جعبههای اعتبارسنجی، نامگذاری نسخه، و تناوب
|
||||
- بهدنبال نامگذاری نسخه و آهنگ انتشار
|
||||
summary: مسیرهای انتشار، چکلیست اپراتور، باکسهای اعتبارسنجی، نامگذاری نسخه، و تناوب
|
||||
title: سیاست انتشار
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:59:23Z"
|
||||
generated_at: "2026-05-02T23:39:13Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 493cb8b42f0e15f3bf5f8fb9be7d01fd626f4f16db9ac0a85e6efa747ef12d12
|
||||
source_hash: ba316d1736eae8edd2fb0a71b9a3da345f8895c3b536e9a1f619718ea12fc851
|
||||
source_path: reference/RELEASING.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw چهار مسیر انتشار عمومی دارد:
|
||||
OpenClaw سه مسیر انتشار عمومی دارد:
|
||||
|
||||
- stable: انتشارهای برچسبخورده که بهطور پیشفرض در npm با `beta` منتشر میشوند، یا وقتی صراحتاً درخواست شود در npm با `latest`
|
||||
- alpha: برچسبهای پیشانتشار که در npm با `alpha` منتشر میشوند
|
||||
- beta: برچسبهای پیشانتشار که در npm با `beta` منتشر میشوند
|
||||
- stable: نسخههای برچسبخوردهای که بهصورت پیشفرض در npm `beta` منتشر میشوند، یا وقتی صراحتا درخواست شود در npm `latest`
|
||||
- beta: برچسبهای پیشانتشار که در npm `beta` منتشر میشوند
|
||||
- dev: سر متحرک `main`
|
||||
|
||||
## نامگذاری نسخه
|
||||
|
||||
- نسخه انتشار پایدار: `YYYY.M.D`
|
||||
- برچسب Git: `vYYYY.M.D`
|
||||
- نسخه انتشار اصلاحی پایدار: `YYYY.M.D-N`
|
||||
- نسخه اصلاحی انتشار پایدار: `YYYY.M.D-N`
|
||||
- برچسب Git: `vYYYY.M.D-N`
|
||||
- نسخه پیشانتشار Alpha: `YYYY.M.D-alpha.N`
|
||||
- برچسب Git: `vYYYY.M.D-alpha.N`
|
||||
- نسخه پیشانتشار Beta: `YYYY.M.D-beta.N`
|
||||
- برچسب Git: `vYYYY.M.D-beta.N`
|
||||
- ماه یا روز را با صفر پر نکنید
|
||||
- `latest` یعنی انتشار پایدار npm که در حال حاضر ترویج شده است
|
||||
- `alpha` یعنی هدف نصب alpha فعلی
|
||||
- `beta` یعنی هدف نصب beta فعلی
|
||||
- انتشارهای پایدار و اصلاحی پایدار بهطور پیشفرض در npm با `beta` منتشر میشوند؛ اپراتورهای انتشار میتوانند صراحتاً `latest` را هدف بگیرند، یا بعداً یک ساخت beta بررسیشده را ترویج کنند
|
||||
- ماه یا روز را با صفر ابتدایی ننویسید
|
||||
- `latest` یعنی انتشار پایدار فعلی npm که ترویج شده است
|
||||
- `beta` یعنی هدف نصب فعلی beta
|
||||
- انتشارهای پایدار و اصلاحی پایدار بهصورت پیشفرض در npm `beta` منتشر میشوند؛ اپراتورهای انتشار میتوانند صراحتا `latest` را هدف بگیرند، یا بعدا یک ساخت beta بررسیشده را ترویج کنند
|
||||
- هر انتشار پایدار OpenClaw بسته npm و برنامه macOS را با هم ارائه میکند؛
|
||||
انتشارهای beta معمولاً ابتدا مسیر npm/package را اعتبارسنجی و منتشر میکنند و
|
||||
ساخت/امضا/محضرسازی برنامه mac برای stable نگه داشته میشود مگر اینکه صراحتاً درخواست شود
|
||||
انتشارهای beta معمولا ابتدا مسیر npm/بسته را اعتبارسنجی و منتشر میکنند، و
|
||||
ساخت/امضا/محضرسازی برنامه mac برای stable نگه داشته میشود مگر اینکه صراحتا درخواست شود
|
||||
|
||||
## آهنگ انتشار
|
||||
|
||||
- انتشارها ابتدا از beta عبور میکنند
|
||||
- stable فقط پس از اعتبارسنجی آخرین beta دنبال میشود
|
||||
- نگهدارندگان معمولاً انتشارها را از شاخه `release/YYYY.M.D` که
|
||||
از `main` فعلی ساخته شده است برش میزنند، تا اعتبارسنجی و اصلاحات انتشار جلوی
|
||||
توسعه جدید روی `main` را نگیرد
|
||||
- اگر یک برچسب beta پوش یا منتشر شده باشد و به اصلاح نیاز داشته باشد، نگهدارندگان
|
||||
بهجای حذف یا بازآفرینی برچسب beta قدیمی، برچسب بعدی `-beta.N` را برش میزنند
|
||||
- روند تفصیلی انتشار، تأییدها، اعتبارنامهها و یادداشتهای بازیابی
|
||||
- نگهدارندگان معمولا انتشارها را از شاخه `release/YYYY.M.D` ایجاد میکنند که
|
||||
از `main` فعلی ساخته شده است، تا اعتبارسنجی و اصلاحات انتشار توسعه جدید
|
||||
روی `main` را مسدود نکند
|
||||
- اگر یک برچسب beta ارسال یا منتشر شده باشد و به اصلاح نیاز داشته باشد، نگهدارندگان
|
||||
بهجای حذف یا بازآفرینی برچسب قدیمی beta، برچسب بعدی `-beta.N` را ایجاد میکنند
|
||||
- رویه دقیق انتشار، تأییدها، اعتبارنامهها، و یادداشتهای بازیابی
|
||||
فقط مخصوص نگهدارندگان است
|
||||
|
||||
## چکلیست اپراتور انتشار
|
||||
|
||||
این چکلیست شکل عمومی جریان انتشار است. اعتبارنامههای خصوصی،
|
||||
امضا، محضرسازی، بازیابی dist-tag و جزئیات بازگشت اضطراری در
|
||||
دفترچه اجرای انتشار مخصوص نگهدارندگان باقی میماند.
|
||||
امضا، محضرسازی، بازیابی dist-tag، و جزئیات بازگشت اضطراری در
|
||||
راهنمای اجرای انتشار مخصوص نگهداران باقی میماند.
|
||||
|
||||
1. از `main` فعلی شروع کنید: آخرین نسخه را pull کنید، تأیید کنید commit هدف پوش شده است،
|
||||
و تأیید کنید CI فعلی `main` بهاندازه کافی سبز است تا بتوان از آن شاخه ساخت.
|
||||
1. از `main` فعلی شروع کنید: آخرین نسخه را pull کنید، تأیید کنید commit هدف push شده است،
|
||||
و تأیید کنید CI فعلی `main` بهاندازه کافی سبز است که بتوان از آن شاخه ساخت.
|
||||
2. بخش بالایی `CHANGELOG.md` را از تاریخچه واقعی commit با
|
||||
`/changelog` بازنویسی کنید، ورودیها را کاربرمحور نگه دارید، آن را commit و push کنید، و
|
||||
پیش از شاخهسازی یکبار دیگر rebase/pull کنید.
|
||||
3. رکوردهای سازگاری انتشار را در
|
||||
یک بار دیگر پیش از شاخهسازی rebase/pull کنید.
|
||||
3. سوابق سازگاری انتشار را در
|
||||
`src/plugins/compat/registry.ts` و
|
||||
`src/commands/doctor/shared/deprecation-compat.ts` بازبینی کنید. سازگاری منقضیشده را
|
||||
فقط زمانی حذف کنید که مسیر ارتقا همچنان پوشش داده شده باشد، یا ثبت کنید چرا
|
||||
عمداً نگه داشته شده است.
|
||||
4. `release/YYYY.M.D` را از `main` فعلی بسازید؛ کار انتشار عادی را
|
||||
مستقیماً روی `main` انجام ندهید.
|
||||
5. هر محل نسخه لازم را برای برچسب موردنظر افزایش دهید، `pnpm plugins:sync` را اجرا کنید تا بستههای Plugin قابل انتشار نسخه انتشار و فراداده سازگاری مشترک داشته باشند، سپس پیشبررسی قطعی محلی را اجرا کنید:
|
||||
`src/commands/doctor/shared/deprecation-compat.ts` بازبینی کنید. سازگاریهای منقضیشده را
|
||||
فقط وقتی حذف کنید که مسیر ارتقا همچنان پوشش داشته باشد، یا ثبت کنید چرا
|
||||
عمدا حفظ شدهاند.
|
||||
4. `release/YYYY.M.D` را از `main` فعلی بسازید؛ کار معمول انتشار را
|
||||
مستقیما روی `main` انجام ندهید.
|
||||
5. همه محلهای نسخه لازم را برای برچسب مورد نظر افزایش دهید، `pnpm plugins:sync` را اجرا کنید
|
||||
تا بستههای Plugin قابل انتشار نسخه انتشار
|
||||
و فراداده سازگاری مشترک داشته باشند، سپس پیشپرواز قطعی محلی را اجرا کنید:
|
||||
`pnpm check:test-types`، `pnpm check:architecture`،
|
||||
`pnpm build && pnpm ui:build`، `pnpm plugins:sync:check` و
|
||||
`pnpm build && pnpm ui:build`، `pnpm plugins:sync:check`، و
|
||||
`pnpm release:check`.
|
||||
6. `OpenClaw NPM Release` را با `preflight_only=true` اجرا کنید. پیش از وجود برچسب،
|
||||
یک SHA کامل ۴۰ کاراکتری شاخه انتشار برای پیشبررسی فقط-اعتبارسنجی مجاز است.
|
||||
`preflight_run_id` موفق را ذخیره کنید.
|
||||
7. همه آزمونهای پیشانتشار را با `Full Release Validation` برای
|
||||
یک SHA کامل ۴۰ کاراکتری شاخه انتشار برای پیشپرواز فقط اعتبارسنجی
|
||||
مجاز است. `preflight_run_id` موفق را ذخیره کنید.
|
||||
7. همه آزمونهای پیش از انتشار را با `Full Release Validation` برای
|
||||
شاخه انتشار، برچسب، یا SHA کامل commit آغاز کنید. این تنها نقطه ورود دستی
|
||||
برای چهار جعبه آزمون بزرگ انتشار است: Vitest، Docker، QA Lab و Package.
|
||||
8. اگر اعتبارسنجی شکست خورد، روی شاخه انتشار اصلاح کنید و کوچکترین
|
||||
فایل، مسیر، کار workflow، پروفایل package، ارائهدهنده، یا فهرست مجاز مدل شکستخورده را دوباره اجرا کنید که
|
||||
اصلاح را اثبات میکند. چتر کامل را فقط وقتی دوباره اجرا کنید که سطح تغییرکرده
|
||||
برای چهار جعبه آزمون بزرگ انتشار است: Vitest، Docker، QA Lab، و Package.
|
||||
8. اگر اعتبارسنجی شکست خورد، روی شاخه انتشار اصلاح کنید و کوچکترین فایل،
|
||||
مسیر، job گردشکار، پروفایل بسته، provider، یا allowlist مدل شکستخوردهای را دوباره اجرا کنید که
|
||||
اصلاح را اثبات میکند. چتر کامل را فقط وقتی دوباره اجرا کنید که سطح تغییر کرده
|
||||
شواهد قبلی را کهنه کند.
|
||||
9. برای alpha یا beta، `vYYYY.M.D-alpha.N` یا `vYYYY.M.D-beta.N` را برچسب بزنید، سپس `OpenClaw Release Publish` را از
|
||||
شاخه مطابق `release/YYYY.M.D` اجرا کنید. این کار `pnpm plugins:sync:check` را تأیید میکند،
|
||||
ابتدا همه بستههای Plugin قابل انتشار را در npm منتشر میکند، همان
|
||||
مجموعه را در مرحله دوم در ClawHub منتشر میکند، و سپس artifact پیشبررسی npm آمادهشده OpenClaw را با dist-tag مطابق ترویج میکند. پس از انتشار، پذیرش package پس از انتشار را
|
||||
در برابر بسته منتشرشده `openclaw@YYYY.M.D-alpha.N`، `openclaw@alpha`،
|
||||
`openclaw@YYYY.M.D-beta.N`، یا `openclaw@beta` اجرا کنید. اگر یک پیشانتشار پوششده یا
|
||||
منتشرشده به اصلاح نیاز داشت، شماره پیشانتشار مطابق بعدی را برش بزنید؛
|
||||
پیشانتشار قدیمی را حذف یا بازنویسی نکنید.
|
||||
9. برای beta، `vYYYY.M.D-beta.N` را برچسب بزنید، سپس `OpenClaw Release Publish` را از
|
||||
شاخه متناظر `release/YYYY.M.D` اجرا کنید. این فرمان `pnpm plugins:sync:check` را راستیآزمایی میکند،
|
||||
ابتدا همه بستههای Plugin قابل انتشار را در npm منتشر میکند، مجموعه مشابه را
|
||||
در مرحله دوم در ClawHub منتشر میکند، و سپس آرتیفکت پیشپرواز آمادهشده OpenClaw در npm را
|
||||
با dist-tag متناظر ترویج میدهد. پس از انتشار، پذیرش بسته پس از انتشار را
|
||||
در برابر بسته منتشرشده `openclaw@YYYY.M.D-beta.N` یا
|
||||
`openclaw@beta` اجرا کنید. اگر یک پیشانتشار push یا منتشرشده به اصلاح نیاز داشت،
|
||||
شماره پیشانتشار متناظر بعدی را ایجاد کنید؛ پیشانتشار قدیمی را حذف یا بازنویسی نکنید.
|
||||
10. برای stable، فقط پس از آن ادامه دهید که beta بررسیشده یا نامزد انتشار
|
||||
شواهد اعتبارسنجی لازم را داشته باشد. انتشار npm پایدار نیز از طریق
|
||||
`OpenClaw Release Publish` انجام میشود و artifact پیشبررسی موفق را از طریق
|
||||
`preflight_run_id` دوباره استفاده میکند؛ آمادگی انتشار macOS پایدار همچنین به
|
||||
شواهد اعتبارسنجی لازم را داشته باشد. انتشار stable در npm نیز از طریق
|
||||
`OpenClaw Release Publish` انجام میشود و از آرتیفکت پیشپرواز موفق با
|
||||
`preflight_run_id` دوباره استفاده میکند؛ آمادگی انتشار stable macOS همچنین به
|
||||
`.zip`، `.dmg`، `.dSYM.zip` بستهبندیشده، و `appcast.xml` بهروزشده روی `main` نیاز دارد.
|
||||
11. پس از انتشار، تأییدکننده پس از انتشار npm، E2E مستقل اختیاری Telegram منتشرشده در npm را هنگامی که به اثبات کانال پس از انتشار نیاز دارید،
|
||||
ترویج dist-tag هنگام نیاز، یادداشتهای انتشار/پیشانتشار GitHub از
|
||||
بخش کامل و مطابق `CHANGELOG.md`، و گامهای اعلان انتشار را اجرا کنید.
|
||||
11. پس از انتشار، راستیآزمای پس از انتشار npm، E2E اختیاری Telegram برای npm منتشرشده مستقل
|
||||
وقتی به اثبات کانال پس از انتشار نیاز دارید،
|
||||
ترویج dist-tag در صورت نیاز، یادداشتهای انتشار/پیشانتشار GitHub از
|
||||
بخش کامل و متناظر `CHANGELOG.md`، و مراحل اعلام انتشار
|
||||
را اجرا کنید.
|
||||
|
||||
## پیشبررسی انتشار
|
||||
## پیشپرواز انتشار
|
||||
|
||||
- پیش از preflight انتشار، `pnpm check:test-types` را اجرا کنید تا TypeScript تستها بیرون از gate سریعتر محلی `pnpm check` نیز پوشش داده شود
|
||||
- پیش از preflight انتشار، `pnpm check:architecture` را اجرا کنید تا بررسیهای گستردهتر چرخه import و مرزهای معماری بیرون از gate سریعتر محلی سبز باشند
|
||||
- پیش از `pnpm release:check`، دستور `pnpm build && pnpm ui:build` را اجرا کنید تا artifactهای انتشار مورد انتظار `dist/*` و bundle رابط کاربری Control برای مرحله اعتبارسنجی pack وجود داشته باشند
|
||||
- پس از افزایش نسخه root و پیش از tag زدن، `pnpm plugins:sync` را اجرا کنید. این دستور نسخههای packageهای Plugin قابل انتشار، metadata سازگاری peer/API مربوط به OpenClaw، metadata ساخت، و stubهای changelog Plugin را بهروزرسانی میکند تا با نسخه انتشار core همخوان شوند. `pnpm plugins:sync:check` نگهبان انتشار غیرتغییردهنده است؛ اگر این مرحله فراموش شده باشد، workflow انتشار پیش از هرگونه تغییر در registry شکست میخورد.
|
||||
- پیش از تایید انتشار، workflow دستی `Full Release Validation` را اجرا کنید تا همه جعبههای تست پیشانتشار از یک entrypoint آغاز شوند. این workflow یک branch، tag، یا SHA کامل commit را میپذیرد، `CI` دستی را dispatch میکند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعههای مسیر انتشار Docker، live/E2E، OpenWebUI، برابری QA Lab، Matrix، و laneهای Telegram dispatch میکند. با `release_profile=full` و `rerun_group=all`، همچنین Telegram E2E مربوط به package را در برابر artifact `release-package-under-test` از release checks اجرا میکند. پس از انتشار، وقتی همان Telegram E2E باید package منتشرشده npm را نیز اثبات کند، `npm_telegram_package_spec` را ارائه کنید. پس از انتشار، وقتی Package Acceptance باید ماتریس package/update خود را بهجای artifact ساختهشده از SHA در برابر package ارسالشده npm اجرا کند، `package_acceptance_package_spec` را ارائه کنید. وقتی گزارش خصوصی evidence باید بدون اجبار Telegram E2E ثابت کند که اعتبارسنجی با یک package منتشرشده npm مطابقت دارد، `evidence_package_spec` را ارائه کنید. مثال:
|
||||
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
|
||||
- وقتی میخواهید همزمان با ادامه کار انتشار، proof جانبی برای یک candidate package داشته باشید، workflow دستی `Package Acceptance` را اجرا کنید. برای `openclaw@alpha`، `openclaw@beta`، `openclaw@latest`، یا یک نسخه انتشار دقیق از `source=npm` استفاده کنید؛ برای pack کردن یک branch/tag/SHA قابل اعتماد `package_ref` با harness فعلی `workflow_ref` از `source=ref` استفاده کنید؛ برای tarball HTTPS با SHA-256 الزامی از `source=url` استفاده کنید؛ یا برای tarball آپلودشده توسط یک اجرای دیگر GitHub Actions از `source=artifact` استفاده کنید. این workflow candidate را به `package-under-test` resolve میکند، scheduler انتشار Docker E2E را در برابر همان tarball دوباره استفاده میکند، و میتواند QA مربوط به Telegram را با `telegram_mode=mock-openai` یا `telegram_mode=live-frontier` در برابر همان tarball اجرا کند. وقتی laneهای انتخابشده Docker شامل `published-upgrade-survivor` باشند، artifact package همان candidate است و `published_upgrade_survivor_baseline` baseline منتشرشده را انتخاب میکند.
|
||||
- اجرای `pnpm check:test-types` پیش از پیشبررسی انتشار تا TypeScript آزمونها بیرون از دروازه سریعتر محلی `pnpm check` پوشش داده بماند
|
||||
- اجرای `pnpm check:architecture` پیش از پیشبررسی انتشار تا بررسیهای گستردهتر چرخه import و مرزهای معماری بیرون از دروازه سریعتر محلی سبز باشند
|
||||
- اجرای `pnpm build && pnpm ui:build` پیش از `pnpm release:check` تا آرتیفکتهای انتشار مورد انتظار `dist/*` و بسته Control UI برای مرحله اعتبارسنجی pack وجود داشته باشند
|
||||
- اجرای `pnpm plugins:sync` پس از افزایش نسخه ریشه و پیش از tag کردن. این دستور نسخههای بستههای Plugin قابل انتشار، فراداده سازگاری peer/API OpenClaw، فراداده build و stubهای changelog Plugin را بهروزرسانی میکند تا با نسخه انتشار core هماهنگ شوند. `pnpm plugins:sync:check` نگهبان غیرتغییردهنده انتشار است؛ اگر این مرحله فراموش شده باشد، workflow انتشار پیش از هر تغییر در registry شکست میخورد.
|
||||
- اجرای workflow دستی `Full Release Validation` پیش از تأیید انتشار برای آغاز همه test boxهای پیش از انتشار از یک entrypoint. این workflow یک branch، tag یا commit SHA کامل میپذیرد، `CI` دستی را dispatch میکند، و `OpenClaw Release Checks` را برای install smoke، package acceptance، مجموعههای مسیر انتشار Docker، live/E2E، OpenWebUI، همارزی QA Lab، Matrix و laneهای Telegram dispatch میکند. با `release_profile=full` و `rerun_group=all`، همچنین Telegram E2E بسته را در برابر آرتیفکت `release-package-under-test` از release checks اجرا میکند. پس از انتشار، وقتی همان Telegram E2E باید بسته npm منتشرشده را هم اثبات کند، `npm_telegram_package_spec` را ارائه کنید. پس از انتشار، وقتی Package Acceptance باید ماتریس package/update خود را در برابر بسته npm ارسالشده اجرا کند، نه آرتیفکت ساختهشده از SHA، `package_acceptance_package_spec` را ارائه کنید. وقتی گزارش evidence خصوصی باید اثبات کند که اعتبارسنجی با یک بسته npm منتشرشده مطابق است بدون اینکه Telegram E2E را اجباری کند، `evidence_package_spec` را ارائه کنید. مثال: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
|
||||
- اجرای workflow دستی `Package Acceptance` وقتی برای نامزد بسته، همزمان با ادامه کار انتشار، proof جانبی میخواهید. از `source=npm` برای `openclaw@beta`، `openclaw@latest` یا نسخه دقیق انتشار استفاده کنید؛ از `source=ref` برای pack کردن branch/tag/SHA مورد اعتماد `package_ref` با harness فعلی `workflow_ref`؛ از `source=url` برای tarball HTTPS با SHA-256 الزامی؛ یا از `source=artifact` برای tarball بارگذاریشده توسط یک اجرای دیگر GitHub Actions. این workflow نامزد را به `package-under-test` resolve میکند، release scheduler مربوط به Docker E2E را در برابر همان tarball دوباره استفاده میکند، و میتواند Telegram QA را با `telegram_mode=mock-openai` یا `telegram_mode=live-frontier` در برابر همان tarball اجرا کند. وقتی laneهای Docker انتخابشده شامل `published-upgrade-survivor` باشند، آرتیفکت بسته همان نامزد است و `published_upgrade_survivor_baseline` baseline منتشرشده را انتخاب میکند.
|
||||
مثال: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
|
||||
profileهای رایج:
|
||||
- `smoke`: laneهای install/channel/agent، شبکه Gateway، و بارگذاری دوباره config
|
||||
- `package`: laneهای package/update/plugin بومی artifact بدون OpenWebUI یا ClawHub زنده
|
||||
- `product`: profile package بههمراه کانالهای MCP، پاکسازی cron/subagent، جستوجوی وب OpenAI، و OpenWebUI
|
||||
- `full`: بخشهای مسیر انتشار Docker با OpenWebUI
|
||||
- `smoke`: laneهای install/channel/agent، شبکه Gateway و reload پیکربندی
|
||||
- `package`: laneهای package/update/plugin بومی آرتیفکت بدون OpenWebUI یا ClawHub زنده
|
||||
- `product`: profile بسته بهعلاوه کانالهای MCP، پاکسازی cron/subagent، جستوجوی وب OpenAI و OpenWebUI
|
||||
- `full`: بخشهای مسیر انتشار Docker همراه با OpenWebUI
|
||||
- `custom`: انتخاب دقیق `docker_lanes` برای rerun متمرکز
|
||||
- وقتی فقط به پوشش کامل CI عادی برای release candidate نیاز دارید، workflow دستی `CI` را مستقیم اجرا کنید. dispatchهای دستی CI از scoping تغییرات عبور میکنند و shardهای Linux Node، shardهای bundled-plugin، قراردادهای channel، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسیهای docs، Skills پایتون، Windows، macOS، Android، و laneهای i18n رابط کاربری Control را اجباری میکنند.
|
||||
- اجرای مستقیم workflow دستی `CI` وقتی فقط به پوشش کامل CI عادی برای نامزد انتشار نیاز دارید. dispatchهای دستی CI از scoping تغییرات عبور میکنند و shardهای Linux Node، shardهای Plugin همراه، قراردادهای کانال، سازگاری Node 22، `check`، `check-additional`، build smoke، بررسیهای مستندات، Python skills، Windows، macOS، Android و laneهای i18n مربوط به Control UI را اجباری میکنند.
|
||||
مثال: `gh workflow run ci.yml --ref release/YYYY.M.D`
|
||||
- هنگام اعتبارسنجی telemetry انتشار، `pnpm qa:otel:smoke` را اجرا کنید. این دستور QA-lab را از طریق یک receiver محلی OTLP/HTTP اجرا میکند و نام spanهای trace صادرشده، attributeهای محدود، و redaction محتوا/شناسه را بدون نیاز به Opik، Langfuse، یا collector خارجی دیگر راستیآزمایی میکند.
|
||||
- پیش از هر انتشار tagشده، `pnpm release:check` را اجرا کنید
|
||||
- پس از وجود tag، برای توالی انتشار تغییردهنده `OpenClaw Release Publish` را اجرا کنید. آن را از `release/YYYY.M.D` dispatch کنید (یا هنگام انتشار tag قابل دسترسی از main، از `main`)، tag انتشار و `preflight_run_id` موفق npm مربوط به OpenClaw را پاس دهید، و scope پیشفرض انتشار Plugin یعنی `all-publishable` را نگه دارید مگر اینکه عمدا یک repair متمرکز اجرا میکنید. این workflow انتشار npm مربوط به Plugin، انتشار ClawHub مربوط به Plugin، و انتشار npm مربوط به OpenClaw را serialize میکند تا package core پیش از Pluginهای externalized خود منتشر نشود.
|
||||
- Release checkها اکنون در یک workflow دستی جدا اجرا میشوند:
|
||||
- اجرای `pnpm qa:otel:smoke` هنگام اعتبارسنجی telemetry انتشار. این دستور QA-lab را از طریق گیرنده محلی OTLP/HTTP تمرین میدهد و نام spanهای trace صادرشده، attributeهای محدود، و redaction محتوا/شناسه را بدون نیاز به Opik، Langfuse یا جمعآورنده خارجی دیگر تأیید میکند.
|
||||
- اجرای `pnpm release:check` پیش از هر انتشار tagشده
|
||||
- اجرای `OpenClaw Release Publish` برای توالی انتشار تغییردهنده پس از وجود tag. آن را از `release/YYYY.M.D` dispatch کنید (یا از `main` هنگام انتشار tag قابل دسترسی از main)، tag انتشار و `preflight_run_id` موفق npm مربوط به OpenClaw را بدهید، و scope پیشفرض انتشار Plugin یعنی `all-publishable` را نگه دارید مگر اینکه عمداً repair متمرکز اجرا میکنید. این workflow انتشار npm مربوط به Plugin، انتشار ClawHub مربوط به Plugin و انتشار npm مربوط به OpenClaw را serialize میکند تا بسته core پیش از Pluginهای externalized خودش منتشر نشود.
|
||||
- release checks اکنون در یک workflow دستی جداگانه اجرا میشوند:
|
||||
`OpenClaw Release Checks`
|
||||
- `OpenClaw Release Checks` همچنین پیش از تایید انتشار، lane برابری mock مربوط به QA Lab بههمراه profile سریع Matrix زنده و lane QA مربوط به Telegram را اجرا میکند. laneهای زنده از محیط `qa-live-shared` استفاده میکنند؛ Telegram همچنین از leaseهای credential مربوط به Convex CI استفاده میکند. وقتی موجودی کامل transport، media، و E2EE مربوط به Matrix را بهصورت موازی میخواهید، workflow دستی `QA-Lab - All Lanes` را با `matrix_profile=all` و `matrix_shards=true` اجرا کنید.
|
||||
- اعتبارسنجی runtime مربوط به install و upgrade میانسیستمعاملی بخشی از `OpenClaw Release Checks` عمومی و `Full Release Validation` است که workflow قابل استفاده مجدد `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` را مستقیم فراخوانی میکنند
|
||||
- این تفکیک عمدی است: مسیر واقعی انتشار npm را کوتاه، deterministic، و متمرکز بر artifact نگه دارید، درحالیکه checkهای زنده کندتر در lane خودشان باقی میمانند تا انتشار را متوقف یا مسدود نکنند
|
||||
- Release checkهای دارای secret باید از طریق `Full Release Validation` یا از workflow ref مربوط به `main`/release dispatch شوند تا منطق workflow و secretها کنترلشده بمانند
|
||||
- `OpenClaw Release Checks` یک branch، tag، یا SHA کامل commit را میپذیرد، به شرطی که commit resolveشده از یک branch یا tag انتشار OpenClaw قابل دسترسی باشد
|
||||
- preflight فقط-اعتبارسنجی `OpenClaw NPM Release` نیز SHA کامل ۴۰ کاراکتری commit مربوط به workflow-branch فعلی را بدون نیاز به tag pushشده میپذیرد
|
||||
- آن مسیر SHA فقط برای اعتبارسنجی است و نمیتواند به انتشار واقعی promote شود
|
||||
- در حالت SHA، workflow فقط برای بررسی metadata package مقدار `v<package.json version>` را synthesize میکند؛ انتشار واقعی همچنان به tag انتشار واقعی نیاز دارد
|
||||
- هر دو workflow مسیر انتشار و promotion واقعی را روی runnerهای GitHub-hosted نگه میدارند، درحالیکه مسیر اعتبارسنجی غیرتغییردهنده میتواند از runnerهای بزرگتر Blacksmith Linux استفاده کند
|
||||
- آن workflow دستور
|
||||
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
|
||||
را با استفاده از هر دو secret workflow یعنی `OPENAI_API_KEY` و `ANTHROPIC_API_KEY` اجرا میکند
|
||||
- preflight انتشار npm دیگر منتظر lane جداگانه release checks نمیماند
|
||||
- پیش از تایید، دستور `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
|
||||
(یا tag beta/correction متناظر) را اجرا کنید
|
||||
- پس از انتشار npm، دستور
|
||||
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
|
||||
(یا نسخه beta/correction متناظر) را اجرا کنید تا مسیر install مربوط به registry منتشرشده را در یک temp prefix تازه راستیآزمایی کنید
|
||||
- پس از انتشار beta، دستور `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
|
||||
را اجرا کنید تا onboarding package نصبشده، setup مربوط به Telegram، و Telegram E2E واقعی در برابر package منتشرشده npm با استفاده از pool مشترک credential اجارهشده Telegram را راستیآزمایی کنید. maintainerها برای اجرای local one-off میتوانند متغیرهای Convex را حذف کنند و سه credential محیطی `OPENCLAW_QA_TELEGRAM_*` را مستقیم پاس دهند.
|
||||
- maintainerها میتوانند همان check پس از انتشار را از GitHub Actions از طریق workflow دستی `NPM Telegram Beta E2E` اجرا کنند. این workflow عمدا فقط دستی است و روی هر merge اجرا نمیشود.
|
||||
- automation انتشار maintainer اکنون از preflight-then-promote استفاده میکند:
|
||||
- انتشار واقعی npm باید یک `preflight_run_id` موفق npm را پاس کرده باشد
|
||||
- انتشار واقعی npm باید از همان branch `main` یا `release/YYYY.M.D` که اجرای preflight موفق از آن بوده dispatch شود
|
||||
- انتشارهای stable npm بهطور پیشفرض `beta` هستند
|
||||
- انتشار stable npm میتواند از طریق ورودی workflow صراحتا `latest` را هدف بگیرد
|
||||
- mutation مبتنی بر token مربوط به npm dist-tag اکنون برای امنیت در
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
قرار دارد، زیرا `npm dist-tag add` همچنان به `NPM_TOKEN` نیاز دارد درحالیکه repo عمومی انتشار فقط OIDC را نگه میدارد
|
||||
- `macOS Release` عمومی فقط برای اعتبارسنجی است؛ وقتی یک tag فقط روی یک branch انتشار قرار دارد اما workflow از `main` dispatch میشود، `public_release_branch=release/YYYY.M.D` را تنظیم کنید
|
||||
- انتشار خصوصی واقعی mac باید `preflight_run_id` و `validate_run_id` خصوصی mac موفق را پاس کرده باشد
|
||||
- مسیرهای انتشار واقعی بهجای rebuild دوباره، artifactهای آمادهشده را promote میکنند
|
||||
- برای انتشارهای correction stable مانند `YYYY.M.D-N`، verifier پس از انتشار همچنین همان مسیر upgrade با temp-prefix از `YYYY.M.D` به `YYYY.M.D-N` را بررسی میکند تا correctionهای انتشار نتوانند بیصدا installهای global قدیمیتر را روی payload stable پایه باقی بگذارند
|
||||
- preflight انتشار npm بهصورت fail closed شکست میخورد مگر اینکه tarball هم `dist/control-ui/index.html` و هم payload غیرخالی `dist/control-ui/assets/` را شامل شود تا دوباره داشبورد مرورگر خالی منتشر نکنیم
|
||||
- verification پس از انتشار همچنین بررسی میکند که entrypointهای Plugin منتشرشده و metadata package در layout نصبشده registry حاضر باشند. انتشاری که payloadهای runtime مربوط به Plugin را ناقص ارسال کند، verifier پس از انتشار را fail میکند و نمیتواند به `latest` promote شود.
|
||||
- `pnpm test:install:smoke` همچنین بودجه `unpackedSize` مربوط به npm pack را روی tarball candidate update enforce میکند، بنابراین installer e2e پیش از مسیر انتشار release، pack bloat تصادفی را میگیرد
|
||||
- اگر کار انتشار به برنامهریزی CI، manifestهای timing مربوط به extension، یا ماتریسهای تست extension دست زده است، پیش از تایید خروجیهای ماتریس `plugin-prerelease-extension-shard` متعلق به planner را از `.github/workflows/plugin-prerelease.yml` دوباره generate و review کنید تا release noteها layout منسوخ CI را توصیف نکنند
|
||||
- `OpenClaw Release Checks` همچنین پیش از تأیید انتشار، lane همارزی mock مربوط به QA Lab بهعلاوه profile سریع live Matrix و lane مربوط به Telegram QA را اجرا میکند. laneهای live از environment `qa-live-shared` استفاده میکنند؛ Telegram همچنین از leaseهای credential مربوط به Convex CI استفاده میکند. وقتی inventory کامل transport، media و E2EE مربوط به Matrix را بهصورت موازی میخواهید، workflow دستی `QA-Lab - All Lanes` را با `matrix_profile=all` و `matrix_shards=true` اجرا کنید.
|
||||
- اعتبارسنجی runtime نصب و upgrade بین سیستمعاملها بخشی از `OpenClaw Release Checks` عمومی و `Full Release Validation` است که workflow قابل استفاده مجدد `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` را مستقیم فراخوانی میکنند
|
||||
- این جداسازی عمدی است: مسیر واقعی انتشار npm کوتاه، deterministic و متمرکز بر آرتیفکت بماند، در حالیکه بررسیهای live کندتر در lane خودشان میمانند تا انتشار را متوقف یا مسدود نکنند
|
||||
- release checkهای دارای secret باید از طریق `Full Release Validation` یا از workflow ref مربوط به `main`/release dispatch شوند تا منطق workflow و secretها کنترلشده بمانند
|
||||
- `OpenClaw Release Checks` یک branch، tag یا commit SHA کامل را میپذیرد، تا زمانی که commit resolveشده از یک branch یا release tag متعلق به OpenClaw قابل دسترسی باشد
|
||||
- پیشبررسی validation-only مربوط به `OpenClaw NPM Release` همچنین commit SHA کامل ۴۰ کاراکتری فعلی workflow-branch را بدون نیاز به tag pushشده میپذیرد
|
||||
- آن مسیر SHA فقط برای اعتبارسنجی است و نمیتواند به انتشار واقعی ارتقا یابد
|
||||
- در حالت SHA، workflow فقط برای بررسی فراداده بسته `v<package.json version>` را synthesize میکند؛ انتشار واقعی همچنان به tag انتشار واقعی نیاز دارد
|
||||
- هر دو workflow مسیر انتشار و promotion واقعی را روی runnerهای GitHub-hosted نگه میدارند، در حالیکه مسیر اعتبارسنجی غیرتغییردهنده میتواند از runnerهای بزرگتر Blacksmith Linux استفاده کند
|
||||
- آن workflow دستور `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` را با هر دو secret workflow یعنی `OPENAI_API_KEY` و `ANTHROPIC_API_KEY` اجرا میکند
|
||||
- پیشبررسی انتشار npm دیگر منتظر lane جداگانه release checks نمیماند
|
||||
- اجرای `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` (یا tag متناظر beta/correction) پیش از تأیید
|
||||
- پس از انتشار npm، اجرای `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (یا نسخه متناظر beta/correction) برای تأیید مسیر نصب registry منتشرشده در یک prefix موقت تازه
|
||||
- پس از انتشار beta، اجرای `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` برای تأیید onboarding بسته نصبشده، راهاندازی Telegram و Telegram E2E واقعی در برابر بسته npm منتشرشده با استفاده از pool اشتراکی credentialهای Telegram اجارهشده. one-offهای محلی maintainer میتوانند varهای Convex را حذف کنند و سه credential env مربوط به `OPENCLAW_QA_TELEGRAM_*` را مستقیم پاس بدهند.
|
||||
- Maintainerها میتوانند همان بررسی پس از انتشار را از GitHub Actions از طریق workflow دستی `NPM Telegram Beta E2E` اجرا کنند. این workflow عمداً فقط دستی است و روی هر merge اجرا نمیشود.
|
||||
- automation انتشار maintainer اکنون از الگوی preflight-then-promote استفاده میکند:
|
||||
- انتشار واقعی npm باید یک `preflight_run_id` موفق npm داشته باشد
|
||||
- انتشار واقعی npm باید از همان branch یعنی `main` یا `release/YYYY.M.D` که اجرای preflight موفق از آن بوده dispatch شود
|
||||
- انتشارهای stable npm بهصورت پیشفرض روی `beta` هستند
|
||||
- انتشار stable npm میتواند از طریق ورودی workflow صراحتاً `latest` را هدف بگیرد
|
||||
- تغییر token-based مربوط به dist-tag در npm اکنون برای امنیت در `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` قرار دارد، چون `npm dist-tag add` همچنان به `NPM_TOKEN` نیاز دارد در حالیکه repo عمومی انتشار OIDC-only را نگه میدارد
|
||||
- `macOS Release` عمومی فقط برای اعتبارسنجی است؛ وقتی یک tag فقط روی branch انتشار وجود دارد اما workflow از `main` dispatch شده است، `public_release_branch=release/YYYY.M.D` را تنظیم کنید
|
||||
- انتشار واقعی private mac باید `preflight_run_id` و `validate_run_id` موفق private mac داشته باشد
|
||||
- مسیرهای انتشار واقعی، آرتیفکتهای آمادهشده را promote میکنند بهجای اینکه دوباره آنها را rebuild کنند
|
||||
- برای انتشارهای correction پایدار مانند `YYYY.M.D-N`، verifier پس از انتشار همچنین همان مسیر upgrade با prefix موقت از `YYYY.M.D` به `YYYY.M.D-N` را بررسی میکند تا correctionهای انتشار نتوانند بیصدا نصبهای global قدیمیتر را روی payload stable پایه باقی بگذارند
|
||||
- پیشبررسی انتشار npm بهصورت fail closed شکست میخورد مگر اینکه tarball هم شامل `dist/control-ui/index.html` و هم payload غیرخالی `dist/control-ui/assets/` باشد تا دوباره dashboard مرورگر خالی منتشر نکنیم
|
||||
- اعتبارسنجی پس از انتشار همچنین بررسی میکند که entrypointهای Plugin منتشرشده و فراداده بسته در layout نصبشده registry وجود داشته باشند. انتشاری که payloadهای runtime مربوط به Plugin را ناقص ارسال کند، verifier پس از انتشار را شکست میدهد و نمیتواند به `latest` promote شود.
|
||||
- `pnpm test:install:smoke` همچنین بودجه `unpackedSize` مربوط به npm pack را روی tarball بهروزرسانی نامزد enforce میکند، تا installer e2e پیش از مسیر انتشار release، bloat تصادفی pack را تشخیص دهد
|
||||
- اگر کار انتشار به CI planning، manifestهای timing مربوط به extension، یا ماتریسهای آزمون extension دست زده است، پیش از تأیید، خروجیهای ماتریس `plugin-prerelease-extension-shard` متعلق به planner را از `.github/workflows/plugin-prerelease.yml` بازتولید و بازبینی کنید تا release notes یک layout قدیمی CI را توصیف نکنند
|
||||
- آمادگی انتشار stable macOS همچنین شامل سطحهای updater است:
|
||||
- GitHub release باید در نهایت `.zip`، `.dmg`، و `.dSYM.zip` بستهبندیشده را داشته باشد
|
||||
- `appcast.xml` روی `main` باید پس از انتشار به zip stable جدید اشاره کند
|
||||
- app بستهبندیشده باید bundle id غیر debug، URL feed غیرخالی Sparkle، و `CFBundleVersion` برابر یا بالاتر از کف build رسمی Sparkle برای آن نسخه انتشار را حفظ کند
|
||||
- release در GitHub باید در نهایت `.zip`، `.dmg` و `.dSYM.zip` بستهبندیشده را داشته باشد
|
||||
- `appcast.xml` روی `main` پس از انتشار باید به zip stable جدید اشاره کند
|
||||
- app بستهبندیشده باید bundle id غیر-debug، URL feed غیرخالی Sparkle، و `CFBundleVersion` برابر یا بالاتر از کف build canonical Sparkle برای آن نسخه انتشار را نگه دارد
|
||||
|
||||
## جعبههای تست انتشار
|
||||
## test boxهای انتشار
|
||||
|
||||
`Full Release Validation` روشی است که operatorها همه تستهای پیشانتشار را از یک entrypoint آغاز میکنند. برای proof مربوط به commit pinned روی branch سریعتغییر، از helper استفاده کنید تا هر workflow فرزند از یک branch موقت ثابتشده روی SHA هدف اجرا شود:
|
||||
`Full Release Validation` روشی است که operatorها همه آزمونهای پیش از انتشار را از یک entrypoint آغاز میکنند. برای proof مربوط به commit pinشده روی branch پرتحرک، از helper استفاده کنید تا هر workflow فرزند از branch موقتی ثابتشده روی SHA هدف اجرا شود:
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
این helper مقدار `release-ci/<sha>-...` را push میکند، `Full Release Validation` را از آن branch با `ref=<sha>` dispatch میکند، راستیآزمایی میکند که `headSha` هر workflow فرزند با هدف مطابقت دارد، سپس branch موقت را حذف میکند. این کار از اثبات تصادفی اجرای فرزند جدیدتر `main` جلوگیری میکند.
|
||||
helper، `release-ci/<sha>-...` را push میکند، `Full Release Validation` را از آن branch با `ref=<sha>` dispatch میکند، تأیید میکند که `headSha` هر workflow فرزند با هدف مطابق است، سپس branch موقت را حذف میکند. این کار از اثبات تصادفی اجرای فرزند جدیدتر `main` جلوگیری میکند.
|
||||
|
||||
برای اعتبارسنجی branch یا tag انتشار، آن را از workflow ref قابل اعتماد `main` اجرا کنید و branch یا tag انتشار را بهعنوان `ref` پاس دهید:
|
||||
برای اعتبارسنجی branch یا tag انتشار، آن را از workflow ref مورد اعتماد `main` اجرا کنید و branch یا tag انتشار را بهعنوان `ref` پاس بدهید:
|
||||
|
||||
```bash
|
||||
gh workflow run full-release-validation.yml \
|
||||
@ -188,45 +179,46 @@ gh workflow run full-release-validation.yml \
|
||||
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
|
||||
```
|
||||
|
||||
گردشکار ref هدف را resolve میکند، `CI` دستی را با
|
||||
`target_ref=<release-ref>` dispatch میکند، `OpenClaw Release Checks` را dispatch میکند، و زمانی که `release_profile=full` با
|
||||
`rerun_group=all` باشد یا وقتی `npm_telegram_package_spec` تنظیم شده باشد، E2E مستقل بسته Telegram را dispatch میکند. سپس `OpenClaw Release
|
||||
گردش کار، ref هدف را resolve میکند، `CI` دستی را با
|
||||
`target_ref=<release-ref>` dispatch میکند، `OpenClaw Release Checks` را dispatch میکند، و
|
||||
E2E مستقل بسته Telegram را زمانی dispatch میکند که `release_profile=full` با
|
||||
`rerun_group=all` باشد یا زمانی که `npm_telegram_package_spec` تنظیم شده باشد. سپس `OpenClaw Release
|
||||
Checks` install smoke، بررسیهای انتشار cross-OS، پوشش live/E2E Docker
|
||||
release-path، Package Acceptance با QA بسته Telegram، همارزی QA Lab،
|
||||
Matrix زنده، و Telegram زنده را fan out میکند. اجرای کامل فقط وقتی قابلقبول است که
|
||||
خلاصهٔ `Full Release Validation`
|
||||
نشان دهد `normal_ci` و `release_checks` موفق بودهاند. در حالت full/all،
|
||||
فرزند `npm_telegram` نیز باید موفق باشد؛ خارج از full/all نادیده گرفته میشود،
|
||||
مگر اینکه یک `npm_telegram_package_spec` منتشرشده ارائه شده باشد. خلاصهٔ نهایی
|
||||
verifier برای هر اجرای فرزند جدولهای کندترین job را شامل میشود، تا مدیر انتشار
|
||||
Matrix زنده، و Telegram زنده را fan out میکند. اجرای کامل فقط زمانی پذیرفتنی است که
|
||||
خلاصه `Full Release Validation`
|
||||
، `normal_ci` و `release_checks` را موفق نشان دهد. در حالت full/all،
|
||||
فرزند `npm_telegram` نیز باید موفق باشد؛ خارج از full/all، نادیده گرفته میشود
|
||||
مگر اینکه یک `npm_telegram_package_spec` منتشرشده ارائه شده باشد. خلاصه نهایی
|
||||
verifier شامل جدولهای کندترین job برای هر اجرای فرزند است، تا مدیر انتشار
|
||||
بتواند مسیر بحرانی فعلی را بدون دانلود کردن logها ببیند.
|
||||
برای ماتریس کامل مرحلهها، نام دقیق jobهای گردشکار، تفاوتهای پروفایل stable و full،
|
||||
artifactها، و handleهای بازاجرای متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید.
|
||||
برای ماتریس کامل مرحلهها، نام دقیق jobهای گردش کار، تفاوتهای پروفایل stable و full،
|
||||
artifactها، و handleهای rerun متمرکز، [اعتبارسنجی کامل انتشار](/fa/reference/full-release-validation) را ببینید.
|
||||
گردشکارهای فرزند از ref مورداعتمادی dispatch میشوند که `Full Release
|
||||
Validation` را اجرا میکند، معمولاً `--ref main`، حتی وقتی `ref` هدف به یک
|
||||
شاخه یا tag انتشار قدیمیتر اشاره کند. هیچ ورودی workflow-ref جداگانهای برای Full Release Validation
|
||||
وجود ندارد؛ harness مورداعتماد را با انتخاب ref اجرای گردشکار انتخاب کنید.
|
||||
شاخه یا tag انتشار قدیمیتر اشاره کند. ورودی جداگانهای برای Full Release Validation
|
||||
workflow-ref وجود ندارد؛ harness مورداعتماد را با انتخاب ref اجرای گردش کار انتخاب کنید.
|
||||
برای اثبات commit دقیق روی `main` متحرک از `--ref main -f ref=<sha>` استفاده نکنید؛
|
||||
SHAهای خام commit نمیتوانند refهای dispatch گردشکار باشند، پس از
|
||||
`pnpm ci:full-release --sha <sha>` برای ساخت شاخهٔ موقت pin شده استفاده کنید.
|
||||
SHAهای خام commit نمیتوانند refهای workflow dispatch باشند، بنابراین از
|
||||
`pnpm ci:full-release --sha <sha>` برای ایجاد شاخه موقت pinشده استفاده کنید.
|
||||
|
||||
برای انتخاب گسترهٔ live/provider از `release_profile` استفاده کنید:
|
||||
از `release_profile` برای انتخاب گستره live/provider استفاده کنید:
|
||||
|
||||
- `minimum`: سریعترین مسیر live و Docker حیاتی برای انتشار در OpenAI/core
|
||||
- `stable`: minimum بهعلاوهٔ پوشش provider/backend پایدار برای تأیید انتشار
|
||||
- `full`: stable بهعلاوهٔ پوشش گستردهٔ provider/media مشورتی
|
||||
- `minimum`: سریعترین مسیر release-critical OpenAI/core live و Docker
|
||||
- `stable`: minimum بهعلاوه پوشش provider/backend پایدار برای تأیید انتشار
|
||||
- `full`: stable بهعلاوه پوشش گسترده provider/media مشورتی
|
||||
|
||||
`OpenClaw Release Checks` از ref گردشکار مورداعتماد استفاده میکند تا ref هدف را
|
||||
یکبار بهعنوان `release-package-under-test` resolve کند و همان artifact را هم در
|
||||
بررسیهای Docker مسیر انتشار و هم در Package Acceptance دوباره استفاده کند. این کار همهٔ
|
||||
boxهای رو به بسته را روی همان byteها نگه میدارد و از buildهای تکراری بسته جلوگیری میکند.
|
||||
install smoke مربوط به OpenAI روی cross-OS زمانی که متغیر repo/org تنظیم باشد از
|
||||
`OPENCLAW_CROSS_OS_OPENAI_MODEL` استفاده میکند، وگرنه از `openai/gpt-5.4`، چون این lane
|
||||
در حال اثبات نصب بسته، onboarding، راهاندازی Gateway، و یک نوبت agent زنده است
|
||||
نه benchmark کردن کندترین مدل پیشفرض. ماتریس گستردهتر provider زنده همچنان محل
|
||||
پوشش مخصوص مدل است.
|
||||
`OpenClaw Release Checks` از ref گردش کار مورداعتماد برای resolve کردن ref هدف
|
||||
یکبار بهصورت `release-package-under-test` استفاده میکند و همان artifact را هم در
|
||||
بررسیهای Docker مسیر انتشار و هم در Package Acceptance دوباره استفاده میکند. این کار همه
|
||||
boxهای مواجه با بسته را روی همان bytes نگه میدارد و از ساختهای تکراری بسته جلوگیری میکند.
|
||||
install smoke مربوط به cross-OS OpenAI از `OPENCLAW_CROSS_OS_OPENAI_MODEL` زمانی استفاده میکند که
|
||||
متغیر repo/org تنظیم شده باشد، وگرنه از `openai/gpt-5.4`، چون این lane در حال
|
||||
اثبات نصب بسته، onboarding، راهاندازی Gateway، و یک نوبت agent زنده است
|
||||
نه benchmark کردن کندترین مدل پیشفرض. ماتریس گستردهتر live provider همچنان
|
||||
جای پوشش اختصاصی مدل است.
|
||||
|
||||
بسته به مرحلهٔ انتشار از این گونهها استفاده کنید:
|
||||
بسته به مرحله انتشار از این variantها استفاده کنید:
|
||||
|
||||
```bash
|
||||
# Validate an unpublished release candidate branch.
|
||||
@ -256,41 +248,41 @@ gh workflow run full-release-validation.yml \
|
||||
-f npm_telegram_provider_mode=mock-openai
|
||||
```
|
||||
|
||||
از چتر کامل بهعنوان اولین بازاجرا پس از یک fix متمرکز استفاده نکنید. اگر یک box
|
||||
fail شد، برای اثبات بعدی از گردشکار فرزند، job، lane مربوط به Docker، پروفایل بسته، provider مدل،
|
||||
یا lane مربوط به QA که fail شده استفاده کنید. چتر کامل را فقط وقتی دوباره اجرا کنید
|
||||
که fix، orchestration مشترک انتشار را تغییر داده باشد یا شواهد قبلی همهٔ boxها را
|
||||
کهنه کرده باشد. verifier نهایی چتر، idهای ثبتشدهٔ اجرای گردشکار فرزند را دوباره بررسی میکند،
|
||||
پس پس از اینکه یک گردشکار فرزند با موفقیت دوباره اجرا شد، فقط job والد fail شدهٔ
|
||||
`Verify full validation` را دوباره اجرا کنید.
|
||||
از چتر full بهعنوان اولین rerun پس از یک fix متمرکز استفاده نکنید. اگر یک box
|
||||
fail شد، برای اثبات بعدی از گردش کار فرزند، job، lane مربوط به Docker، پروفایل بسته، provider
|
||||
مدل، یا lane مربوط به QA که fail شده است استفاده کنید. چتر full را فقط زمانی دوباره اجرا کنید که
|
||||
fix، orchestration مشترک انتشار را تغییر داده یا شواهد قبلی همه boxها را
|
||||
stale کرده باشد. verifier نهایی چتر، idهای ثبتشده اجرای گردشکارهای فرزند را دوباره بررسی میکند؛
|
||||
بنابراین پس از اینکه یک گردش کار فرزند با موفقیت rerun شد، فقط job والد failشده
|
||||
`Verify full validation` را rerun کنید.
|
||||
|
||||
برای بازیابی محدود، `rerun_group` را به چتر پاس دهید. `all` اجرای واقعی
|
||||
release-candidate است، `ci` فقط فرزند CI معمولی را اجرا میکند، `plugin-prerelease`
|
||||
فقط فرزند Plugin مخصوص انتشار را اجرا میکند، `release-checks` همهٔ boxهای انتشار
|
||||
را اجرا میکند، و گروههای انتشار محدودتر عبارتاند از `install-smoke`، `cross-os`،
|
||||
`live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، و `npm-telegram`.
|
||||
بازاجراهای متمرکز `npm-telegram` به `npm_telegram_package_spec` نیاز دارند؛ اجراهای full/all
|
||||
با `release_profile=full` از artifact بستهٔ release-checks استفاده میکنند.
|
||||
release-candidate است، `ci` فقط فرزند CI عادی را اجرا میکند، `plugin-prerelease`
|
||||
فقط فرزند Plugin مخصوص انتشار را اجرا میکند، `release-checks` همه boxهای انتشار
|
||||
را اجرا میکند، و گروههای محدودتر انتشار `install-smoke`، `cross-os`،
|
||||
`live-e2e`، `package`، `qa`، `qa-parity`، `qa-live`، و `npm-telegram` هستند.
|
||||
rerunهای متمرکز `npm-telegram` به `npm_telegram_package_spec` نیاز دارند؛ اجراهای full/all
|
||||
با `release_profile=full` از artifact بسته release-checks استفاده میکنند.
|
||||
|
||||
### Vitest
|
||||
|
||||
box مربوط به Vitest همان گردشکار فرزند دستی `CI` است. CI دستی عمداً
|
||||
scoping تغییرات را دور میزند و graph تست عادی را برای release candidate اجباری میکند:
|
||||
shardهای Linux Node، shardهای Pluginهای bundled، قراردادهای channel، سازگاری Node 22،
|
||||
`check`، `check-additional`، build smoke، بررسیهای docs، Skills پایتون، Windows، macOS،
|
||||
Android، و i18n مربوط به Control UI.
|
||||
box مربوط به Vitest همان گردش کار فرزند `CI` دستی است. CI دستی عمداً
|
||||
scoping تغییرات را دور میزند و گراف تست عادی را برای release candidate اجباری میکند:
|
||||
شاردهای Linux Node، شاردهای bundled-plugin، قراردادهای channel، سازگاری Node 22،
|
||||
`check`، `check-additional`، build smoke، بررسیهای docs، Python
|
||||
skills، Windows، macOS، Android، و Control UI i18n.
|
||||
|
||||
از این box برای پاسخ به «آیا source tree کل test suite عادی را pass کرد؟» استفاده کنید.
|
||||
این همان اعتبارسنجی محصول در مسیر انتشار نیست. شواهدی که باید نگه دارید:
|
||||
از این box برای پاسخ به این سؤال استفاده کنید: «آیا درخت source از کل مجموعه تست عادی عبور کرد؟»
|
||||
این با اعتبارسنجی product مسیر انتشار یکسان نیست. شواهدی که باید نگه دارید:
|
||||
|
||||
- خلاصهٔ `Full Release Validation` که URL اجرای dispatch شدهٔ `CI` را نشان میدهد
|
||||
- سبز بودن اجرای `CI` روی SHA دقیق هدف
|
||||
- نام shardهای fail شده یا کند در jobهای CI هنگام بررسی regressionها
|
||||
- خلاصه `Full Release Validation` که URL اجرای `CI` dispatchشده را نشان میدهد
|
||||
- اجرای `CI` روی SHA دقیق هدف green باشد
|
||||
- نام شاردهای failشده یا کند از jobهای CI هنگام بررسی regressionها
|
||||
- artifactهای زمانبندی Vitest مانند `.artifacts/vitest-shard-timings.json` وقتی
|
||||
یک اجرا به تحلیل کارایی نیاز دارد
|
||||
یک اجرا به تحلیل performance نیاز دارد
|
||||
|
||||
CI دستی را مستقیماً فقط وقتی اجرا کنید که انتشار به CI عادی deterministic نیاز دارد
|
||||
اما نه به boxهای Docker، QA Lab، live، cross-OS، یا package:
|
||||
CI دستی را فقط زمانی مستقیماً اجرا کنید که انتشار به CI عادی deterministic نیاز دارد اما
|
||||
به boxهای Docker، QA Lab، live، cross-OS، یا package نیاز ندارد:
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
@ -299,104 +291,105 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
### Docker
|
||||
|
||||
box مربوط به Docker در `OpenClaw Release Checks` از طریق
|
||||
`openclaw-live-and-e2e-checks-reusable.yml` بهعلاوهٔ گردشکار
|
||||
`install-smoke` در حالت انتشار قرار دارد. این box، release candidate را از طریق
|
||||
محیطهای Docker بستهبندیشده اعتبارسنجی میکند، نه فقط تستهای سطح source.
|
||||
`openclaw-live-and-e2e-checks-reusable.yml`، بهعلاوه گردش کار release-mode
|
||||
`install-smoke` قرار دارد. این box، release candidate را از طریق محیطهای Docker بستهبندیشده
|
||||
اعتبارسنجی میکند، نه فقط تستهای سطح source.
|
||||
|
||||
پوشش Docker انتشار شامل موارد زیر است:
|
||||
پوشش Docker انتشار شامل این موارد است:
|
||||
|
||||
- install smoke کامل با فعال بودن slow Bun global install smoke
|
||||
- آمادهسازی/استفادهٔ مجدد image smoke مربوط به Dockerfile ریشه بر اساس SHA هدف، با jobهای QR،
|
||||
root/gateway، و installer/Bun smoke که بهعنوان shardهای جداگانهٔ install-smoke اجرا میشوند
|
||||
- آمادهسازی/استفاده مجدد از تصویر smoke مربوط به Dockerfile ریشه بر اساس SHA هدف، با jobهای QR،
|
||||
root/gateway، و installer/Bun smoke که بهصورت شاردهای install-smoke جداگانه اجرا میشوند
|
||||
- laneهای E2E مخزن
|
||||
- chunkهای Docker مسیر انتشار: `core`، `package-update-openai`،
|
||||
`package-update-anthropic`، `package-update-core`، `plugins-runtime-plugins`،
|
||||
`plugins-runtime-services`,
|
||||
`plugins-runtime-services`،
|
||||
`plugins-runtime-install-a`، `plugins-runtime-install-b`،
|
||||
`plugins-runtime-install-c`، `plugins-runtime-install-d`،
|
||||
`plugins-runtime-install-e`، `plugins-runtime-install-f`،
|
||||
`plugins-runtime-install-g`، و `plugins-runtime-install-h`
|
||||
- پوشش OpenWebUI داخل chunk `plugins-runtime-services` وقتی درخواست شده باشد
|
||||
- laneهای تفکیکشدهٔ install/uninstall مربوط به Pluginهای bundled
|
||||
- پوشش OpenWebUI داخل chunk مربوط به `plugins-runtime-services` وقتی درخواست شده باشد
|
||||
- laneهای جداشده install/uninstall برای bundled plugin
|
||||
از `bundled-plugin-install-uninstall-0` تا
|
||||
`bundled-plugin-install-uninstall-23`
|
||||
- suiteهای provider زنده/E2E و پوشش مدل زندهٔ Docker وقتی release checks
|
||||
suiteهای live را شامل شوند
|
||||
- مجموعههای live/E2E provider و پوشش مدل live در Docker وقتی release checks
|
||||
شامل مجموعههای live باشد
|
||||
|
||||
پیش از بازاجرا از artifactهای Docker استفاده کنید. scheduler مسیر انتشار
|
||||
قبل از rerun کردن از artifactهای Docker استفاده کنید. scheduler مسیر انتشار
|
||||
`.artifacts/docker-tests/` را با logهای lane، `summary.json`، `failures.json`،
|
||||
زمانبندی phaseها، JSON برنامهٔ scheduler، و commandهای بازاجرا upload میکند. برای بازیابی متمرکز،
|
||||
بهجای بازاجرای همهٔ chunkهای انتشار، از `docker_lanes=<lane[,lane]>` روی گردشکار قابلاستفادهٔ مجدد live/E2E استفاده کنید.
|
||||
commandهای بازاجرای تولیدشده، `package_artifact_run_id` قبلی و ورودیهای image آمادهشدهٔ Docker
|
||||
را وقتی موجود باشند شامل میشوند، پس یک lane fail شده میتواند همان tarball و imageهای GHCR را دوباره استفاده کند.
|
||||
زمانبندی phaseها، JSON برنامه scheduler، و فرمانهای rerun upload میکند. برای بازیابی متمرکز،
|
||||
بهجای rerun کردن همه chunkهای انتشار، از `docker_lanes=<lane[,lane]>` روی گردش کار reusable live/E2E استفاده کنید.
|
||||
فرمانهای rerun تولیدشده در صورت موجود بودن شامل `package_artifact_run_id` قبلی
|
||||
و ورودیهای تصویر Docker آمادهشده هستند، بنابراین یک lane failشده میتواند همان tarball و
|
||||
تصویرهای GHCR را دوباره استفاده کند.
|
||||
|
||||
### QA Lab
|
||||
|
||||
box مربوط به QA Lab نیز بخشی از `OpenClaw Release Checks` است. این gate رفتار agentic
|
||||
و release در سطح channel است، جدا از Vitest و سازوکارهای package مربوط به Docker.
|
||||
box مربوط به QA Lab نیز بخشی از `OpenClaw Release Checks` است. این gate انتشار
|
||||
برای رفتار agentic و سطح channel است و از Vitest و مکانیک بسته Docker جداست.
|
||||
|
||||
پوشش QA Lab انتشار شامل موارد زیر است:
|
||||
پوشش QA Lab انتشار شامل این موارد است:
|
||||
|
||||
- lane همارزی mock که lane نامزد OpenAI را با baseline Opus 4.6
|
||||
- lane همارزی mock که lane کاندید OpenAI را با baseline مربوط به Opus 4.6
|
||||
با استفاده از agentic parity pack مقایسه میکند
|
||||
- پروفایل سریع QA مربوط به Matrix زنده با استفاده از محیط `qa-live-shared`
|
||||
- lane QA مربوط به Telegram زنده با استفاده از leaseهای credential مربوط به Convex CI
|
||||
- پروفایل fast live Matrix QA با استفاده از محیط `qa-live-shared`
|
||||
- lane live Telegram QA با استفاده از leaseهای credential مربوط به Convex CI
|
||||
- `pnpm qa:otel:smoke` وقتی telemetry انتشار به اثبات محلی صریح نیاز دارد
|
||||
|
||||
از این box برای پاسخ به «آیا انتشار در سناریوهای QA و جریانهای channel زنده درست رفتار میکند؟»
|
||||
استفاده کنید. هنگام تأیید انتشار، URLهای artifact برای laneهای parity، Matrix، و Telegram را نگه دارید.
|
||||
پوشش کامل Matrix همچنان بهعنوان اجرای دستی sharded QA-Lab در دسترس است،
|
||||
نه lane حیاتی پیشفرض انتشار.
|
||||
از این box برای پاسخ به این سؤال استفاده کنید: «آیا انتشار در سناریوهای QA و
|
||||
جریانهای channel زنده درست رفتار میکند؟» هنگام تأیید انتشار، URLهای artifact مربوط به laneهای parity، Matrix، و Telegram
|
||||
را نگه دارید. پوشش کامل Matrix همچنان بهصورت اجرای دستی sharded QA-Lab در دسترس است،
|
||||
نه lane پیشفرض release-critical.
|
||||
|
||||
### Package
|
||||
|
||||
box مربوط به Package، gate محصول قابلنصب است. این box با
|
||||
box مربوط به Package، gate محصول قابل نصب است. این box توسط
|
||||
`Package Acceptance` و resolver
|
||||
`scripts/resolve-openclaw-package-candidate.mjs` پشتیبانی میشود. resolver یک
|
||||
candidate را به tarball `package-under-test` که Docker E2E مصرف میکند normalize میکند،
|
||||
inventory بسته را اعتبارسنجی میکند، نسخهٔ بسته و SHA-256 را ثبت میکند، و ref
|
||||
harness گردشکار را از ref منبع بسته جدا نگه میدارد.
|
||||
candidate را به tarball مربوط به `package-under-test` که توسط Docker E2E مصرف میشود normalize میکند،
|
||||
inventory بسته را اعتبارسنجی میکند، version بسته و SHA-256 را ثبت میکند، و ref
|
||||
harness گردش کار را جدا از ref source بسته نگه میدارد.
|
||||
|
||||
منابع candidate پشتیبانیشده:
|
||||
|
||||
- `source=npm`: `openclaw@beta`، `openclaw@latest`، یا یک نسخهٔ دقیق انتشار OpenClaw
|
||||
- `source=ref`: بستهبندی یک شاخه، tag، یا SHA کامل commit مربوط به `package_ref` مورداعتماد
|
||||
با harness انتخابشدهٔ `workflow_ref`
|
||||
- `source=url`: دانلود یک `.tgz` با HTTPS همراه با `package_sha256` الزامی
|
||||
- `source=artifact`: استفادهٔ مجدد از یک `.tgz` که اجرای دیگری از GitHub Actions upload کرده است
|
||||
- `source=npm`: `openclaw@beta`، `openclaw@latest`، یا یک version دقیق انتشار OpenClaw
|
||||
- `source=ref`: pack کردن شاخه، tag، یا SHA کامل commit مربوط به `package_ref` مورداعتماد
|
||||
با harness انتخابشده `workflow_ref`
|
||||
- `source=url`: دانلود یک `.tgz` از HTTPS با `package_sha256` الزامی
|
||||
- `source=artifact`: استفاده مجدد از یک `.tgz` که توسط اجرای دیگری از GitHub Actions upload شده است
|
||||
|
||||
`OpenClaw Release Checks`، Package Acceptance را با `source=artifact`،
|
||||
artifact آمادهشدهٔ بستهٔ انتشار، `suite_profile=custom`،
|
||||
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
|
||||
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
|
||||
`OpenClaw Release Checks`، Package Acceptance را با `source=artifact`، artifact
|
||||
بسته انتشار آمادهشده، `suite_profile=custom`،
|
||||
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`،
|
||||
`published_upgrade_survivor_baselines=all-since-2026.4.23`،
|
||||
`published_upgrade_survivor_scenarios=reported-issues`، و
|
||||
`telegram_mode=mock-openai` اجرا میکند. Package Acceptance، migration، update،
|
||||
پاکسازی dependency کهنهٔ Plugin، fixtureهای Plugin آفلاین، update Plugin، و QA بستهٔ Telegram
|
||||
را روی همان tarball resolve شده نگه میدارد. ماتریس upgrade هر baseline پایدار منتشرشده در npm را از `2026.4.23` تا `latest` پوشش میدهد؛ برای candidate ازپیش ship شده از
|
||||
Package Acceptance با `source=npm` استفاده کنید، یا برای tarball محلی npm مبتنی بر SHA پیش از انتشار،
|
||||
از `source=ref`/`source=artifact` استفاده کنید. این جایگزین GitHub-native برای بیشتر
|
||||
پوشش package/update است که قبلاً به Parallels نیاز داشت. بررسیهای انتشار cross-OS همچنان
|
||||
برای onboarding، installer، و رفتار platform مخصوص OS مهماند، اما اعتبارسنجی محصول
|
||||
package/update باید Package Acceptance را ترجیح دهد.
|
||||
`telegram_mode=mock-openai` اجرا میکند. Package Acceptance، migration، update، پاکسازی dependency مربوط به stale
|
||||
plugin، fixtureهای offline plugin، update مربوط به Plugin، و QA بسته Telegram
|
||||
را در برابر همان tarball resolveشده نگه میدارد. ماتریس upgrade، هر baseline پایدار منتشرشده در npm از `2026.4.23` تا `latest` را پوشش میدهد؛ برای candidateای که قبلاً shipped شده است از
|
||||
Package Acceptance با `source=npm` استفاده کنید، یا برای یک tarball محلی npm با پشتوانه SHA قبل از
|
||||
publish از `source=ref`/`source=artifact` استفاده کنید. این جایگزین GitHub-native
|
||||
برای بیشتر پوشش package/update است که قبلاً به Parallels نیاز داشت.
|
||||
بررسیهای انتشار cross-OS همچنان برای onboarding، installer، و رفتار platform مختص OS مهماند،
|
||||
اما اعتبارسنجی product مربوط به package/update باید Package Acceptance را ترجیح دهد.
|
||||
|
||||
چکلیست canonical برای اعتبارسنجی update و Plugin،
|
||||
[تست کردن updateها و Pluginها](/fa/help/testing-updates-plugins) است. هنگام تصمیمگیری دربارهٔ اینکه کدام
|
||||
lane محلی، Docker، Package Acceptance، یا release-check یک install/update Plugin،
|
||||
پاکسازی doctor، یا تغییر migration بستهٔ منتشرشده را اثبات میکند، از آن استفاده کنید.
|
||||
migration جامع update منتشرشده از هر بستهٔ پایدار `2026.4.23+` یک گردشکار دستی جداگانهٔ
|
||||
`Update Migration` است، نه بخشی از Full Release CI.
|
||||
[تست updateها و Pluginها](/fa/help/testing-updates-plugins) است. هنگام تصمیمگیری درباره اینکه کدام
|
||||
lane محلی، Docker، Package Acceptance، یا release-check یک تغییر در install/update مربوط به Plugin،
|
||||
پاکسازی doctor، یا migration بسته منتشرشده را اثبات میکند، از آن استفاده کنید.
|
||||
migration کامل update منتشرشده از هر بسته پایدار `2026.4.23+` یک گردش کار دستی
|
||||
`Update Migration` جداگانه است، نه بخشی از Full Release CI.
|
||||
|
||||
leniency قدیمی package-acceptance عمداً time boxed است. بستهها تا
|
||||
`2026.4.25` ممکن است از مسیر سازگاری برای gapهای metadata که قبلاً
|
||||
در npm منتشر شدهاند استفاده کنند: entryهای private QA inventory که در tarball نیستند،
|
||||
نبود `gateway install --wrapper`، نبود patch fileها در fixture git مشتقشده از tarball،
|
||||
نبود `update.channel` پایدارشده، مکانهای قدیمی install-record مربوط به Plugin،
|
||||
نبود persistence برای marketplace install-record، و migration metadata config
|
||||
هنگام `plugins update`. بستهٔ منتشرشدهٔ `2026.4.26` ممکن است برای stamp fileهای metadata مربوط به build محلی
|
||||
که قبلاً ship شدهاند warn بدهد. بستههای بعدی باید قراردادهای مدرن package را رعایت کنند؛
|
||||
همان gapها باعث fail شدن اعتبارسنجی انتشار میشوند.
|
||||
نرمگیری legacy package-acceptance عمداً بازه زمانی محدود دارد. بستهها تا
|
||||
`2026.4.25` ممکن است برای gapهای metadata که قبلاً به npm منتشر شدهاند از مسیر compatibility استفاده کنند:
|
||||
ورودیهای private QA inventory که در tarball وجود ندارند، نبود
|
||||
`gateway install --wrapper`، نبود patch fileها در fixture git مشتقشده از tarball،
|
||||
نبود `update.channel` persisted، مکانهای legacy install-record مربوط به Plugin،
|
||||
نبود پایداری install-record مربوط به marketplace، و migration metadata config
|
||||
هنگام `plugins update`. بسته منتشرشده `2026.4.26` ممکن است برای فایلهای stamp مربوط به local build metadata
|
||||
که قبلاً shipped شدهاند warn بدهد. بستههای بعدی
|
||||
باید قراردادهای modern package را رعایت کنند؛ همان gapها باعث fail شدن validation انتشار میشوند.
|
||||
|
||||
وقتی پرسش انتشار دربارهٔ یک بستهٔ واقعاً قابلنصب است، از پروفایلهای گستردهتر Package Acceptance استفاده کنید:
|
||||
وقتی سؤال انتشار درباره یک بسته واقعاً قابل نصب است، از پروفایلهای گستردهتر Package Acceptance استفاده کنید:
|
||||
|
||||
```bash
|
||||
gh workflow run package-acceptance.yml \
|
||||
@ -410,34 +403,34 @@ gh workflow run package-acceptance.yml \
|
||||
|
||||
پروفایلهای رایج package:
|
||||
|
||||
- `smoke`: laneهای سریع install/channel/agent بسته، شبکهٔ gateway، و reload config
|
||||
- `package`: قراردادهای install/update/Plugin package بدون ClawHub زنده؛ این پیشفرض release-check
|
||||
- `smoke`: laneهای سریع install/channel/agent بسته، شبکه Gateway، و reload کردن config
|
||||
- `package`: قراردادهای install/update/plugin package بدون live ClawHub؛ این پیشفرض release-check
|
||||
است
|
||||
- `product`: `package` بهعلاوهٔ channelهای MCP، پاکسازی cron/subagent، جستوجوی وب OpenAI،
|
||||
- `product`: `package` بهعلاوه channelهای MCP، پاکسازی cron/subagent، جستوجوی وب OpenAI،
|
||||
و OpenWebUI
|
||||
- `full`: chunkهای Docker مسیر انتشار با OpenWebUI
|
||||
- `custom`: فهرست دقیق `docker_lanes` برای بازاجراهای متمرکز
|
||||
- `full`: chunkهای Docker مسیر انتشار همراه با OpenWebUI
|
||||
- `custom`: فهرست دقیق `docker_lanes` برای rerunهای متمرکز
|
||||
|
||||
برای اثبات Telegram نامزد بسته، `telegram_mode=mock-openai` یا
|
||||
`telegram_mode=live-frontier` را در Package Acceptance فعال کنید. این workflow فایل tarball
|
||||
حلشدهی `package-under-test` را به مسیر Telegram میفرستد؛ workflow مستقل
|
||||
Telegram همچنان برای بررسیهای پس از انتشار، مشخصات npm منتشرشده را میپذیرد.
|
||||
برای اثبات Telegram کاندیدای بسته، `telegram_mode=mock-openai` یا
|
||||
`telegram_mode=live-frontier` را در Package Acceptance فعال کنید. گردشکار،
|
||||
tarball حلشدهی `package-under-test` را به مسیر Telegram میفرستد؛ گردشکار
|
||||
مستقل Telegram همچنان یک مشخصات npm منتشرشده را برای بررسیهای پس از انتشار میپذیرد.
|
||||
|
||||
## خودکارسازی انتشار Release
|
||||
|
||||
`OpenClaw Release Publish` نقطهی ورود معمول برای انتشار تغییردهنده است. این مورد
|
||||
workflowهای منتشرکنندهی مورد اعتماد را به ترتیبی که Release نیاز دارد هماهنگ میکند:
|
||||
`OpenClaw Release Publish` نقطهی ورود معمول انتشار تغییردهنده است. این مورد
|
||||
گردشکارهای trusted-publisher را به ترتیبی که release نیاز دارد هماهنگ میکند:
|
||||
|
||||
1. تگ Release را checkout کنید و SHA کامیت آن را حل کنید.
|
||||
2. تأیید کنید که تگ از `main` یا `release/*` قابل دسترسی است.
|
||||
1. tag انتشار را checkout کنید و SHA کامیت آن را حل کنید.
|
||||
2. بررسی کنید tag از `main` یا `release/*` قابل دسترسی باشد.
|
||||
3. `pnpm plugins:sync:check` را اجرا کنید.
|
||||
4. `Plugin NPM Release` را با `publish_scope=all-publishable` و
|
||||
`ref=<release-sha>` dispatch کنید.
|
||||
5. `Plugin ClawHub Release` را با همان scope و SHA dispatch کنید.
|
||||
6. `OpenClaw NPM Release` را با تگ Release، dist-tag مربوط به npm، و
|
||||
6. `OpenClaw NPM Release` را با tag انتشار، dist-tag مربوط به npm، و
|
||||
`preflight_run_id` ذخیرهشده dispatch کنید.
|
||||
|
||||
نمونهی انتشار بتا:
|
||||
نمونهی انتشار Beta:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -447,17 +440,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
نمونهی انتشار آلفا:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
--ref release/YYYY.M.D \
|
||||
-f tag=vYYYY.M.D-alpha.N \
|
||||
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
|
||||
-f npm_dist_tag=alpha
|
||||
```
|
||||
|
||||
انتشار پایدار به dist-tag پیشفرض بتا:
|
||||
انتشار stable به dist-tag پیشفرض beta:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -467,7 +450,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
ارتقای پایدار مستقیماً به `latest` صریح است:
|
||||
ارتقای stable مستقیم به `latest` صریح است:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -477,90 +460,91 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=latest
|
||||
```
|
||||
|
||||
از workflowهای سطح پایینتر `Plugin NPM Release` و `Plugin ClawHub Release`
|
||||
فقط برای تعمیر متمرکز یا بازانتشار استفاده کنید. برای تعمیر Plugin انتخابشده،
|
||||
`plugin_publish_scope=selected` و `plugins=@openclaw/name` را به
|
||||
از گردشکارهای سطح پایینتر `Plugin NPM Release` و `Plugin ClawHub Release`
|
||||
فقط برای کارهای repair یا انتشار مجدد متمرکز استفاده کنید. برای repair یک plugin
|
||||
انتخابشده، `plugin_publish_scope=selected` و `plugins=@openclaw/name` را به
|
||||
`OpenClaw Release Publish` بدهید، یا وقتی بستهی OpenClaw نباید منتشر شود،
|
||||
workflow فرزند را مستقیماً dispatch کنید.
|
||||
گردشکار فرزند را مستقیم dispatch کنید.
|
||||
|
||||
## ورودیهای workflow مربوط به NPM
|
||||
## ورودیهای گردشکار NPM
|
||||
|
||||
`OpenClaw NPM Release` این ورودیهای کنترلشده توسط اپراتور را میپذیرد:
|
||||
|
||||
- `tag`: تگ Release الزامی مانند `v2026.4.2`، `v2026.4.2-1`، یا
|
||||
`v2026.4.2-alpha.1` یا `v2026.4.2-beta.1`؛ وقتی `preflight_only=true` باشد، میتواند SHA کامل ۴۰کاراکتری کامیت شاخهی فعلی workflow نیز برای preflight فقط اعتبارسنجی باشد
|
||||
- `preflight_only`: `true` فقط برای اعتبارسنجی/ساخت/بسته، `false` برای مسیر
|
||||
انتشار واقعی
|
||||
- `preflight_run_id`: در مسیر انتشار واقعی الزامی است تا workflow از tarball
|
||||
آمادهشده در اجرای preflight موفق دوباره استفاده کند
|
||||
- `npm_dist_tag`: تگ هدف npm برای مسیر انتشار؛ مقدار پیشفرض `beta` است
|
||||
- `tag`: tag انتشار الزامی مانند `v2026.4.2`، `v2026.4.2-1`، یا
|
||||
`v2026.4.2-beta.1`؛ وقتی `preflight_only=true` باشد، برای preflight فقط
|
||||
اعتبارسنجی میتواند SHA کامل ۴۰ کاراکتری کامیت شاخهی گردشکار فعلی نیز باشد
|
||||
- `preflight_only`: مقدار `true` فقط برای اعتبارسنجی/build/package، مقدار `false` برای
|
||||
مسیر انتشار واقعی
|
||||
- `preflight_run_id`: در مسیر انتشار واقعی الزامی است تا گردشکار tarball آمادهشده
|
||||
از اجرای preflight موفق را دوباره استفاده کند
|
||||
- `npm_dist_tag`: tag هدف npm برای مسیر انتشار؛ پیشفرض `beta` است
|
||||
|
||||
`OpenClaw Release Publish` این ورودیهای کنترلشده توسط اپراتور را میپذیرد:
|
||||
|
||||
- `tag`: تگ Release الزامی؛ باید از قبل وجود داشته باشد
|
||||
- `tag`: tag انتشار الزامی؛ باید از قبل وجود داشته باشد
|
||||
- `preflight_run_id`: شناسهی اجرای preflight موفق `OpenClaw NPM Release`؛
|
||||
وقتی `publish_openclaw_npm=true` باشد الزامی است
|
||||
- `npm_dist_tag`: تگ هدف npm برای بستهی OpenClaw
|
||||
- `plugin_publish_scope`: مقدار پیشفرض `all-publishable` است؛ از `selected` فقط
|
||||
برای تعمیر متمرکز استفاده کنید
|
||||
- `plugins`: نامهای بستهی `@openclaw/*` که با کاما جدا شدهاند، وقتی
|
||||
- `npm_dist_tag`: tag هدف npm برای بستهی OpenClaw
|
||||
- `plugin_publish_scope`: پیشفرض `all-publishable` است؛ فقط برای کار repair
|
||||
متمرکز از `selected` استفاده کنید
|
||||
- `plugins`: نامهای بستهی `@openclaw/*` جداشده با کاما وقتی
|
||||
`plugin_publish_scope=selected` باشد
|
||||
- `publish_openclaw_npm`: مقدار پیشفرض `true` است؛ فقط وقتی از workflow بهعنوان
|
||||
هماهنگکنندهی تعمیر فقط Plugin استفاده میکنید آن را `false` قرار دهید
|
||||
- `publish_openclaw_npm`: پیشفرض `true` است؛ فقط وقتی از گردشکار بهعنوان
|
||||
هماهنگکنندهی repair فقط مخصوص plugin استفاده میکنید، آن را `false` بگذارید
|
||||
|
||||
`OpenClaw Release Checks` این ورودیهای کنترلشده توسط اپراتور را میپذیرد:
|
||||
|
||||
- `ref`: شاخه، تگ، یا SHA کامل کامیت برای اعتبارسنجی. بررسیهای دارای secret
|
||||
نیاز دارند کامیت حلشده از یک شاخهی OpenClaw یا
|
||||
تگ Release قابل دسترسی باشد.
|
||||
- `ref`: شاخه، tag، یا SHA کامل کامیت برای اعتبارسنجی. بررسیهای دارای secret
|
||||
نیاز دارند کامیت حلشده از یک شاخهی OpenClaw یا tag انتشار قابل دسترسی باشد.
|
||||
|
||||
قوانین:
|
||||
قواعد:
|
||||
|
||||
- تگهای پایدار و اصلاحی میتوانند روی `beta` یا `latest` منتشر شوند
|
||||
- تگهای prerelease آلفا فقط میتوانند روی `alpha` منتشر شوند
|
||||
- تگهای prerelease بتا فقط میتوانند روی `beta` منتشر شوند
|
||||
- tagهای stable و correction میتوانند روی `beta` یا `latest` منتشر شوند
|
||||
- tagهای prerelease مربوط به Beta فقط میتوانند روی `beta` منتشر شوند
|
||||
- برای `OpenClaw NPM Release`، ورودی SHA کامل کامیت فقط وقتی مجاز است که
|
||||
`preflight_only=true` باشد
|
||||
- `OpenClaw Release Checks` و `Full Release Validation` همیشه
|
||||
فقط اعتبارسنجی هستند
|
||||
- `OpenClaw Release Checks` و `Full Release Validation` همیشه فقط اعتبارسنجی هستند
|
||||
- مسیر انتشار واقعی باید از همان `npm_dist_tag` استفاده کند که در preflight استفاده شده است؛
|
||||
workflow پیش از ادامهی انتشار آن metadata را تأیید میکند
|
||||
گردشکار پیش از ادامهی انتشار، آن metadata را بررسی میکند
|
||||
|
||||
## توالی Release پایدار npm
|
||||
## توالی انتشار stable در npm
|
||||
|
||||
هنگام آمادهسازی یک Release پایدار npm:
|
||||
هنگام بریدن یک انتشار stable در npm:
|
||||
|
||||
1. `OpenClaw NPM Release` را با `preflight_only=true` اجرا کنید
|
||||
- پیش از وجود تگ، میتوانید برای اجرای آزمایشی فقط اعتبارسنجی workflow preflight از SHA کامل کامیت شاخهی فعلی workflow استفاده کنید
|
||||
2. برای جریان معمول بتا-اول `npm_dist_tag=beta` را انتخاب کنید، یا فقط وقتی
|
||||
عمداً انتشار پایدار مستقیم میخواهید `latest` را انتخاب کنید
|
||||
3. وقتی CI معمولی بههمراه پوشش live prompt cache، Docker، QA Lab،
|
||||
Matrix، و Telegram را از یک workflow دستی میخواهید، `Full Release Validation` را روی شاخهی Release، تگ Release، یا SHA کامل کامیت اجرا کنید
|
||||
4. اگر عمداً فقط گراف تست عادی قطعی را نیاز دارید، بهجای آن workflow دستی
|
||||
`CI` را روی ref مربوط به Release اجرا کنید
|
||||
- پیش از وجود tag، میتوانید از SHA کامل کامیت شاخهی گردشکار فعلی برای یک
|
||||
dry run فقط اعتبارسنجی از گردشکار preflight استفاده کنید
|
||||
2. برای جریان معمول beta-first، `npm_dist_tag=beta` را انتخاب کنید، یا فقط وقتی
|
||||
عمدا انتشار stable مستقیم میخواهید، `latest` را انتخاب کنید
|
||||
3. وقتی میخواهید CI معمول بههمراه پوشش live prompt cache، Docker، QA Lab،
|
||||
Matrix، و Telegram را از یک گردشکار دستی داشته باشید، `Full Release Validation`
|
||||
را روی شاخهی انتشار، tag انتشار، یا SHA کامل کامیت اجرا کنید
|
||||
4. اگر عمدا فقط به گراف تست معمول deterministic نیاز دارید، بهجای آن گردشکار
|
||||
دستی `CI` را روی ref انتشار اجرا کنید
|
||||
5. `preflight_run_id` موفق را ذخیره کنید
|
||||
6. `OpenClaw Release Publish` را با همان `tag`، همان `npm_dist_tag`،
|
||||
و `preflight_run_id` ذخیرهشده اجرا کنید؛ این کار پیش از ارتقای بستهی npm مربوط به OpenClaw، Pluginهای خارجیشده را در npm
|
||||
و ClawHub منتشر میکند
|
||||
7. اگر Release روی `beta` فرود آمد، از workflow خصوصی
|
||||
6. `OpenClaw Release Publish` را با همان `tag`، همان `npm_dist_tag`، و
|
||||
`preflight_run_id` ذخیرهشده اجرا کنید؛ این کار پیش از ارتقای بستهی npm
|
||||
مربوط به OpenClaw، pluginهای externalized را در npm و ClawHub منتشر میکند
|
||||
7. اگر انتشار روی `beta` نشست، از گردشکار خصوصی
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
برای ارتقای آن نسخهی پایدار از `beta` به `latest` استفاده کنید
|
||||
8. اگر Release عمداً مستقیماً روی `latest` منتشر شد و `beta`
|
||||
باید فوراً همان ساخت پایدار را دنبال کند، از همان workflow خصوصی
|
||||
برای اشاره دادن هر دو dist-tag به نسخهی پایدار استفاده کنید، یا اجازه دهید همگامسازی خودترمیم زمانبندیشدهی آن بعداً `beta` را جابهجا کند
|
||||
برای ارتقای آن نسخهی stable از `beta` به `latest` استفاده کنید
|
||||
8. اگر انتشار عمدا مستقیم روی `latest` منتشر شد و `beta` باید بلافاصله همان build
|
||||
stable را دنبال کند، از همان گردشکار خصوصی استفاده کنید تا هر دو dist-tag به نسخهی
|
||||
stable اشاره کنند، یا اجازه دهید همگامسازی self-healing زمانبندیشدهی آن بعدا
|
||||
`beta` را جابهجا کند
|
||||
|
||||
تغییر dist-tag به دلایل امنیتی در مخزن خصوصی قرار دارد، چون همچنان
|
||||
به `NPM_TOKEN` نیاز دارد، در حالی که مخزن عمومی انتشار فقط مبتنی بر OIDC را نگه میدارد.
|
||||
تغییر dist-tag به دلایل امنیتی در repo خصوصی قرار دارد، چون هنوز به
|
||||
`NPM_TOKEN` نیاز دارد، در حالی که repo عمومی انتشار فقط مبتنی بر OIDC را نگه میدارد.
|
||||
|
||||
این کار هر دو مسیر انتشار مستقیم و مسیر ارتقای بتا-اول را
|
||||
مستند و برای اپراتور قابل مشاهده نگه میدارد.
|
||||
این کار هم مسیر انتشار مستقیم و هم مسیر ارتقای beta-first را مستندسازیشده و
|
||||
برای اپراتور قابل مشاهده نگه میدارد.
|
||||
|
||||
اگر یک نگهدارنده ناچار شود به احراز هویت محلی npm برگردد، هر دستور 1Password
|
||||
CLI (`op`) را فقط داخل یک نشست اختصاصی tmux اجرا کند. `op` را
|
||||
مستقیماً از shell اصلی agent فراخوانی نکنید؛ نگه داشتن آن داخل tmux باعث میشود promptها،
|
||||
هشدارها و مدیریت OTP قابل مشاهده باشند و از هشدارهای مکرر میزبان جلوگیری شود.
|
||||
اگر یک maintainer مجبور شود به احراز هویت محلی npm fallback کند، هر دستور
|
||||
1Password CLI (`op`) را فقط داخل یک نشست اختصاصی tmux اجرا کنید. `op` را
|
||||
مستقیما از پوستهی اصلی agent فراخوانی نکنید؛ نگهداشتن آن داخل tmux باعث میشود
|
||||
promptها، alertها، و مدیریت OTP قابل مشاهده باشند و از alertهای تکراری میزبان جلوگیری میکند.
|
||||
|
||||
## منابع عمومی
|
||||
## ارجاعهای عمومی
|
||||
|
||||
- [`.github/workflows/full-release-validation.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/full-release-validation.yml)
|
||||
- [`.github/workflows/package-acceptance.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/package-acceptance.yml)
|
||||
@ -572,10 +556,10 @@ CLI (`op`) را فقط داخل یک نشست اختصاصی tmux اجرا کن
|
||||
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
|
||||
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
|
||||
|
||||
نگهدارندگان برای runbook واقعی از مستندات خصوصی Release در
|
||||
Maintainerها از docs خصوصی release در
|
||||
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
|
||||
استفاده میکنند.
|
||||
برای runbook واقعی استفاده میکنند.
|
||||
|
||||
## مرتبط
|
||||
|
||||
- [کانالهای Release](/fa/install/development-channels)
|
||||
- [کانالهای release](/fa/install/development-channels)
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- میخواهید Gateway را از مرورگر مدیریت کنید
|
||||
- میخواهید Gateway را از یک مرورگر اجرا کنید
|
||||
- میخواهید بدون تونلهای SSH به Tailnet دسترسی داشته باشید
|
||||
sidebarTitle: Control UI
|
||||
summary: رابط کاربری کنترل مبتنی بر مرورگر برای Gateway (گفتوگو، گرهها، پیکربندی)
|
||||
summary: رابط کاربری کنترل مبتنی بر مرورگر برای Gateway (گفتگو، گرهها، پیکربندی)
|
||||
title: رابط کاربری کنترل
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T21:01:38Z"
|
||||
generated_at: "2026-05-02T23:39:05Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 88959ccf435b31015039bf28c3043023d99f0b953a1489986ab2d0cbd261771c
|
||||
source_hash: 50bef807915f27406e19f1c6ca7d839a610d79ba79da85d7a78523400cbf9208
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -19,224 +19,226 @@ x-i18n:
|
||||
- پیشفرض: `http://<host>:18789/`
|
||||
- پیشوند اختیاری: `gateway.controlUi.basePath` را تنظیم کنید (مثلاً `/openclaw`)
|
||||
|
||||
این برنامه **مستقیماً با WebSocket Gateway** روی همان پورت ارتباط برقرار میکند.
|
||||
این برنامه **مستقیماً با Gateway WebSocket** روی همان پورت صحبت میکند.
|
||||
|
||||
## باز کردن سریع (محلی)
|
||||
|
||||
اگر Gateway روی همان رایانه در حال اجراست، باز کنید:
|
||||
اگر Gateway روی همان رایانه در حال اجرا است، باز کنید:
|
||||
|
||||
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (یا [http://localhost:18789/](http://localhost:18789/))
|
||||
|
||||
اگر صفحه بارگذاری نشد، ابتدا Gateway را شروع کنید: `openclaw gateway`.
|
||||
|
||||
احراز هویت هنگام دستدهی WebSocket از این مسیرها ارائه میشود:
|
||||
احراز هویت هنگام دستدهی WebSocket از طریق موارد زیر ارائه میشود:
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- سرآیندهای هویت Tailscale Serve وقتی `gateway.auth.allowTailscale: true` است
|
||||
- سرآیندهای هویت پروکسی معتمد وقتی `gateway.auth.mode: "trusted-proxy"` است
|
||||
- سرآیندهای هویت Tailscale Serve وقتی `gateway.auth.allowTailscale: true` باشد
|
||||
- سرآیندهای هویت پروکسی معتمد وقتی `gateway.auth.mode: "trusted-proxy"` باشد
|
||||
|
||||
پنل تنظیمات داشبورد یک توکن را برای نشست فعلی تب مرورگر و URL انتخابشده Gateway نگه میدارد؛ گذرواژهها ذخیره نمیشوند. راهاندازی اولیه معمولاً در اولین اتصال، برای احراز هویت با راز مشترک یک توکن Gateway تولید میکند، اما وقتی `gateway.auth.mode` برابر `"password"` باشد، احراز هویت با گذرواژه هم کار میکند.
|
||||
پنل تنظیمات داشبورد یک توکن را برای جلسه زبانه مرورگر فعلی و URL Gateway انتخابشده نگه میدارد؛ گذرواژهها پایدار ذخیره نمیشوند. راهاندازی اولیه معمولاً در اولین اتصال، برای احراز هویت مبتنی بر راز مشترک یک توکن Gateway تولید میکند، اما احراز هویت با گذرواژه هم وقتی `gateway.auth.mode` برابر `"password"` باشد کار میکند.
|
||||
|
||||
## جفتسازی دستگاه (اولین اتصال)
|
||||
|
||||
وقتی از یک مرورگر یا دستگاه جدید به رابط کاربری کنترل وصل میشوید، Gateway معمولاً به **تأیید یکباره جفتسازی** نیاز دارد. این یک اقدام امنیتی برای جلوگیری از دسترسی غیرمجاز است.
|
||||
وقتی از یک مرورگر یا دستگاه جدید به رابط کاربری کنترل وصل میشوید، Gateway معمولاً به **تأیید جفتسازی یکباره** نیاز دارد. این یک اقدام امنیتی برای جلوگیری از دسترسی غیرمجاز است.
|
||||
|
||||
**آنچه میبینید:** "disconnected (1008): pairing required"
|
||||
**چیزی که میبینید:** "disconnected (1008): pairing required"
|
||||
|
||||
<Steps>
|
||||
<Step title="فهرست کردن درخواستهای در انتظار">
|
||||
<Step title="List pending requests">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="تأیید با شناسه درخواست">
|
||||
<Step title="Approve by request ID">
|
||||
```bash
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
اگر مرورگر جفتسازی را با جزئیات احراز هویت تغییرکرده دوباره امتحان کند (نقش/دامنهها/کلید عمومی)، درخواست در انتظار قبلی جایگزین میشود و یک `requestId` جدید ساخته میشود. پیش از تأیید، دوباره `openclaw devices list` را اجرا کنید.
|
||||
اگر مرورگر با جزئیات احراز هویت تغییرکرده (نقش/دامنهها/کلید عمومی) دوباره برای جفتسازی تلاش کند، درخواست در انتظار قبلی جایگزین میشود و یک `requestId` جدید ساخته میشود. پیش از تأیید، دوباره `openclaw devices list` را اجرا کنید.
|
||||
|
||||
اگر مرورگر از قبل جفت شده باشد و آن را از دسترسی خواندن به دسترسی نوشتن/مدیریت تغییر دهید، این بهعنوان ارتقای تأیید در نظر گرفته میشود، نه اتصال مجدد بیصدا. OpenClaw تأیید قدیمی را فعال نگه میدارد، اتصال مجدد گستردهتر را مسدود میکند، و از شما میخواهد مجموعه دامنههای جدید را صریحاً تأیید کنید.
|
||||
اگر مرورگر از قبل جفت شده باشد و شما آن را از دسترسی خواندن به دسترسی نوشتن/مدیر تغییر دهید، این کار بهعنوان ارتقای تأیید در نظر گرفته میشود، نه اتصال مجدد بیصدا. OpenClaw تأیید قدیمی را فعال نگه میدارد، اتصال مجدد گستردهتر را مسدود میکند، و از شما میخواهد مجموعه دامنه جدید را صراحتاً تأیید کنید.
|
||||
|
||||
پس از تأیید، دستگاه به خاطر سپرده میشود و دیگر به تأیید دوباره نیاز ندارد، مگر اینکه آن را با `openclaw devices revoke --device <id> --role <role>` لغو کنید. برای چرخش و لغو توکن، [CLI دستگاهها](/fa/cli/devices) را ببینید.
|
||||
|
||||
<Note>
|
||||
- اتصالهای مستقیم مرورگر از طریق local loopback (`127.0.0.1` / `localhost`) بهصورت خودکار تأیید میشوند.
|
||||
- وقتی `gateway.auth.allowTailscale: true` باشد، هویت Tailscale تأیید شود، و مرورگر هویت دستگاه خود را ارائه کند، Tailscale Serve میتواند رفتوبرگشت جفتسازی را برای نشستهای اپراتور رابط کاربری کنترل نادیده بگیرد.
|
||||
- اتصالهای مستقیم Tailnet، اتصالهای مرورگر از LAN، و پروفایلهای مرورگر بدون هویت دستگاه همچنان به تأیید صریح نیاز دارند.
|
||||
- اتصالهای مستقیم مرورگر از طریق local loopback (`127.0.0.1` / `localhost`) بهطور خودکار تأیید میشوند.
|
||||
- وقتی `gateway.auth.allowTailscale: true` باشد، هویت Tailscale تأیید شود، و مرورگر هویت دستگاه خود را ارائه کند، Tailscale Serve میتواند مرحله رفتوبرگشت جفتسازی را برای جلسههای اپراتور رابط کاربری کنترل رد کند.
|
||||
- اتصالهای مستقیم Tailnet، اتصالهای مرورگر روی LAN، و پروفایلهای مرورگری بدون هویت دستگاه همچنان به تأیید صریح نیاز دارند.
|
||||
- هر پروفایل مرورگر یک شناسه دستگاه یکتا تولید میکند، بنابراین تغییر مرورگر یا پاک کردن دادههای مرورگر به جفتسازی دوباره نیاز خواهد داشت.
|
||||
|
||||
</Note>
|
||||
|
||||
## هویت شخصی (محلیِ مرورگر)
|
||||
|
||||
رابط کاربری کنترل از یک هویت شخصی برای هر مرورگر پشتیبانی میکند (نام نمایشی و آواتار) که برای نسبتدهی در نشستهای مشترک به پیامهای خروجی متصل میشود. این هویت در فضای ذخیرهسازی مرورگر قرار دارد، به پروفایل فعلی مرورگر محدود است، و با دستگاههای دیگر همگامسازی نمیشود یا در سمت سرور، فراتر از فراداده معمول نویسندگی رونوشت برای پیامهایی که واقعاً میفرستید، ماندگار نمیشود. پاک کردن دادههای سایت یا تغییر مرورگر آن را به حالت خالی بازنشانی میکند.
|
||||
رابط کاربری کنترل از یک هویت شخصی برای هر مرورگر (نام نمایشی و آواتار) پشتیبانی میکند که برای انتساب در جلسههای مشترک به پیامهای خروجی پیوست میشود. این هویت در فضای ذخیرهسازی مرورگر قرار دارد، به پروفایل مرورگر فعلی محدود است، و به دستگاههای دیگر همگامسازی نمیشود یا فراتر از فراداده معمول نویسندگی رونوشت برای پیامهایی که واقعاً ارسال میکنید، در سمت سرور پایدار نمیماند. پاک کردن دادههای سایت یا تغییر مرورگر آن را به حالت خالی بازمیگرداند.
|
||||
|
||||
همین الگوی محلیِ مرورگر برای بازنویسی آواتار دستیار هم اعمال میشود. آواتارهای بارگذاریشده دستیار فقط در مرورگر محلی، هویت حلشده توسط Gateway را میپوشانند و هرگز از مسیر `config.patch` رفتوبرگشت نمیکنند. فیلد پیکربندی مشترک `ui.assistant.avatar` همچنان برای کلاینتهای غیر UI که این فیلد را مستقیماً مینویسند در دسترس است (مانند Gatewayهای اسکریپتی یا داشبوردهای سفارشی).
|
||||
همین الگوی محلیِ مرورگر برای جایگزینی آواتار دستیار هم اعمال میشود. آواتارهای دستیار بارگذاریشده فقط در مرورگر محلی روی هویت حلشده توسط Gateway قرار میگیرند و هرگز از طریق `config.patch` رفتوبرگشت نمیکنند. فیلد پیکربندی مشترک `ui.assistant.avatar` همچنان برای کلاینتهای غیر UI که مستقیماً این فیلد را مینویسند در دسترس است (مانند Gatewayهای اسکریپتی یا داشبوردهای سفارشی).
|
||||
|
||||
## نقطه پایانی پیکربندی زمان اجرا
|
||||
|
||||
رابط کاربری کنترل تنظیمات زمان اجرای خود را از `/__openclaw/control-ui-config.json` دریافت میکند. آن نقطه پایانی با همان احراز هویت Gateway که برای بقیه سطح HTTP استفاده میشود محافظت میشود: مرورگرهای احراز هویتنشده نمیتوانند آن را دریافت کنند، و دریافت موفق به یک توکن/گذرواژه معتبر از قبل برای Gateway، هویت Tailscale Serve، یا هویت پروکسی معتمد نیاز دارد.
|
||||
رابط کاربری کنترل تنظیمات زمان اجرای خود را از `/__openclaw/control-ui-config.json` دریافت میکند. این نقطه پایانی با همان احراز هویت Gateway که برای بقیه سطح HTTP استفاده میشود محافظت میشود: مرورگرهای احراز هویتنشده نمیتوانند آن را دریافت کنند، و دریافت موفق به یک توکن/گذرواژه Gateway از قبل معتبر، هویت Tailscale Serve، یا هویت پروکسی معتمد نیاز دارد.
|
||||
|
||||
## پشتیبانی زبان
|
||||
|
||||
رابط کاربری کنترل میتواند هنگام اولین بارگذاری، بر اساس زبان مرورگر شما خود را بومیسازی کند. برای بازنویسی آن در زمان بعدی، **نمای کلی -> دسترسی Gateway -> زبان** را باز کنید. انتخابگر زبان در کارت دسترسی Gateway قرار دارد، نه زیر ظاهر.
|
||||
رابط کاربری کنترل میتواند در اولین بارگذاری، بر اساس زبان مرورگر شما خود را بومیسازی کند. برای بازنویسی آن در آینده، **Overview -> Gateway Access -> Language** را باز کنید. انتخابگر زبان در کارت Gateway Access قرار دارد، نه زیر Appearance.
|
||||
|
||||
- زبانهای پشتیبانیشده: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- ترجمههای غیرانگلیسی در مرورگر بهصورت تنبل بارگذاری میشوند.
|
||||
- زبان انتخابشده در فضای ذخیرهسازی مرورگر ذخیره میشود و در بازدیدهای آینده دوباره استفاده میشود.
|
||||
- کلیدهای ترجمه جاافتاده به انگلیسی بازمیگردند.
|
||||
- کلیدهای ترجمه ازدسترفته به انگلیسی برمیگردند.
|
||||
|
||||
ترجمههای مستندات برای همان مجموعه زبانهای غیرانگلیسی تولید میشوند، اما انتخابگر زبان داخلی سایت مستندات Mintlify به کدهای زبانیای محدود است که Mintlify میپذیرد. مستندات تایلندی (`th`) و فارسی (`fa`) همچنان در مخزن انتشار تولید میشوند؛ ممکن است تا زمانی که Mintlify از آن کدها پشتیبانی کند در آن انتخابگر ظاهر نشوند.
|
||||
ترجمههای مستندات برای همان مجموعه زبانهای غیرانگلیسی تولید میشوند، اما انتخابگر زبان داخلی سایت مستندات در Mintlify به کدهای زبانی محدود است که Mintlify میپذیرد. مستندات تایلندی (`th`) و فارسی (`fa`) همچنان در مخزن انتشار تولید میشوند؛ ممکن است تا زمانی که Mintlify از این کدها پشتیبانی نکند، در آن انتخابگر ظاهر نشوند.
|
||||
|
||||
## قالبهای ظاهری
|
||||
## پوستههای ظاهری
|
||||
|
||||
پنل ظاهر قالبهای داخلی Claw، Knot و Dash، بهعلاوه یک جایگاه واردسازی tweakcn محلیِ مرورگر را نگه میدارد. برای وارد کردن قالب، [قالبهای tweakcn](https://tweakcn.com/themes) را باز کنید، یک قالب انتخاب یا ایجاد کنید، روی **اشتراکگذاری** کلیک کنید، و پیوند کپیشده قالب را در ظاهر جایگذاری کنید. واردکننده همچنین URLهای رجیستری `https://tweakcn.com/r/themes/<id>`، URLهای ویرایشگر مانند `https://tweakcn.com/editor/theme?theme=amethyst-haze`، مسیرهای نسبی `/themes/<id>`، شناسههای خام قالب، و نامهای قالب پیشفرض مانند `amethyst-haze` را میپذیرد.
|
||||
پنل Appearance پوستههای داخلی Claw، Knot و Dash را بههمراه یک جایگاه واردسازی tweakcn محلیِ مرورگر نگه میدارد. برای وارد کردن یک پوسته، [پوستههای tweakcn](https://tweakcn.com/themes) را باز کنید، یک پوسته را انتخاب یا ایجاد کنید، روی **Share** کلیک کنید، و پیوند پوسته کپیشده را در Appearance جایگذاری کنید. واردکننده همچنین URLهای رجیستری `https://tweakcn.com/r/themes/<id>`، URLهای ویرایشگر مانند `https://tweakcn.com/editor/theme?theme=amethyst-haze`، مسیرهای نسبی `/themes/<id>`، شناسههای خام پوسته، و نامهای پوسته پیشفرض مانند `amethyst-haze` را میپذیرد.
|
||||
|
||||
قالبهای واردشده فقط در پروفایل فعلی مرورگر ذخیره میشوند. آنها در پیکربندی Gateway نوشته نمیشوند و بین دستگاهها همگامسازی نمیشوند. جایگزین کردن قالب واردشده همان یک جایگاه محلی را بهروزرسانی میکند؛ پاک کردن آن، اگر قالب واردشده انتخاب شده باشد، قالب فعال را به Claw برمیگرداند.
|
||||
پوستههای واردشده فقط در پروفایل مرورگر فعلی ذخیره میشوند. آنها در پیکربندی Gateway نوشته نمیشوند و میان دستگاهها همگامسازی نمیشوند. جایگزین کردن پوسته واردشده همان یک جایگاه محلی را بهروزرسانی میکند؛ پاک کردن آن، اگر پوسته واردشده انتخاب شده باشد، پوسته فعال را به Claw برمیگرداند.
|
||||
|
||||
## کارهایی که میتواند انجام دهد (امروز)
|
||||
## اکنون چه کارهایی میتواند انجام دهد
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="گفتوگو و مکالمه">
|
||||
- گفتوگو با مدل از طریق Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- مکالمه از طریق نشستهای بلادرنگ مرورگر. OpenAI از WebRTC مستقیم استفاده میکند، Google Live از یک توکن محدود یکبارمصرف مرورگر روی WebSocket استفاده میکند، و Pluginهای صدای بلادرنگِ فقطپشتیبان از انتقال رله Gateway استفاده میکنند. رله، اعتبارنامههای ارائهدهنده را روی Gateway نگه میدارد، در حالی که مرورگر PCM میکروفون را از طریق RPCهای `talk.realtime.relay*` پخش میکند و فراخوانیهای ابزار `openclaw_agent_consult` را از طریق `chat.send` برای مدل بزرگتر پیکربندیشده OpenClaw برمیگرداند.
|
||||
- پخش جریانی فراخوانیهای ابزار + کارتهای خروجی زنده ابزار در گفتوگو (رویدادهای عامل).
|
||||
<Accordion title="Chat and Talk">
|
||||
- گفتگو با مدل از طریق Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- دیکته کردن در آهنگساز گفتگو با STT سمت سرور (`chat.transcribeAudio`). مرورگر یک کلیپ کوتاه میکروفون ضبط میکند و آن را به Gateway میفرستد؛ Gateway خط لوله رونویسی پیکربندیشده `tools.media.audio` را اجرا میکند و متن پیشنویس را بدون افشای اعتبارنامههای ارائهدهنده به مرورگر برمیگرداند.
|
||||
- صحبت کردن از طریق جلسههای بلادرنگ مرورگر. OpenAI از WebRTC مستقیم استفاده میکند، Google Live از یک توکن مرورگر محدود و یکبارمصرف روی WebSocket استفاده میکند، و Pluginهای صدای بلادرنگ فقط-بکاند از انتقال رله Gateway استفاده میکنند. رله اعتبارنامههای ارائهدهنده را روی Gateway نگه میدارد، در حالی که مرورگر PCM میکروفون را از طریق RPCهای `talk.realtime.relay*` جریان میدهد و فراخوانیهای ابزار `openclaw_agent_consult` را از طریق `chat.send` به مدل بزرگتر پیکربندیشده OpenClaw برمیگرداند.
|
||||
- جریاندهی فراخوانیهای ابزار + کارتهای خروجی زنده ابزار در گفتگو (رویدادهای عامل).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="کانالها، نمونهها، نشستها، رؤیاها">
|
||||
<Accordion title="Channels, instances, sessions, dreams">
|
||||
- کانالها: وضعیت کانالهای داخلی بهعلاوه کانالهای Plugin بستهبندیشده/خارجی، ورود با QR، و پیکربندی برای هر کانال (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- نمونهها: فهرست حضور + تازهسازی (`system-presence`).
|
||||
- نشستها: فهرست + بازنویسیهای مدل/تفکر/سریع/پرحرف/ردیابی/استدلال برای هر نشست (`sessions.list`, `sessions.patch`).
|
||||
- رؤیاها: وضعیت Dreaming، کلید فعال/غیرفعال، و خواننده دفترچه رؤیا (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
- جلسهها: فهرست + بازنویسیهای مدل/تفکر/سریع/پرحرف/ردیابی/استدلال برای هر جلسه (`sessions.list`, `sessions.patch`).
|
||||
- رویاها: وضعیت Dreaming، کلید فعال/غیرفعالسازی، و خواننده دفترچه رویا (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron، skills، nodes، تأییدهای exec">
|
||||
- کارهای Cron: فهرست/افزودن/ویرایش/اجرا/فعالسازی/غیرفعالسازی + تاریخچه اجرا (`cron.*`).
|
||||
- Skills: وضعیت، فعال/غیرفعال، نصب، بهروزرسانیهای کلید API (`skills.*`).
|
||||
- Nodes: فهرست + قابلیتها (`node.list`).
|
||||
- تأییدهای exec: ویرایش فهرستهای مجاز Gateway یا Node + خطمشی پرسش برای `exec host=gateway/node` (`exec.approvals.*`).
|
||||
<Accordion title="Cron, skills, nodes, exec approvals">
|
||||
- کارهای Cron: فهرست/افزودن/ویرایش/اجرا/فعال/غیرفعال + تاریخچه اجرا (`cron.*`).
|
||||
- Skills: وضعیت، فعال/غیرفعالسازی، نصب، بهروزرسانی کلید API (`skills.*`).
|
||||
- Nodeها: فهرست + قابلیتها (`node.list`).
|
||||
- تأییدهای exec: ویرایش allowlistهای Gateway یا Node + سیاست پرسش برای `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="پیکربندی">
|
||||
<Accordion title="Config">
|
||||
- مشاهده/ویرایش `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- اعمال + راهاندازی مجدد همراه با اعتبارسنجی (`config.apply`) و بیدار کردن آخرین نشست فعال.
|
||||
- نوشتنها شامل یک محافظ هش پایه هستند تا از بازنویسی و از بین بردن ویرایشهای همزمان جلوگیری شود.
|
||||
- نوشتنها (`config.set`/`config.apply`/`config.patch`) پیش از اجرا، حل SecretRef فعال را برای ارجاعهای موجود در بار پیکربندی ارسالشده پیشپرواز میکنند؛ ارجاعهای فعالِ ارسالشده و حلنشده پیش از نوشتن رد میشوند.
|
||||
- طرحواره + رندر فرم (`config.schema` / `config.schema.lookup`، شامل `title` / `description` فیلد، راهنماییهای UI منطبق، خلاصههای فرزند بلافصل، فراداده مستندات روی گرههای آبجکت/وایلدکارت/آرایه/ترکیب تودرتو، بهعلاوه طرحوارههای Plugin + کانال در صورت وجود)؛ ویرایشگر JSON خام فقط وقتی در دسترس است که عکس فوری رفتوبرگشت خام ایمن داشته باشد.
|
||||
- اگر یک عکس فوری نتواند متن خام را بهطور ایمن رفتوبرگشت کند، رابط کاربری کنترل حالت فرم را اجباری میکند و حالت خام را برای آن عکس فوری غیرفعال میکند.
|
||||
- «بازنشانی به ذخیرهشده» در ویرایشگر JSON خام، بهجای رندر دوباره یک عکس فوری تختشده، شکل خامِ نوشتهشده را حفظ میکند (قالببندی، نظرها، چیدمان `$include`)، بنابراین وقتی عکس فوری بتواند بهطور ایمن رفتوبرگشت کند، ویرایشهای خارجی پس از بازنشانی باقی میمانند.
|
||||
- مقدارهای آبجکت SecretRef ساختاریافته در ورودیهای متنی فرم بهصورت فقطخواندنی رندر میشوند تا از خرابی تصادفی آبجکت به رشته جلوگیری شود.
|
||||
- اعمال + راهاندازی مجدد همراه با اعتبارسنجی (`config.apply`) و بیدار کردن آخرین جلسه فعال.
|
||||
- نوشتنها شامل یک محافظ base-hash برای جلوگیری از بازنویسی و از بین بردن ویرایشهای همزمان هستند.
|
||||
- نوشتنها (`config.set`/`config.apply`/`config.patch`) پیش از اجرا، حل SecretRefهای فعال را برای ارجاعهای موجود در بار پیکربندی ارسالشده بررسی میکنند؛ ارجاعهای فعالِ ارسالشده که حل نشده باشند پیش از نوشتن رد میشوند.
|
||||
- طرحواره + رندر فرم (`config.schema` / `config.schema.lookup`، شامل `title` / `description` فیلد، راهنماییهای UI منطبق، خلاصههای فرزند مستقیم، فراداده مستندات روی گرههای شیء تودرتو/وایلدکارد/آرایه/ترکیب، بهعلاوه طرحوارههای Plugin + کانال در صورت وجود)؛ ویرایشگر Raw JSON فقط وقتی در دسترس است که snapshot رفتوبرگشت خام امن داشته باشد.
|
||||
- اگر یک snapshot نتواند متن خام را بهطور امن رفتوبرگشت کند، رابط کاربری کنترل حالت Form را اجباری میکند و حالت Raw را برای آن snapshot غیرفعال میکند.
|
||||
- در ویرایشگر Raw JSON، "Reset to saved" شکل خام نوشتهشده (قالببندی، توضیحها، چیدمان `$include`) را بهجای رندر دوباره یک snapshot تختشده حفظ میکند، بنابراین وقتی snapshot بتواند بهطور امن رفتوبرگشت کند، ویرایشهای خارجی پس از بازنشانی باقی میمانند.
|
||||
- مقدارهای شیء ساختاریافته SecretRef در ورودیهای متنی فرم فقطخواندنی نمایش داده میشوند تا از خراب شدن تصادفی شیء به رشته جلوگیری شود.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="اشکالزدایی، گزارشها، بهروزرسانی">
|
||||
- اشکالزدایی: عکسهای فوری وضعیت/سلامت/مدلها + گزارش رویداد + فراخوانیهای دستی RPC (`status`, `health`, `models.list`).
|
||||
- گزارشها: دنبال کردن زنده گزارشهای فایل Gateway با فیلتر/صدور (`logs.tail`).
|
||||
- بهروزرسانی: اجرای بهروزرسانی بسته/گیت + راهاندازی مجدد (`update.run`) همراه با گزارش راهاندازی مجدد، سپس نظرسنجی `update.status` پس از اتصال مجدد برای تأیید نسخه Gateway در حال اجرا.
|
||||
<Accordion title="Debug, logs, update">
|
||||
- اشکالزدایی: snapshotهای وضعیت/سلامت/مدلها + گزارش رویداد + فراخوانیهای دستی RPC (`status`, `health`, `models.list`).
|
||||
- گزارشها: دنبالکردن زنده گزارشهای فایلی Gateway با فیلتر/خروجیگیری (`logs.tail`).
|
||||
- بهروزرسانی: اجرای بهروزرسانی بسته/git + راهاندازی مجدد (`update.run`) همراه با گزارش راهاندازی مجدد، سپس نظرسنجی `update.status` پس از اتصال مجدد برای تأیید نسخه Gateway در حال اجرا.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="نکتههای پنل کارهای Cron">
|
||||
- برای کارهای ایزوله، تحویل بهصورت پیشفرض روی اعلام خلاصه است. اگر اجراهای فقطداخلی میخواهید، میتوانید آن را به هیچ تغییر دهید.
|
||||
- فیلدهای کانال/هدف وقتی اعلام انتخاب شده باشد ظاهر میشوند.
|
||||
- حالت Webhook از `delivery.mode = "webhook"` استفاده میکند و `delivery.to` روی یک URL Webhook معتبر HTTP(S) تنظیم میشود.
|
||||
- برای کارهای نشست اصلی، حالتهای تحویل Webhook و هیچ در دسترس هستند.
|
||||
- کنترلهای ویرایش پیشرفته شامل حذف پس از اجرا، پاک کردن بازنویسی عامل، گزینههای دقیق/پراکنده Cron، بازنویسیهای مدل/تفکر عامل، و کلیدهای تحویل با بهترین تلاش هستند.
|
||||
- اعتبارسنجی فرم بهصورت درونخطی با خطاهای سطح فیلد انجام میشود؛ مقدارهای نامعتبر تا زمان اصلاح، دکمه ذخیره را غیرفعال میکنند.
|
||||
<Accordion title="Cron jobs panel notes">
|
||||
- برای کارهای ایزوله، تحویل بهطور پیشفرض اعلام خلاصه است. اگر اجراهای فقط داخلی میخواهید، میتوانید آن را به هیچکدام تغییر دهید.
|
||||
- وقتی اعلام انتخاب شده باشد، فیلدهای کانال/هدف ظاهر میشوند.
|
||||
- حالت Webhook از `delivery.mode = "webhook"` استفاده میکند و `delivery.to` روی یک URL معتبر Webhook از نوع HTTP(S) تنظیم میشود.
|
||||
- برای کارهای جلسه اصلی، حالتهای تحویل Webhook و هیچکدام در دسترس هستند.
|
||||
- کنترلهای ویرایش پیشرفته شامل حذف پس از اجرا، پاک کردن بازنویسی عامل، گزینههای دقیق/پلکانی Cron، بازنویسیهای مدل/تفکر عامل، و کلیدهای تحویل best-effort هستند.
|
||||
- اعتبارسنجی فرم بهصورت درونخطی و با خطاهای سطح فیلد است؛ مقدارهای نامعتبر تا زمان اصلاح، دکمه ذخیره را غیرفعال میکنند.
|
||||
- برای ارسال یک توکن bearer اختصاصی، `cron.webhookToken` را تنظیم کنید؛ اگر حذف شود Webhook بدون سرآیند احراز هویت ارسال میشود.
|
||||
- مسیر جایگزین منسوخ: کارهای قدیمی ذخیرهشده با `notify: true` همچنان میتوانند تا زمان مهاجرت از `cron.webhook` استفاده کنند.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## رفتار گفتوگو
|
||||
## رفتار گفتگو
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="معناشناسی ارسال و تاریخچه">
|
||||
- `chat.send` **غیرمسدودکننده** است: بلافاصله با `{ runId, status: "started" }` تایید میکند و پاسخ از طریق رویدادهای `chat` جریان مییابد.
|
||||
- بارگذاریهای چت تصویرها را بههمراه فایلهای غیر ویدئویی میپذیرند. تصویرها مسیر تصویر بومی را نگه میدارند؛ فایلهای دیگر بهصورت رسانهٔ مدیریتشده ذخیره میشوند و در تاریخچه بهصورت پیوندهای پیوست نمایش داده میشوند.
|
||||
- `chat.send` **غیرمسدودکننده** است: بلافاصله با `{ runId, status: "started" }` تأیید میکند و پاسخ از طریق رویدادهای `chat` جریان مییابد.
|
||||
- `chat.transcribeAudio` یک کمککننده دیکته یکباره برای پیشنویسهای Chat است. صدای base64 ضبطشده در مرورگر را میپذیرد، بارگذاریها را زیر حد فریم WebSocket در Gateway نگه میدارد، یک فایل محلی موقت مینویسد، رونویسی صوتیِ درک رسانه را با پیکربندی فعال Gateway اجرا میکند، `{ text, provider, model }` را برمیگرداند، و فایل موقت را حذف میکند. اجرای agent ایجاد نمیکند و از Talk بیدرنگ جدا است.
|
||||
- بارگذاریهای Chat تصویرها و فایلهای غیر ویدیویی را میپذیرند. تصویرها مسیر تصویر بومی را نگه میدارند؛ فایلهای دیگر بهصورت رسانه مدیریتشده ذخیره میشوند و در تاریخچه بهعنوان پیوندهای پیوست نمایش داده میشوند.
|
||||
- ارسال دوباره با همان `idempotencyKey` هنگام اجرا `{ status: "in_flight" }` و پس از تکمیل `{ status: "ok" }` را برمیگرداند.
|
||||
- پاسخهای `chat.history` برای ایمنی UI از نظر اندازه محدود هستند. وقتی ورودیهای رونوشت بیش از حد بزرگ باشند، Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، بلوکهای فرادادهٔ سنگین را حذف کند، و پیامهای بیشازحد بزرگ را با یک جایگزین (`[chat.history omitted: message too large]`) جایگزین کند.
|
||||
- تصویرهای دستیار/تولیدشده بهصورت ارجاعهای رسانهٔ مدیریتشده پایدار میشوند و دوباره از طریق URLهای رسانهای احرازهویتشدهٔ Gateway ارائه میشوند، بنابراین بارگذاریهای دوباره به باقی ماندن محمولههای تصویر base64 خام در پاسخ تاریخچهٔ چت وابسته نیستند.
|
||||
- `chat.history` همچنین برچسبهای دستور درونخطیِ فقط نمایشی را از متن قابلمشاهدهٔ دستیار حذف میکند (برای مثال `[[reply_to_*]]` و `[[audio_as_voice]]`)، محمولههای XML فراخوانی ابزارِ متن ساده (از جمله `<tool_call>...</tool_call>`، `<function_call>...</function_call>`، `<tool_calls>...</tool_calls>`، `<function_calls>...</function_calls>`، و بلوکهای کوتاهشدهٔ فراخوانی ابزار)، و توکنهای کنترلی مدل ASCII/تمامعرض نشتکرده را حذف میکند، و ورودیهای دستیار را که کل متن قابلمشاهدهشان فقط توکن سکوت دقیق `NO_REPLY` / `no_reply` است حذف میکند.
|
||||
- در طول یک ارسال فعال و تازهسازی نهایی تاریخچه، نمای چت پیامهای خوشبینانهٔ محلی کاربر/دستیار را در صورت بازگرداندن موقت یک عکس فوری قدیمیتر توسط `chat.history` قابلمشاهده نگه میدارد؛ پس از همگام شدن تاریخچهٔ Gateway، رونوشت مرجع آن پیامهای محلی را جایگزین میکند.
|
||||
- `chat.inject` یک یادداشت دستیار را به رونوشت نشست اضافه میکند و یک رویداد `chat` را برای بهروزرسانیهای فقط UI پخش میکند (بدون اجرای عامل، بدون تحویل کانال).
|
||||
- انتخابگرهای مدل و تفکر در سربرگ چت، نشست فعال را بلافاصله از طریق `sessions.patch` وصله میکنند؛ آنها بازنویسیهای پایدار نشست هستند، نه گزینههای ارسال فقط برای یک نوبت.
|
||||
- تایپ کردن `/new` در Control UI همان نشست داشبورد تازهٔ New Chat را ایجاد میکند و به آن جابهجا میشود. تایپ کردن `/reset` بازنشانی صریح درجا برای نشست فعلی در Gateway را نگه میدارد.
|
||||
- انتخابگر مدل چت نمای مدل پیکربندیشدهٔ Gateway را درخواست میکند. اگر `agents.defaults.models` وجود داشته باشد، آن فهرست مجاز انتخابگر را هدایت میکند. در غیر این صورت، انتخابگر ورودیهای صریح `models.providers.*.models` بهعلاوهٔ ارائهدهندههایی با احراز هویت قابلاستفاده را نشان میدهد. کاتالوگ کامل از طریق RPC اشکالزدایی `models.list` با `view: "all"` در دسترس میماند.
|
||||
- وقتی گزارشهای تازهٔ مصرف نشست Gateway فشار بالای زمینه را نشان دهند، ناحیهٔ آهنگساز چت یک اعلان زمینه و، در سطوح Compaction توصیهشده، یک دکمهٔ فشرده نشان میدهد که مسیر عادی Compaction نشست را اجرا میکند. عکسهای فوری توکن کهنه تا زمانی که Gateway دوباره مصرف تازه را گزارش کند پنهان میشوند.
|
||||
- پاسخهای `chat.history` برای ایمنی UI از نظر اندازه محدود میشوند. وقتی ورودیهای رونوشت بیش از حد بزرگ باشند، Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، بلوکهای سنگین فراداده را حذف کند، و پیامهای بیشازحد بزرگ را با یک جاینگهدار (`[chat.history omitted: message too large]`) جایگزین کند.
|
||||
- تصویرهای assistant/تولیدشده بهعنوان ارجاعهای رسانه مدیریتشده پایدار میشوند و دوباره از طریق URLهای رسانه احرازهویتشده Gateway ارائه میشوند، بنابراین بارگذاریهای مجدد به باقی ماندن بارهای تصویر base64 خام در پاسخ تاریخچه chat وابسته نیستند.
|
||||
- `chat.history` همچنین برچسبهای دستورالعمل درونخطیِ فقط نمایشی را از متن قابلمشاهده assistant حذف میکند (برای مثال `[[reply_to_*]]` و `[[audio_as_voice]]`)، بارهای XML فراخوانی ابزار بهصورت متن ساده (از جمله `<tool_call>...</tool_call>`، `<function_call>...</function_call>`، `<tool_calls>...</tool_calls>`، `<function_calls>...</function_calls>`، و بلوکهای کوتاهشده فراخوانی ابزار)، و توکنهای کنترل مدل ASCII/تمامعرض نشتکرده را حذف میکند، و ورودیهای assistant را که کل متن قابلمشاهدهشان فقط توکن ساکت دقیق `NO_REPLY` / `no_reply` است، کنار میگذارد.
|
||||
- در طول یک ارسال فعال و تازهسازی نهایی تاریخچه، اگر `chat.history` برای مدت کوتاهی یک snapshot قدیمیتر برگرداند، نمای chat پیامهای خوشبینانه محلی user/assistant را قابلمشاهده نگه میدارد؛ وقتی تاریخچه Gateway بهروز شد، رونوشت رسمی جایگزین آن پیامهای محلی میشود.
|
||||
- `chat.inject` یک یادداشت assistant را به رونوشت نشست اضافه میکند و یک رویداد `chat` را برای بهروزرسانیهای فقط UI پخش میکند (بدون اجرای agent، بدون تحویل کانال).
|
||||
- انتخابگرهای مدل و thinking در سرآیند chat، نشست فعال را بلافاصله از طریق `sessions.patch` وصله میکنند؛ آنها بازنویسیهای پایدار نشست هستند، نه گزینههای ارسال فقط برای یک نوبت.
|
||||
- تایپ `/new` در Control UI همان نشست تازه داشبورد را مثل New Chat ایجاد میکند و به آن جابهجا میشود. تایپ `/reset` بازنشانی درجا و صریح Gateway را برای نشست فعلی نگه میدارد.
|
||||
- انتخابگر مدل chat نمای مدل پیکربندیشده Gateway را درخواست میکند. اگر `agents.defaults.models` وجود داشته باشد، همان allowlist انتخابگر را هدایت میکند. در غیر این صورت، انتخابگر ورودیهای صریح `models.providers.*.models` بهاضافه ارائهدهندگانی با auth قابلاستفاده را نشان میدهد. کاتالوگ کامل از طریق RPC اشکالزدایی `models.list` با `view: "all"` همچنان در دسترس میماند.
|
||||
- وقتی گزارشهای تازه مصرف نشست Gateway فشار زمینه بالایی را نشان دهند، ناحیه نگارش chat یک اعلان زمینه نشان میدهد و، در سطحهای Compaction توصیهشده، دکمهای فشرده که مسیر عادی Compaction نشست را اجرا میکند. snapshotهای توکن قدیمی تا وقتی Gateway دوباره مصرف تازه را گزارش کند پنهان میشوند.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="حالت گفتوگو (بیدرنگ مرورگر)">
|
||||
حالت گفتوگو از یک ارائهدهندهٔ صدای بیدرنگ ثبتشده استفاده میکند. OpenAI را با `talk.provider: "openai"` بههمراه `talk.providers.openai.apiKey` پیکربندی کنید، یا Google را با `talk.provider: "google"` بههمراه `talk.providers.google.apiKey` پیکربندی کنید؛ پیکربندی ارائهدهندهٔ بیدرنگ Voice Call همچنان میتواند بهعنوان پشتیبان دوباره استفاده شود. مرورگر هرگز کلید API استاندارد ارائهدهنده را دریافت نمیکند. OpenAI یک محرمانهٔ موقت Realtime client برای WebRTC دریافت میکند. Google Live یک توکن احراز هویت Live API محدود و یکبارمصرف برای نشست WebSocket مرورگر دریافت میکند، همراه با دستورالعملها و اعلانهای ابزار که توسط Gateway در توکن قفل شدهاند. ارائهدهندههایی که فقط یک پل بیدرنگ سمت پشتیبان ارائه میکنند از مسیر انتقال رلهٔ Gateway عبور میکنند، بنابراین اعتبارنامهها و سوکتهای فروشنده در سمت سرور میمانند در حالی که صدای مرورگر از طریق RPCهای احرازهویتشدهٔ Gateway جابهجا میشود. اعلان نشست Realtime توسط Gateway ساخته میشود؛ `talk.realtime.session` بازنویسی دستورالعمل ارائهشده توسط فراخواننده را نمیپذیرد.
|
||||
<Accordion title="حالت Talk (بیدرنگ مرورگر)">
|
||||
حالت Talk از یک ارائهدهنده صدای بیدرنگ ثبتشده استفاده میکند. OpenAI را با `talk.provider: "openai"` بهاضافه `talk.providers.openai.apiKey` پیکربندی کنید، یا Google را با `talk.provider: "google"` بهاضافه `talk.providers.google.apiKey` پیکربندی کنید؛ پیکربندی ارائهدهنده بیدرنگ Voice Call همچنان میتواند بهعنوان جایگزین استفاده شود. مرورگر هرگز کلید API ارائهدهنده استاندارد دریافت نمیکند. OpenAI یک secret موقت مشتری Realtime برای WebRTC دریافت میکند. Google Live یک توکن auth محدود و یکبارمصرف Live API برای نشست WebSocket مرورگر دریافت میکند، در حالی که دستورالعملها و اعلانهای ابزار توسط Gateway در توکن قفل شدهاند. ارائهدهندگانی که فقط یک پل بیدرنگ backend ارائه میکنند از طریق حملونقل relay در Gateway اجرا میشوند، بنابراین اعتبارنامهها و سوکتهای فروشنده سمت سرور میمانند و صدای مرورگر از طریق RPCهای احرازهویتشده Gateway جابهجا میشود. اعلان نشست Realtime توسط Gateway مونتاژ میشود؛ `talk.realtime.session` بازنویسیهای دستورالعمل ارائهشده از سوی فراخواننده را نمیپذیرد.
|
||||
|
||||
در آهنگساز Chat، کنترل Talk دکمهٔ موجها کنار دکمهٔ دیکتهٔ میکروفون است. وقتی Talk شروع میشود، ردیف وضعیت آهنگساز ابتدا `Connecting Talk...`، سپس هنگام اتصال صدا `Talk live`، یا هنگام مشورت یک فراخوانی ابزار بیدرنگ با مدل بزرگتر پیکربندیشده از طریق `chat.send` مقدار `Asking OpenClaw...` را نشان میدهد.
|
||||
در نگارنده Chat، کنترل Talk دکمه موجها کنار دکمه دیکته میکروفون است. وقتی Talk شروع میشود، ردیف وضعیت نگارنده ابتدا `Connecting Talk...` را نشان میدهد، سپس هنگام اتصال صدا `Talk live`، یا وقتی یک فراخوانی ابزار بیدرنگ در حال مشورت با مدل بزرگتر پیکربندیشده از طریق `chat.send` است `Asking OpenClaw...` را نشان میدهد.
|
||||
|
||||
دودآزمایی زندهٔ نگهدارنده: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` تبادل SDP مرورگر WebRTC در OpenAI، راهاندازی WebSocket مرورگر با توکن محدود Google Live، و آداپتور مرورگر رلهٔ Gateway با رسانهٔ میکروفون جعلی را راستیآزمایی میکند. این فرمان فقط وضعیت ارائهدهنده را چاپ میکند و محرمانهها را ثبت نمیکند.
|
||||
smoke زنده نگهدارنده: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` تبادل SDP مرورگر WebRTC در OpenAI، راهاندازی WebSocket مرورگر با توکن محدود Google Live، و آداپتور مرورگر relay در Gateway را با رسانه میکروفون ساختگی بررسی میکند. این فرمان فقط وضعیت ارائهدهنده را چاپ میکند و secretها را ثبت نمیکند.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="توقف و لغو">
|
||||
- روی **توقف** کلیک کنید (`chat.abort` را فراخوانی میکند).
|
||||
- تا زمانی که یک اجرا فعال است، پیگیریهای عادی در صف قرار میگیرند. روی **هدایت** در یک پیام صفشده کلیک کنید تا آن پیگیری به نوبت در حال اجرا تزریق شود.
|
||||
- وقتی یک اجرا فعال است، پیگیریهای عادی در صف قرار میگیرند. روی **هدایت** در یک پیام صفشده کلیک کنید تا آن پیگیری به نوبت در حال اجرا تزریق شود.
|
||||
- برای لغو خارج از باند، `/stop` را تایپ کنید (یا عبارتهای لغو مستقل مانند `stop`، `stop action`، `stop run`، `stop openclaw`، `please stop`).
|
||||
- `chat.abort` از `{ sessionKey }` (بدون `runId`) برای لغو همهٔ اجراهای فعال آن نشست پشتیبانی میکند.
|
||||
- `chat.abort` از `{ sessionKey }` (بدون `runId`) برای لغو همه اجراهای فعال آن نشست پشتیبانی میکند.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="نگهداری بخش ناقص پس از لغو">
|
||||
- وقتی یک اجرا لغو میشود، متن ناقص دستیار همچنان میتواند در UI نشان داده شود.
|
||||
- Gateway وقتی خروجی بافرشده وجود داشته باشد متن ناقص لغوشدهٔ دستیار را در تاریخچهٔ رونوشت پایدار میکند.
|
||||
- ورودیهای پایدارشده شامل فرادادهٔ لغو هستند تا مصرفکنندگان رونوشت بتوانند بخشهای ناقص لغوشده را از خروجی تکمیل عادی تشخیص دهند.
|
||||
<Accordion title="نگهداری بخش ناقص لغوشده">
|
||||
- وقتی یک اجرا لغو میشود، متن ناقص assistant همچنان میتواند در UI نمایش داده شود.
|
||||
- Gateway متن ناقص assistant لغوشده را وقتی خروجی بافرشده وجود داشته باشد در تاریخچه رونوشت پایدار میکند.
|
||||
- ورودیهای پایدارشده شامل فراداده لغو هستند تا مصرفکنندگان رونوشت بتوانند بخشهای ناقص لغوشده را از خروجی تکمیل عادی تشخیص دهند.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## نصب PWA و پوش وب
|
||||
## نصب PWA و Web Push
|
||||
|
||||
Control UI یک `manifest.webmanifest` و یک سرویسورکر ارائه میکند، بنابراین مرورگرهای مدرن میتوانند آن را بهصورت یک PWA مستقل نصب کنند. Web Push به Gateway اجازه میدهد PWA نصبشده را حتی وقتی برگه یا پنجرهٔ مرورگر باز نیست با اعلانها بیدار کند.
|
||||
Control UI یک `manifest.webmanifest` و یک service worker ارائه میکند، بنابراین مرورگرهای مدرن میتوانند آن را بهعنوان یک PWA مستقل نصب کنند. Web Push به Gateway اجازه میدهد PWA نصبشده را حتی وقتی زبانه یا پنجره مرورگر باز نیست با اعلانها بیدار کند.
|
||||
|
||||
| سطح | کارکرد |
|
||||
| سطح | کاری که انجام میدهد |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | مانیفست PWA. مرورگرها پس از در دسترس شدن آن، گزینهٔ «نصب برنامه» را ارائه میکنند. |
|
||||
| `ui/public/sw.js` | سرویسورکری که رویدادهای `push` و کلیکهای اعلان را مدیریت میکند. |
|
||||
| `push/vapid-keys.json` (زیر دایرکتوری وضعیت OpenClaw) | جفتکلید VAPID خودکار تولیدشده که برای امضای محمولههای Web Push استفاده میشود. |
|
||||
| `push/web-push-subscriptions.json` | نقطههای پایانی اشتراک مرورگرِ پایدارشده. |
|
||||
| `ui/public/manifest.webmanifest` | manifest مربوط به PWA. وقتی در دسترس باشد، مرورگرها گزینه «نصب برنامه» را ارائه میکنند. |
|
||||
| `ui/public/sw.js` | service worker که رویدادهای `push` و کلیکهای اعلان را مدیریت میکند. |
|
||||
| `push/vapid-keys.json` (درون مسیر وضعیت OpenClaw) | جفتکلید VAPID خودکار تولیدشده که برای امضای بارهای Web Push استفاده میشود. |
|
||||
| `push/web-push-subscriptions.json` | endpointهای subscription مرورگر که پایدار شدهاند. |
|
||||
|
||||
وقتی میخواهید کلیدها را ثابت کنید (برای استقرارهای چندمیزبانه، چرخش محرمانهها، یا آزمونها)، جفتکلید VAPID را از طریق متغیرهای محیطی روی فرایند Gateway بازنویسی کنید:
|
||||
وقتی میخواهید کلیدها را ثابت کنید (برای استقرارهای چندمیزبانه، چرخش secretها، یا آزمونها)، جفتکلید VAPID را از طریق متغیرهای محیطی در فرایند Gateway بازنویسی کنید:
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (پیشفرض `mailto:openclaw@localhost`)
|
||||
|
||||
Control UI از این روشهای Gateway محدودشده به دامنه برای ثبت و آزمودن اشتراکهای مرورگر استفاده میکند:
|
||||
Control UI از این روشهای Gateway با دامنه محدود برای ثبت و آزمودن subscriptionهای مرورگر استفاده میکند:
|
||||
|
||||
- `push.web.vapidPublicKey` — کلید عمومی VAPID فعال را دریافت میکند.
|
||||
- `push.web.subscribe` — یک `endpoint` بههمراه `keys.p256dh`/`keys.auth` را ثبت میکند.
|
||||
- `push.web.unsubscribe` — یک نقطهٔ پایانی ثبتشده را حذف میکند.
|
||||
- `push.web.test` — یک اعلان آزمایشی به اشتراک فراخواننده میفرستد.
|
||||
- `push.web.subscribe` — یک `endpoint` بهاضافه `keys.p256dh`/`keys.auth` را ثبت میکند.
|
||||
- `push.web.unsubscribe` — یک endpoint ثبتشده را حذف میکند.
|
||||
- `push.web.test` — یک اعلان آزمایشی به subscription فراخواننده میفرستد.
|
||||
|
||||
<Note>
|
||||
Web Push مستقل از مسیر رلهٔ APNS در iOS است (برای پوش پشتیبانیشده با رله، [پیکربندی](/fa/gateway/configuration) را ببینید) و با روش موجود `push.test` که جفتسازی موبایل بومی را هدف میگیرد فرق دارد.
|
||||
Web Push مستقل از مسیر relay مربوط به iOS APNS است (برای push پشتیبانیشده با relay به [پیکربندی](/fa/gateway/configuration) مراجعه کنید) و همچنین مستقل از روش موجود `push.test` است که pairing موبایل بومی را هدف میگیرد.
|
||||
</Note>
|
||||
|
||||
## جاسازیهای میزبانیشده
|
||||
|
||||
پیامهای دستیار میتوانند محتوای وب میزبانیشده را با شورتکد `[embed ...]` بهصورت درونخطی رندر کنند. سیاست سندباکس iframe توسط `gateway.controlUi.embedSandbox` کنترل میشود:
|
||||
پیامهای assistant میتوانند محتوای وب میزبانیشده را با shortcode `[embed ...]` بهصورت درونخطی رندر کنند. سیاست sandbox iframe با `gateway.controlUi.embedSandbox` کنترل میشود:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
اجرای اسکریپت را داخل جاسازیهای میزبانیشده غیرفعال میکند.
|
||||
اجرای script را درون جاسازیهای میزبانیشده غیرفعال میکند.
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
ضمن حفظ جداسازی مبدا، جاسازیهای تعاملی را مجاز میکند؛ این مقدار پیشفرض است و معمولاً برای بازیها/ویجتهای مرورگری خودبسنده کافی است.
|
||||
<Tab title="scripts (پیشفرض)">
|
||||
جاسازیهای تعاملی را مجاز میکند و همزمان جداسازی origin را نگه میدارد؛ این پیشفرض است و معمولاً برای بازیها/ویجتهای مرورگری خودبسنده کافی است.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
برای اسناد همسایتی که عمداً به امتیازهای قویتری نیاز دارند، `allow-same-origin` را روی `allow-scripts` اضافه میکند.
|
||||
`allow-same-origin` را روی `allow-scripts` برای سندهای همان سایتی اضافه میکند که عمداً به امتیازهای قویتر نیاز دارند.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
مثال:
|
||||
نمونه:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -249,14 +251,14 @@ Web Push مستقل از مسیر رلهٔ APNS در iOS است (برای پوش
|
||||
```
|
||||
|
||||
<Warning>
|
||||
از `trusted` فقط زمانی استفاده کنید که سند جاسازیشده واقعاً به رفتار هممبدا نیاز دارد. برای بیشتر بازیهای تولیدشده توسط عامل و canvasهای تعاملی، `scripts` انتخاب ایمنتری است.
|
||||
از `trusted` فقط وقتی استفاده کنید که سند جاسازیشده واقعاً به رفتار same-origin نیاز داشته باشد. برای بیشتر بازیها و canvasهای تعاملی تولیدشده توسط agent، `scripts` گزینه ایمنتری است.
|
||||
</Warning>
|
||||
|
||||
URLهای جاسازی مطلق خارجی `http(s)` بهطور پیشفرض مسدود میمانند. اگر عمداً میخواهید `[embed url="https://..."]` صفحههای شخص ثالث را بارگذاری کند، `gateway.controlUi.allowExternalEmbedUrls: true` را تنظیم کنید.
|
||||
URLهای جاسازی خارجی مطلق `http(s)` بهطور پیشفرض مسدود میمانند. اگر عمداً میخواهید `[embed url="https://..."]` صفحههای شخص ثالث را بارگذاری کند، `gateway.controlUi.allowExternalEmbedUrls: true` را تنظیم کنید.
|
||||
|
||||
## پهنای پیام چت
|
||||
## پهنای پیام Chat
|
||||
|
||||
پیامهای چت گروهبندیشده از یک حداکثر پهنای خوانا بهصورت پیشفرض استفاده میکنند. استقرارهای مانیتور عریض میتوانند بدون وصله کردن CSS بستهبندیشده، با تنظیم `gateway.controlUi.chatMessageMaxWidth` آن را بازنویسی کنند:
|
||||
پیامهای گروهبندیشده chat از max-width پیشفرض خوانا استفاده میکنند. استقرارهای مانیتور عریض میتوانند بدون وصله کردن CSS بستهبندیشده، با تنظیم `gateway.controlUi.chatMessageMaxWidth` آن را بازنویسی کنند:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -268,13 +270,13 @@ URLهای جاسازی مطلق خارجی `http(s)` بهطور پیشفر
|
||||
}
|
||||
```
|
||||
|
||||
این مقدار پیش از رسیدن به مرورگر اعتبارسنجی میشود. مقدارهای پشتیبانیشده شامل طولها و درصدهای ساده مانند `960px` یا `82%`، بهعلاوهٔ عبارتهای پهنای محدودشدهٔ `min(...)`، `max(...)`، `clamp(...)`، `calc(...)`، و `fit-content(...)` هستند.
|
||||
این مقدار پیش از رسیدن به مرورگر اعتبارسنجی میشود. مقدارهای پشتیبانیشده شامل طولها و درصدهای ساده مانند `960px` یا `82%`، بهاضافه عبارتهای عرض محدودشده `min(...)`، `max(...)`، `clamp(...)`، `calc(...)`، و `fit-content(...)` هستند.
|
||||
|
||||
## دسترسی tailnet (توصیهشده)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Tailscale Serve یکپارچه (ترجیحی)">
|
||||
Gateway را روی loopback نگه دارید و بگذارید Tailscale Serve آن را با HTTPS پروکسی کند:
|
||||
Gateway را روی local loopback نگه دارید و اجازه دهید Tailscale Serve آن را با HTTPS proxy کند:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -282,48 +284,48 @@ URLهای جاسازی مطلق خارجی `http(s)` بهطور پیشفر
|
||||
|
||||
باز کنید:
|
||||
|
||||
- `https://<magicdns>/` (یا `gateway.controlUi.basePath` پیکربندیشدهٔ شما)
|
||||
- `https://<magicdns>/` (یا `gateway.controlUi.basePath` پیکربندیشده شما)
|
||||
|
||||
بهطور پیشفرض، درخواستهای Control UI/WebSocket Serve میتوانند وقتی `gateway.auth.allowTailscale` برابر `true` است از طریق سرآیندهای هویت Tailscale (`tailscale-user-login`) احراز هویت شوند. OpenClaw هویت را با حل کردن نشانی `x-forwarded-for` توسط `tailscale whois` و تطبیق آن با سرآیند راستیآزمایی میکند، و اینها را فقط وقتی درخواست به loopback با سرآیندهای `x-forwarded-*` مربوط به Tailscale برسد میپذیرد. برای نشستهای اپراتور Control UI با هویت دستگاه مرورگر، این مسیر Serve راستیآزماییشده رفتوبرگشت جفتسازی دستگاه را نیز رد میکند؛ مرورگرهای بدون دستگاه و اتصالهای نقش نود همچنان بررسیهای عادی دستگاه را دنبال میکنند. اگر میخواهید حتی برای ترافیک Serve نیز اعتبارنامههای صریح محرمانهٔ مشترک لازم باشد، `gateway.auth.allowTailscale: false` را تنظیم کنید. سپس از `gateway.auth.mode: "token"` یا `"password"` استفاده کنید.
|
||||
بهطور پیشفرض، درخواستهای Control UI/WebSocket Serve میتوانند از طریق headerهای هویت Tailscale (`tailscale-user-login`) احراز هویت شوند وقتی `gateway.auth.allowTailscale` برابر `true` است. OpenClaw هویت را با resolve کردن آدرس `x-forwarded-for` از طریق `tailscale whois` و تطبیق آن با header بررسی میکند، و فقط وقتی اینها را میپذیرد که درخواست با headerهای `x-forwarded-*` متعلق به Tailscale به local loopback برسد. برای نشستهای اپراتور Control UI با هویت دستگاه مرورگر، این مسیر Serve تأییدشده همچنین رفتوبرگشت pairing دستگاه را رد میکند؛ مرورگرهای بدون دستگاه و اتصالهای نقش node همچنان بررسیهای عادی دستگاه را دنبال میکنند. اگر میخواهید حتی برای ترافیک Serve هم اعتبارنامههای صریح secret مشترک را الزامی کنید، `gateway.auth.allowTailscale: false` را تنظیم کنید. سپس از `gateway.auth.mode: "token"` یا `"password"` استفاده کنید.
|
||||
|
||||
برای آن مسیر هویت ناهمگام Serve، تلاشهای احراز هویت ناموفق برای همان IP کلاینت و دامنهٔ احراز هویت پیش از نوشتنهای محدودسازی نرخ سریالی میشوند. بنابراین تلاشهای ناموفق همزمان از همان مرورگر میتوانند در درخواست دوم بهجای دو عدمتطابق ساده که موازی رقابت میکنند، `retry later` را نشان دهند.
|
||||
برای آن مسیر async هویت Serve، تلاشهای auth ناموفق برای همان IP مشتری و دامنه auth پیش از نوشتن rate-limit سریالی میشوند. بنابراین retryهای بد همزمان از همان مرورگر میتوانند در درخواست دوم بهجای دو mismatch ساده که موازی رقابت میکنند، `retry later` را نشان دهند.
|
||||
|
||||
<Warning>
|
||||
احراز هویت Serve بدون توکن فرض میکند میزبان Gateway مورد اعتماد است. اگر کد محلی نامطمئن ممکن است روی آن میزبان اجرا شود، احراز هویت توکن/گذرواژه را الزامی کنید.
|
||||
auth بدون token در Serve فرض میکند میزبان gateway قابلاعتماد است. اگر کد محلی غیرقابلاعتماد ممکن است روی آن میزبان اجرا شود، auth با token/password را الزامی کنید.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="اتصال به tailnet + توکن">
|
||||
<Tab title="اتصال به tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
|
||||
سپس باز کنید:
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (یا `gateway.controlUi.basePath` پیکربندیشدهٔ شما)
|
||||
- `http://<tailscale-ip>:18789/` (یا `gateway.controlUi.basePath` پیکربندیشده شما)
|
||||
|
||||
محرمانهٔ مشترک متناظر را در تنظیمات UI جایگذاری کنید (بهصورت `connect.params.auth.token` یا `connect.params.auth.password` فرستاده میشود).
|
||||
secret مشترک متناظر را در تنظیمات UI جایگذاری کنید (بهصورت `connect.params.auth.token` یا `connect.params.auth.password` ارسال میشود).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## HTTP ناامن
|
||||
|
||||
اگر داشبورد را روی HTTP ساده (`http://<lan-ip>` یا `http://<tailscale-ip>`) باز کنید، مرورگر در یک **زمینهٔ ناامن** اجرا میشود و WebCrypto را مسدود میکند. بهطور پیشفرض، OpenClaw اتصالهای Control UI بدون هویت دستگاه را **مسدود** میکند.
|
||||
اگر داشبورد را از طریق HTTP ساده باز کنید (`http://<lan-ip>` یا `http://<tailscale-ip>`)، مرورگر در یک **زمینه غیرامن** اجرا میشود و WebCrypto را مسدود میکند. بهطور پیشفرض، OpenClaw اتصالهای Control UI بدون هویت دستگاه را **مسدود** میکند.
|
||||
|
||||
استثناهای مستندشده:
|
||||
استثناهای مستند:
|
||||
|
||||
- سازگاری HTTP ناامن فقط برای localhost با `gateway.controlUi.allowInsecureAuth=true`
|
||||
- احراز هویت موفق اپراتور Control UI از طریق `gateway.auth.mode: "trusted-proxy"`
|
||||
- مسیر اضطراری `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- احراز هویت موفق Control UI اپراتور از طریق `gateway.auth.mode: "trusted-proxy"`
|
||||
- حالت اضطراری `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**راهحل توصیهشده:** از HTTPS (Tailscale Serve) استفاده کنید یا UI را بهصورت محلی باز کنید:
|
||||
**راهکار پیشنهادی:** از HTTPS (Tailscale Serve) استفاده کنید یا UI را بهصورت محلی باز کنید:
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (روی میزبان gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="رفتار کلید insecure-auth">
|
||||
<Accordion title="رفتار کلید احراز هویت ناامن">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -336,12 +338,12 @@ URLهای جاسازی مطلق خارجی `http(s)` بهطور پیشفر
|
||||
|
||||
`allowInsecureAuth` فقط یک کلید سازگاری محلی است:
|
||||
|
||||
- به نشستهای واسط کاربری کنترل روی localhost اجازه میدهد در بسترهای HTTP ناامن بدون هویت دستگاه ادامه پیدا کنند.
|
||||
- بررسیهای جفتسازی را دور نمیزند.
|
||||
- الزامات هویت دستگاه راهدور (غیر localhost) را کاهش نمیدهد.
|
||||
- به نشستهای localhost Control UI اجازه میدهد در زمینههای HTTP غیرامن بدون هویت دستگاه ادامه پیدا کنند.
|
||||
- بررسیهای pairing را دور نمیزند.
|
||||
- الزامات هویت دستگاه remote (غیر localhost) را کاهش نمیدهد.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="فقط برای استفاده اضطراری">
|
||||
<Accordion title="فقط برای حالت اضطراری">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -353,71 +355,71 @@ URLهای جاسازی مطلق خارجی `http(s)` بهطور پیشفر
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` بررسیهای هویت دستگاه واسط کاربری کنترل را غیرفعال میکند و افت امنیتی شدیدی است. پس از استفاده اضطراری، سریعاً آن را برگردانید.
|
||||
`dangerouslyDisableDeviceAuth` بررسیهای هویت دستگاه Control UI را غیرفعال میکند و یک کاهش امنیتی شدید است. پس از استفاده اضطراری، آن را سریعاً برگردانید.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="یادداشت پراکسی مورد اعتماد">
|
||||
- احراز هویت پراکسی مورد اعتماد موفق میتواند نشستهای واسط کاربری کنترل **اپراتور** را بدون هویت دستگاه بپذیرد.
|
||||
- این موضوع به نشستهای واسط کاربری کنترل با نقش گره **گسترش نمییابد**.
|
||||
- پراکسیهای معکوس حلقهبازگشت روی همان میزبان همچنان احراز هویت پراکسی مورد اعتماد را برآورده نمیکنند؛ [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید.
|
||||
<Accordion title="نکته trusted-proxy">
|
||||
- احراز هویت موفق trusted-proxy میتواند نشستهای Control UI **اپراتور** را بدون هویت دستگاه بپذیرد.
|
||||
- این مورد به نشستهای Control UI با نقش node گسترش نمییابد.
|
||||
- reverse proxyهای loopback روی همان میزبان همچنان احراز هویت trusted-proxy را برآورده نمیکنند؛ [احراز هویت trusted proxy](/fa/gateway/trusted-proxy-auth) را ببینید.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
برای راهنمایی راهاندازی HTTPS، [Tailscale](/fa/gateway/tailscale) را ببینید.
|
||||
برای راهنمایی درباره راهاندازی HTTPS، [Tailscale](/fa/gateway/tailscale) را ببینید.
|
||||
|
||||
## سیاست امنیت محتوا
|
||||
|
||||
واسط کاربری کنترل با سیاست سختگیرانه `img-src` ارائه میشود: فقط داراییهای **هممبدأ**، URLهای `data:`، و URLهای `blob:` تولیدشده بهصورت محلی مجاز هستند. URLهای تصویر راهدور `http(s)` و نسبی به پروتکل توسط مرورگر رد میشوند و باعث واکشی شبکهای نمیشوند.
|
||||
Control UI با یک سیاست محدود `img-src` ارائه میشود: فقط داراییهای **same-origin**، URLهای `data:`، و URLهای `blob:` تولیدشده بهصورت محلی مجاز هستند. URLهای تصویر remote از نوع `http(s)` و URLهای protocol-relative توسط مرورگر رد میشوند و درخواست شبکهای صادر نمیکنند.
|
||||
|
||||
این در عمل یعنی:
|
||||
معنای عملی این موضوع:
|
||||
|
||||
- آواتارها و تصویرهایی که از مسیرهای نسبی ارائه میشوند (برای مثال `/avatars/<id>`) همچنان رندر میشوند، از جمله مسیرهای آواتار احراز هویتشده که واسط کاربری آنها را دریافت و به URLهای محلی `blob:` تبدیل میکند.
|
||||
- URLهای درونخطی `data:image/...` همچنان رندر میشوند (برای محمولههای درونپروتکلی مفید است).
|
||||
- URLهای محلی `blob:` که واسط کاربری کنترل ایجاد میکند همچنان رندر میشوند.
|
||||
- URLهای آواتار راهدور که از فراداده کانال تولید میشوند، در کمکتابعهای آواتار واسط کاربری کنترل حذف میشوند و با نشانواره/نشان داخلی جایگزین میشوند، بنابراین یک کانال نفوذشده یا مخرب نمیتواند مرورگر اپراتور را وادار کند تصویرهای راهدور دلخواه را واکشی کند.
|
||||
- آواتارها و تصویرهایی که زیر مسیرهای نسبی ارائه میشوند (برای مثال `/avatars/<id>`) همچنان نمایش داده میشوند، از جمله routeهای آواتار احرازشده که UI آنها را دریافت و به URLهای محلی `blob:` تبدیل میکند.
|
||||
- URLهای درونخطی `data:image/...` همچنان نمایش داده میشوند (برای payloadهای درون پروتکل مفید است).
|
||||
- URLهای محلی `blob:` که توسط Control UI ایجاد میشوند همچنان نمایش داده میشوند.
|
||||
- URLهای آواتار remote که توسط metadata کانال منتشر میشوند در helperهای آواتار Control UI حذف و با لوگو/نشان داخلی جایگزین میشوند، بنابراین یک کانال compromise شده یا مخرب نمیتواند مرورگر اپراتور را مجبور به دریافت تصویر remote دلخواه کند.
|
||||
|
||||
برای دریافت این رفتار لازم نیست چیزی را تغییر دهید؛ این قابلیت همیشه فعال است و قابل پیکربندی نیست.
|
||||
برای دریافت این رفتار لازم نیست چیزی را تغییر دهید — همیشه فعال است و قابل پیکربندی نیست.
|
||||
|
||||
## احراز هویت مسیر آواتار
|
||||
## احراز هویت route آواتار
|
||||
|
||||
وقتی احراز هویت Gateway پیکربندی شده باشد، نقطه پایانی آواتار واسط کاربری کنترل به همان توکن Gateway مثل بقیه API نیاز دارد:
|
||||
وقتی احراز هویت gateway پیکربندی شده باشد، endpoint آواتار Control UI به همان توکن gateway مانند بقیه API نیاز دارد:
|
||||
|
||||
- `GET /avatar/<agentId>` تصویر آواتار را فقط به فراخوانندههای احراز هویتشده برمیگرداند. `GET /avatar/<agentId>?meta=1` فراداده آواتار را طبق همان قاعده برمیگرداند.
|
||||
- درخواستهای بدون احراز هویت به هر یک از این دو مسیر رد میشوند (همانند مسیر همسطح assistant-media). این کار از افشای هویت عامل توسط مسیر آواتار روی میزبانهایی که در غیر این صورت محافظتشدهاند جلوگیری میکند.
|
||||
- خود واسط کاربری کنترل هنگام دریافت آواتارها توکن Gateway را بهعنوان هدر bearer ارسال میکند و از URLهای blob احراز هویتشده استفاده میکند تا تصویر همچنان در داشبوردها رندر شود.
|
||||
- `GET /avatar/<agentId>` تصویر آواتار را فقط به فراخوانهای احرازشده برمیگرداند. `GET /avatar/<agentId>?meta=1` metadata آواتار را با همان قاعده برمیگرداند.
|
||||
- درخواستهای احرازنشده به هرکدام از routeها رد میشوند (مطابق route همخانواده assistant-media). این کار مانع از آن میشود که route آواتار هویت agent را روی میزبانهایی که در غیر این صورت محافظت شدهاند افشا کند.
|
||||
- خود Control UI هنگام دریافت آواتارها، توکن gateway را بهعنوان header bearer ارسال میکند و از URLهای blob احرازشده استفاده میکند تا تصویر همچنان در dashboardها نمایش داده شود.
|
||||
|
||||
اگر احراز هویت Gateway را غیرفعال کنید (روی میزبانهای اشتراکی توصیه نمیشود)، مسیر آواتار نیز، همسو با بقیه Gateway، بدون احراز هویت میشود.
|
||||
اگر احراز هویت gateway را غیرفعال کنید (روی میزبانهای اشتراکی توصیه نمیشود)، route آواتار نیز مطابق بقیه gateway احرازنشده میشود.
|
||||
|
||||
## ساخت واسط کاربری
|
||||
## ساخت UI
|
||||
|
||||
Gateway فایلهای ایستا را از `dist/control-ui` ارائه میکند. آنها را با این دستور بسازید:
|
||||
Gateway فایلهای static را از `dist/control-ui` ارائه میکند. آنها را با این دستور بسازید:
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
پایه مطلق اختیاری (وقتی URLهای ثابت داراییها را میخواهید):
|
||||
base مطلق اختیاری (وقتی URLهای ثابت دارایی میخواهید):
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
برای توسعه محلی (سرور توسعه جداگانه):
|
||||
برای توسعه محلی (dev server جداگانه):
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
سپس واسط کاربری را به URL وبسوکت Gateway خود متصل کنید (برای مثال `ws://127.0.0.1:18789`).
|
||||
سپس UI را به URL مربوط به Gateway WS خود هدایت کنید (مثلاً `ws://127.0.0.1:18789`).
|
||||
|
||||
## اشکالزدایی/آزمایش: سرور توسعه + Gateway راهدور
|
||||
## اشکالزدایی/آزمایش: dev server + Gateway remote
|
||||
|
||||
واسط کاربری کنترل فایلهای ایستا است؛ مقصد WebSocket قابل پیکربندی است و میتواند با مبدأ HTTP متفاوت باشد. این زمانی مفید است که میخواهید سرور توسعه Vite محلی باشد اما Gateway جای دیگری اجرا شود.
|
||||
Control UI از فایلهای static تشکیل شده است؛ مقصد WebSocket قابل پیکربندی است و میتواند با origin HTTP متفاوت باشد. این زمانی مفید است که dev server مربوط به Vite را بهصورت محلی میخواهید اما Gateway جای دیگری اجرا میشود.
|
||||
|
||||
<Steps>
|
||||
<Step title="سرور توسعه واسط کاربری را شروع کنید">
|
||||
<Step title="dev server مربوط به UI را شروع کنید">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
@ -437,18 +439,18 @@ pnpm ui:dev
|
||||
</Steps>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="یادداشتها">
|
||||
<Accordion title="نکتهها">
|
||||
- `gatewayUrl` پس از بارگذاری در localStorage ذخیره و از URL حذف میشود.
|
||||
- اگر یک نقطه پایانی کامل `ws://` یا `wss://` را از طریق `gatewayUrl` ارسال میکنید، مقدار `gatewayUrl` را بهصورت URL کدگذاری کنید تا مرورگر رشته پرسوجو را درست تجزیه کند.
|
||||
- `token` باید هر زمان ممکن است از طریق فرگمنت URL (`#token=...`) ارسال شود. فرگمنتها به سرور ارسال نمیشوند و این از نشت لاگ درخواست و Referer جلوگیری میکند. پارامترهای query قدیمی `?token=` همچنان برای سازگاری یکبار وارد میشوند، اما فقط بهعنوان راهکار پشتیبان، و بلافاصله پس از راهاندازی اولیه حذف میشوند.
|
||||
- اگر یک endpoint کامل `ws://` یا `wss://` را از طریق `gatewayUrl` میدهید، مقدار `gatewayUrl` را URL-encode کنید تا مرورگر query string را درست parse کند.
|
||||
- هر زمان ممکن است، `token` باید از طریق fragment URL (`#token=...`) ارسال شود. fragmentها به سرور فرستاده نمیشوند و این از نشت در request-log و Referer جلوگیری میکند. query paramهای قدیمی `?token=` همچنان برای سازگاری یکبار import میشوند، اما فقط بهعنوان fallback، و بلافاصله پس از bootstrap حذف میشوند.
|
||||
- `password` فقط در حافظه نگه داشته میشود.
|
||||
- وقتی `gatewayUrl` تنظیم شده باشد، واسط کاربری به اعتبارنامههای پیکربندی یا محیط بازنمیگردد. `token` (یا `password`) را صریحاً فراهم کنید. نبود اعتبارنامههای صریح، خطا محسوب میشود.
|
||||
- وقتی Gateway پشت TLS است (Tailscale Serve، پراکسی HTTPS و غیره)، از `wss://` استفاده کنید.
|
||||
- `gatewayUrl` فقط در پنجره سطح بالا (نه تعبیهشده) پذیرفته میشود تا از کلیکربایی جلوگیری شود.
|
||||
- استقرارهای غیرحلقهبازگشت واسط کاربری کنترل باید `gateway.controlUi.allowedOrigins` را صریحاً تنظیم کنند (مبدأهای کامل). این شامل راهاندازیهای توسعه راهدور نیز میشود.
|
||||
- شروع به کار Gateway ممکن است مبدأهای محلی مانند `http://localhost:<port>` و `http://127.0.0.1:<port>` را بر اساس bind و پورت مؤثر زمان اجرا مقداردهی اولیه کند، اما مبدأهای مرورگر راهدور همچنان به ورودیهای صریح نیاز دارند.
|
||||
- از `gateway.controlUi.allowedOrigins: ["*"]` استفاده نکنید مگر برای آزمایش محلی بهشدت کنترلشده. این یعنی اجازه به هر مبدأ مرورگر، نه «مطابقت با هر میزبانی که استفاده میکنم».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` حالت بازگشت جایگزین مبدأ بر اساس هدر Host را فعال میکند، اما این یک حالت امنیتی خطرناک است.
|
||||
- وقتی `gatewayUrl` تنظیم شده باشد، UI به credentialهای config یا environment fallback نمیکند. `token` (یا `password`) را صراحتاً ارائه کنید. نبود credentialهای صریح خطا است.
|
||||
- وقتی Gateway پشت TLS است (Tailscale Serve، proxy HTTPS، و غیره)، از `wss://` استفاده کنید.
|
||||
- `gatewayUrl` فقط در پنجره سطح بالا پذیرفته میشود (نه embedded) تا از clickjacking جلوگیری شود.
|
||||
- deploymentهای Control UI غیر loopback باید `gateway.controlUi.allowedOrigins` را صراحتاً تنظیم کنند (originهای کامل). این شامل راهاندازیهای dev remote نیز میشود.
|
||||
- راهاندازی Gateway ممکن است originهای محلی مانند `http://localhost:<port>` و `http://127.0.0.1:<port>` را از bind و port مؤثر runtime seed کند، اما originهای مرورگر remote همچنان به ورودیهای صریح نیاز دارند.
|
||||
- از `gateway.controlUi.allowedOrigins: ["*"]` استفاده نکنید مگر برای آزمایش محلی کاملاً کنترلشده. معنای آن اجازه دادن به هر origin مرورگر است، نه «مطابقت با هر hostی که استفاده میکنم».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` حالت fallback origin مبتنی بر Host-header را فعال میکند، اما این یک حالت امنیتی خطرناک است.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -465,11 +467,11 @@ pnpm ui:dev
|
||||
}
|
||||
```
|
||||
|
||||
جزئیات راهاندازی دسترسی راهدور: [دسترسی راهدور](/fa/gateway/remote).
|
||||
جزئیات راهاندازی دسترسی remote: [دسترسی remote](/fa/gateway/remote).
|
||||
|
||||
## مرتبط
|
||||
|
||||
- [داشبورد](/fa/web/dashboard) — داشبورد Gateway
|
||||
- [بررسیهای سلامت](/fa/gateway/health) — پایش سلامت Gateway
|
||||
- [TUI](/fa/web/tui) — رابط کاربری ترمینال
|
||||
- [چت وب](/fa/web/webchat) — رابط چت مبتنی بر مرورگر
|
||||
- [Dashboard](/fa/web/dashboard) — dashboard مربوط به gateway
|
||||
- [Health Checks](/fa/gateway/health) — پایش سلامت gateway
|
||||
- [TUI](/fa/web/tui) — رابط کاربری terminal
|
||||
- [WebChat](/fa/web/webchat) — رابط chat مبتنی بر مرورگر
|
||||
|
||||
@ -1,71 +1,72 @@
|
||||
---
|
||||
read_when:
|
||||
- عیبیابی یا پیکربندی دسترسی WebChat
|
||||
summary: میزبان ایستای وبچت لوپبک و استفاده از WS در Gateway برای رابط کاربری چت
|
||||
title: چت وب
|
||||
- اشکالزدایی یا پیکربندی دسترسی WebChat
|
||||
summary: میزبان ایستای چت وب لوپبک و استفاده از WS Gateway برای رابط کاربری چت
|
||||
title: وبچت
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T12:08:34Z"
|
||||
generated_at: "2026-05-02T23:39:03Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fe6d3cb30ed18d651b0d0ca8fd188b47c5f1d186410ee340deb79315f194ed8d
|
||||
source_hash: ad3a09c8962e3a6dda83716d319df7ba27e18105cee50721278b5cba0a85c52f
|
||||
source_path: web/webchat.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
وضعیت: واسط کاربری چت SwiftUI در macOS/iOS مستقیما با WebSocket Gateway صحبت میکند.
|
||||
وضعیت: رابط کاربری چت SwiftUI در macOS/iOS مستقیماً با WebSocketِ Gateway صحبت میکند.
|
||||
|
||||
## چیست
|
||||
## چیستی آن
|
||||
|
||||
- یک واسط کاربری چت بومی برای Gateway (بدون مرورگر تعبیهشده و بدون سرور ایستای محلی).
|
||||
- از همان نشستها و قواعد مسیریابی کانالهای دیگر استفاده میکند.
|
||||
- یک رابط کاربری چت بومی برای Gateway (بدون مرورگر توکار و بدون سرور استاتیک محلی).
|
||||
- از همان جلسهها و قواعد مسیریابی سایر کانالها استفاده میکند.
|
||||
- مسیریابی قطعی: پاسخها همیشه به WebChat برمیگردند.
|
||||
|
||||
## شروع سریع
|
||||
|
||||
1. Gateway را راهاندازی کنید.
|
||||
2. واسط کاربری WebChat (برنامه macOS/iOS) یا زبانه چت واسط کاربری کنترل را باز کنید.
|
||||
3. مطمئن شوید یک مسیر معتبر احراز هویت Gateway پیکربندی شده است (بهطور پیشفرض shared-secret،
|
||||
2. رابط کاربری WebChat (برنامه macOS/iOS) یا زبانه چت Control UI را باز کنید.
|
||||
3. مطمئن شوید یک مسیر احراز هویت معتبر برای Gateway پیکربندی شده است (بهصورت پیشفرض shared-secret،
|
||||
حتی روی loopback).
|
||||
|
||||
## نحوه کارکرد (رفتار)
|
||||
|
||||
- واسط کاربری به WebSocket Gateway متصل میشود و از `chat.history`، `chat.send`، و `chat.inject` استفاده میکند.
|
||||
- `chat.history` برای پایداری محدود است: Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، فراداده سنگین را حذف کند، و ورودیهای بیشازحد بزرگ را با `[chat.history omitted: message too large]` جایگزین کند.
|
||||
- `chat.history` برای فایلهای نشست مدرن append-only شاخه فعال رونوشت را دنبال میکند، بنابراین شاخههای بازنویسی رهاشده و نسخههای رونویسیشده اعلان در WebChat رندر نمیشوند.
|
||||
- واسط کاربری کنترل، `sessionId` پشتیبان Gateway را که توسط `chat.history` برگردانده شده به خاطر میسپارد و آن را در فراخوانیهای پیگیری `chat.send` میگنجاند، بنابراین اتصالهای مجدد و نوسازی صفحه همان گفتوگوی ذخیرهشده را ادامه میدهند مگر اینکه کاربر نشستی را شروع یا بازنشانی کند.
|
||||
- واسط کاربری کنترل، ارسالهای تکراری در حال اجرا را برای همان نشست، پیام، و پیوستها پیش از تولید یک شناسه اجرای جدید `chat.send` ادغام میکند؛ Gateway همچنان درخواستهای تکراری را که از همان کلید idempotency دوباره استفاده میکنند حذف تکراری میکند.
|
||||
- `chat.history` همچنین برای نمایش نرمالسازی میشود: زمینه فقط زمان اجرای OpenClaw،
|
||||
پوششهای envelope ورودی، برچسبهای دستور تحویل درونخطی
|
||||
مانند `[[reply_to_*]]` و `[[audio_as_voice]]`، محمولههای XML فراخوانی ابزار متن ساده
|
||||
(شامل `<tool_call>...</tool_call>`،
|
||||
- رابط کاربری به WebSocketِ Gateway وصل میشود و از `chat.history`، `chat.send`، `chat.inject`، و `chat.transcribeAudio` استفاده میکند.
|
||||
- `chat.history` برای پایداری محدود است: Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، فرادادههای سنگین را حذف کند، و ورودیهای بیشازحد بزرگ را با `[chat.history omitted: message too large]` جایگزین کند.
|
||||
- `chat.history` برای فایلهای جلسه مدرن append-only شاخه فعال رونوشت را دنبال میکند، بنابراین شاخههای بازنویسی رهاشده و نسخههای درخواست جایگزینشده در WebChat نمایش داده نمیشوند.
|
||||
- Control UI شناسه Gateway پشتیبان، یعنی `sessionId` برگشتی از `chat.history`، را به خاطر میسپارد و آن را در فراخوانیهای بعدی `chat.send` اضافه میکند، بنابراین اتصالهای مجدد و تازهسازی صفحه همان گفتوگوی ذخیرهشده را ادامه میدهند مگر اینکه کاربر جلسهای را شروع یا بازنشانی کند.
|
||||
- Control UI ارسالهای در حال انجام تکراری را برای همان جلسه، پیام، و پیوستها پیش از تولید یک شناسه اجرای جدید `chat.send` ادغام میکند؛ Gateway همچنان درخواستهای تکراریای را که از همان کلید idempotency استفاده میکنند حذف تکرار میکند.
|
||||
- `chat.history` همچنین برای نمایش نرمالسازی میشود: زمینه فقط-زماناجرای OpenClaw،
|
||||
پوششهای پاکت ورودی، برچسبهای درونخطی دستور تحویل
|
||||
مانند `[[reply_to_*]]` و `[[audio_as_voice]]`، payloadهای XML فراخوانی ابزار بهصورت متن ساده
|
||||
(از جمله `<tool_call>...</tool_call>`،
|
||||
`<function_call>...</function_call>`، `<tool_calls>...</tool_calls>`،
|
||||
`<function_calls>...</function_calls>`، و بلوکهای کوتاهشده فراخوانی ابزار)، و
|
||||
توکنهای کنترلی مدل ASCII/تمامعرض نشتکرده از متن قابل مشاهده حذف میشوند،
|
||||
و ورودیهای دستیار که کل متن قابل مشاهده آنها فقط توکن سکوت دقیق
|
||||
توکنهای کنترلی ASCII/تمامعرض مدل که نشت کردهاند از متن قابل مشاهده حذف میشوند،
|
||||
و ورودیهای دستیار که کل متن قابل مشاهده آنها فقط توکن خاموش دقیق
|
||||
`NO_REPLY` / `no_reply` است حذف میشوند.
|
||||
- محمولههای پاسخ دارای پرچم استدلال (`isReasoning: true`) از محتوای دستیار WebChat، متن بازپخش رونوشت، و بلوکهای محتوای صوتی کنار گذاشته میشوند، بنابراین محمولههای فقط تفکر بهصورت پیامهای قابل مشاهده دستیار یا صوت قابل پخش ظاهر نمیشوند.
|
||||
- `chat.inject` یک یادداشت دستیار را مستقیما به رونوشت اضافه میکند و آن را به واسط کاربری پخش میکند (بدون اجرای عامل).
|
||||
- اجراهای لغوشده میتوانند خروجی جزئی دستیار را در واسط کاربری قابل مشاهده نگه دارند.
|
||||
- Gateway وقتی خروجی بافرشده وجود دارد، متن جزئی لغوشده دستیار را در تاریخچه رونوشت پایدار میکند و آن ورودیها را با فراداده لغو علامتگذاری میکند.
|
||||
- payloadهای پاسخ علامتگذاریشده بهعنوان استدلال (`isReasoning: true`) از محتوای دستیار WebChat، متن بازپخش رونوشت، و بلوکهای محتوای صوتی حذف میشوند، بنابراین payloadهای فقط-تفکر بهصورت پیامهای قابل مشاهده دستیار یا صوت قابل پخش ظاهر نمیشوند.
|
||||
- `chat.transcribeAudio` دیکته سمت سرور را در آهنگساز چت Control UI پشتیبانی میکند. مرورگر صدای میکروفون را ضبط میکند، آن را بهصورت base64 به Gateway میفرستد، و Gateway پایپلاین پیکربندیشده `tools.media.audio` را اجرا میکند. رونوشت برگشتی در پیشنویس درج میشود؛ تا زمانی که کاربر آن را ارسال نکند هیچ اجرای عاملی شروع نمیشود.
|
||||
- `chat.inject` یک یادداشت دستیار را مستقیماً به رونوشت اضافه میکند و آن را به رابط کاربری پخش میکند (بدون اجرای عامل).
|
||||
- اجراهای لغوشده میتوانند خروجی ناقص دستیار را در رابط کاربری قابل مشاهده نگه دارند.
|
||||
- Gateway وقتی خروجی بافرشده وجود داشته باشد متن ناقص دستیارِ لغوشده را در تاریخچه رونوشت ذخیره میکند و آن ورودیها را با فراداده لغو علامتگذاری میکند.
|
||||
- تاریخچه همیشه از Gateway واکشی میشود (بدون پایش فایل محلی).
|
||||
- اگر Gateway در دسترس نباشد، WebChat فقط خواندنی است.
|
||||
|
||||
## پنل ابزارهای عاملهای واسط کاربری کنترل
|
||||
## پنل ابزارهای عاملها در Control UI
|
||||
|
||||
- پنل ابزارهای `/agents` در واسط کاربری کنترل دو نمای جداگانه دارد:
|
||||
- **همین حالا در دسترس** از `tools.effective(sessionKey=...)` استفاده میکند و نشان میدهد نشست فعلی
|
||||
در زمان اجرا واقعا میتواند از چه چیزهایی استفاده کند، از جمله ابزارهای متعلق به هسته، Plugin، و کانال.
|
||||
- **پیکربندی ابزار** از `tools.catalog` استفاده میکند و بر پروفایلها، بازنویسیها، و
|
||||
- پنل ابزارهای `/agents` در Control UI دو نمای جداگانه دارد:
|
||||
- **همین حالا در دسترس** از `tools.effective(sessionKey=...)` استفاده میکند و نشان میدهد جلسه فعلی
|
||||
واقعاً در زمان اجرا از چه چیزهایی میتواند استفاده کند، از جمله ابزارهای متعلق به هسته، Plugin، و کانال.
|
||||
- **پیکربندی ابزار** از `tools.catalog` استفاده میکند و بر پروفایلها، overrideها، و
|
||||
معناشناسی کاتالوگ متمرکز میماند.
|
||||
- در دسترس بودن زمان اجرا محدود به نشست است. تغییر نشستها روی همان عامل میتواند فهرست
|
||||
- دسترسیپذیری زمان اجرا وابسته به جلسه است. تغییر جلسهها روی همان عامل میتواند فهرست
|
||||
**همین حالا در دسترس** را تغییر دهد.
|
||||
- ویرایشگر پیکربندی بهمعنای در دسترس بودن در زمان اجرا نیست؛ دسترسی مؤثر همچنان از تقدم سیاست
|
||||
(`allow`/`deny`، بازنویسیهای هر عامل و ارائهدهنده/کانال) پیروی میکند.
|
||||
- ویرایشگر پیکربندی بهمعنای دسترسیپذیری زمان اجرا نیست؛ دسترسی مؤثر همچنان از اولویت سیاست
|
||||
(`allow`/`deny`، overrideهای هر عامل و ارائهدهنده/کانال) پیروی میکند.
|
||||
|
||||
## استفاده از راه دور
|
||||
## استفاده راه دور
|
||||
|
||||
- حالت راه دور، WebSocket Gateway را از طریق SSH/Tailscale تونل میکند.
|
||||
- نیازی نیست یک سرور WebChat جداگانه اجرا کنید.
|
||||
- حالت راه دور WebSocketِ Gateway را از طریق SSH/Tailscale تونل میکند.
|
||||
- لازم نیست سرور WebChat جداگانهای اجرا کنید.
|
||||
|
||||
## مرجع پیکربندی (WebChat)
|
||||
|
||||
@ -73,20 +74,20 @@ x-i18n:
|
||||
|
||||
گزینههای WebChat:
|
||||
|
||||
- `gateway.webchat.chatHistoryMaxChars`: حداکثر تعداد نویسه برای فیلدهای متنی در پاسخهای `chat.history`. وقتی یک ورودی رونوشت از این محدودیت فراتر میرود، Gateway فیلدهای متنی طولانی را کوتاه میکند و ممکن است پیامهای بیشازحد بزرگ را با یک placeholder جایگزین کند. `maxChars` هر درخواست نیز میتواند توسط کلاینت ارسال شود تا این پیشفرض را برای یک فراخوانی `chat.history` منفرد بازنویسی کند.
|
||||
- `gateway.webchat.chatHistoryMaxChars`: حداکثر تعداد کاراکتر برای فیلدهای متنی در پاسخهای `chat.history`. وقتی یک ورودی رونوشت از این حد عبور کند، Gateway فیلدهای متنی طولانی را کوتاه میکند و ممکن است پیامهای بیشازحد بزرگ را با یک placeholder جایگزین کند. کلاینت همچنین میتواند `maxChars` را برای هر درخواست بفرستد تا این پیشفرض را برای یک فراخوانی `chat.history` بازنویسی کند.
|
||||
|
||||
گزینههای سراسری مرتبط:
|
||||
|
||||
- `gateway.port`، `gateway.bind`: میزبان/درگاه WebSocket.
|
||||
- `gateway.auth.mode`، `gateway.auth.token`، `gateway.auth.password`:
|
||||
احراز هویت WebSocket با shared-secret.
|
||||
- `gateway.auth.allowTailscale`: زبانه چت واسط کاربری کنترل در مرورگر میتواند هنگام فعال بودن از سرآیندهای هویت Tailscale
|
||||
- `gateway.auth.allowTailscale`: وقتی فعال باشد، زبانه چت Control UI در مرورگر میتواند از سرآیندهای هویت Tailscale
|
||||
Serve استفاده کند.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: احراز هویت reverse-proxy برای کلاینتهای مرورگر پشت یک منبع پراکسی **غیر loopback** آگاه از هویت (نگاه کنید به [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth)).
|
||||
- `gateway.auth.mode: "trusted-proxy"`: احراز هویت reverse-proxy برای کلاینتهای مرورگر پشت یک منبع پروکسی **غیر-loopback** آگاه از هویت (نگاه کنید به [احراز هویت پروکسی قابل اعتماد](/fa/gateway/trusted-proxy-auth)).
|
||||
- `gateway.remote.url`، `gateway.remote.token`، `gateway.remote.password`: هدف Gateway راه دور.
|
||||
- `session.*`: ذخیرهسازی نشست و پیشفرضهای کلید اصلی.
|
||||
- `session.*`: ذخیرهسازی جلسه و پیشفرضهای کلید اصلی.
|
||||
|
||||
## مرتبط
|
||||
|
||||
- [واسط کاربری کنترل](/fa/web/control-ui)
|
||||
- [Control UI](/fa/web/control-ui)
|
||||
- [داشبورد](/fa/web/dashboard)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user