durar-ai 2026.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (571) hide show
  1. package/CHANGELOG.md +5497 -0
  2. package/LICENSE +21 -0
  3. package/README.md +614 -0
  4. package/assets/avatar-placeholder.svg +19 -0
  5. package/assets/chrome-extension/icons/icon128.png +0 -0
  6. package/assets/chrome-extension/icons/icon16.png +0 -0
  7. package/assets/chrome-extension/icons/icon32.png +0 -0
  8. package/assets/chrome-extension/icons/icon48.png +0 -0
  9. package/assets/dmg-background-small.png +0 -0
  10. package/assets/dmg-background.png +0 -0
  11. package/docs/.i18n/README.md +72 -0
  12. package/docs/.i18n/ar-navigation.json +18 -0
  13. package/docs/.i18n/de-navigation.json +18 -0
  14. package/docs/.i18n/es-navigation.json +18 -0
  15. package/docs/.i18n/fr-navigation.json +18 -0
  16. package/docs/.i18n/glossary.ar.json +5 -0
  17. package/docs/.i18n/glossary.de.json +5 -0
  18. package/docs/.i18n/glossary.es.json +5 -0
  19. package/docs/.i18n/glossary.fr.json +5 -0
  20. package/docs/.i18n/glossary.id.json +5 -0
  21. package/docs/.i18n/glossary.it.json +5 -0
  22. package/docs/.i18n/glossary.ja-JP.json +14 -0
  23. package/docs/.i18n/glossary.ko.json +5 -0
  24. package/docs/.i18n/glossary.pl.json +5 -0
  25. package/docs/.i18n/glossary.pt-BR.json +5 -0
  26. package/docs/.i18n/glossary.tr.json +5 -0
  27. package/docs/.i18n/glossary.zh-CN.json +358 -0
  28. package/docs/.i18n/id-navigation.json +18 -0
  29. package/docs/.i18n/it-navigation.json +18 -0
  30. package/docs/.i18n/ja-navigation.json +18 -0
  31. package/docs/.i18n/ko-navigation.json +18 -0
  32. package/docs/.i18n/pl-navigation.json +18 -0
  33. package/docs/.i18n/pt-BR-navigation.json +18 -0
  34. package/docs/.i18n/tr-navigation.json +18 -0
  35. package/docs/.i18n/zh-Hans-navigation.json +544 -0
  36. package/docs/assets/install-script.svg +1 -0
  37. package/docs/assets/macos-onboarding/01-macos-warning.jpeg +0 -0
  38. package/docs/assets/macos-onboarding/02-local-networks.jpeg +0 -0
  39. package/docs/assets/macos-onboarding/03-security-notice.png +0 -0
  40. package/docs/assets/macos-onboarding/04-choose-gateway.png +0 -0
  41. package/docs/assets/macos-onboarding/05-permissions.png +0 -0
  42. package/docs/assets/openclaw-logo-text-dark.png +0 -0
  43. package/docs/assets/openclaw-logo-text-dark.svg +418 -0
  44. package/docs/assets/openclaw-logo-text.png +0 -0
  45. package/docs/assets/openclaw-logo-text.svg +418 -0
  46. package/docs/assets/pixel-lobster.svg +60 -0
  47. package/docs/assets/showcase/agents-ui.jpg +0 -0
  48. package/docs/assets/showcase/bambu-cli.png +0 -0
  49. package/docs/assets/showcase/codexmonitor.png +0 -0
  50. package/docs/assets/showcase/gohome-grafana.png +0 -0
  51. package/docs/assets/showcase/ios-testflight.jpg +0 -0
  52. package/docs/assets/showcase/oura-health.png +0 -0
  53. package/docs/assets/showcase/padel-cli.svg +11 -0
  54. package/docs/assets/showcase/padel-screenshot.jpg +0 -0
  55. package/docs/assets/showcase/papla-tts.jpg +0 -0
  56. package/docs/assets/showcase/pr-review-telegram.jpg +0 -0
  57. package/docs/assets/showcase/roborock-screenshot.jpg +0 -0
  58. package/docs/assets/showcase/roborock-status.svg +13 -0
  59. package/docs/assets/showcase/roof-camera-sky.jpg +0 -0
  60. package/docs/assets/showcase/snag.png +0 -0
  61. package/docs/assets/showcase/tesco-shop.jpg +0 -0
  62. package/docs/assets/showcase/wienerlinien.png +0 -0
  63. package/docs/assets/showcase/wine-cellar-skill.jpg +0 -0
  64. package/docs/assets/showcase/winix-air-purifier.jpg +0 -0
  65. package/docs/assets/showcase/xuezh-pronunciation.jpeg +0 -0
  66. package/docs/assets/sponsors/blacksmith-light.svg +14 -0
  67. package/docs/assets/sponsors/blacksmith.svg +14 -0
  68. package/docs/assets/sponsors/convex-light.svg +16 -0
  69. package/docs/assets/sponsors/convex.svg +16 -0
  70. package/docs/assets/sponsors/github-light.svg +3 -0
  71. package/docs/assets/sponsors/github.svg +3 -0
  72. package/docs/assets/sponsors/nvidia-dark.svg +9 -0
  73. package/docs/assets/sponsors/nvidia.svg +9 -0
  74. package/docs/assets/sponsors/openai-light.svg +3 -0
  75. package/docs/assets/sponsors/openai.svg +3 -0
  76. package/docs/assets/sponsors/vercel-light.svg +5 -0
  77. package/docs/assets/sponsors/vercel.svg +5 -0
  78. package/docs/auth-credential-semantics.md +80 -0
  79. package/docs/automation/auth-monitoring.md +8 -0
  80. package/docs/automation/clawflow.md +8 -0
  81. package/docs/automation/cron-jobs.md +410 -0
  82. package/docs/automation/cron-vs-heartbeat.md +8 -0
  83. package/docs/automation/gmail-pubsub.md +8 -0
  84. package/docs/automation/hooks.md +303 -0
  85. package/docs/automation/index.md +115 -0
  86. package/docs/automation/poll.md +8 -0
  87. package/docs/automation/standing-orders.md +254 -0
  88. package/docs/automation/taskflow.md +82 -0
  89. package/docs/automation/tasks.md +323 -0
  90. package/docs/automation/troubleshooting.md +8 -0
  91. package/docs/automation/webhook.md +8 -0
  92. package/docs/brave-search.md +103 -0
  93. package/docs/channels/bluebubbles.md +435 -0
  94. package/docs/channels/broadcast-groups.md +442 -0
  95. package/docs/channels/channel-routing.md +139 -0
  96. package/docs/channels/discord.md +1254 -0
  97. package/docs/channels/feishu.md +793 -0
  98. package/docs/channels/googlechat.md +270 -0
  99. package/docs/channels/group-messages.md +84 -0
  100. package/docs/channels/groups.md +410 -0
  101. package/docs/channels/imessage.md +427 -0
  102. package/docs/channels/index.md +50 -0
  103. package/docs/channels/irc.md +252 -0
  104. package/docs/channels/line.md +225 -0
  105. package/docs/channels/location.md +56 -0
  106. package/docs/channels/matrix.md +869 -0
  107. package/docs/channels/mattermost.md +472 -0
  108. package/docs/channels/msteams.md +805 -0
  109. package/docs/channels/nextcloud-talk.md +149 -0
  110. package/docs/channels/nostr.md +252 -0
  111. package/docs/channels/pairing.md +129 -0
  112. package/docs/channels/qqbot.md +193 -0
  113. package/docs/channels/signal.md +337 -0
  114. package/docs/channels/slack.md +681 -0
  115. package/docs/channels/synology-chat.md +185 -0
  116. package/docs/channels/telegram.md +1072 -0
  117. package/docs/channels/tlon.md +290 -0
  118. package/docs/channels/troubleshooting.md +133 -0
  119. package/docs/channels/twitch.md +394 -0
  120. package/docs/channels/whatsapp.md +488 -0
  121. package/docs/channels/zalo.md +254 -0
  122. package/docs/channels/zalouser.md +195 -0
  123. package/docs/ci.md +66 -0
  124. package/docs/cli/acp.md +316 -0
  125. package/docs/cli/agent.md +57 -0
  126. package/docs/cli/agents.md +220 -0
  127. package/docs/cli/approvals.md +136 -0
  128. package/docs/cli/backup.md +84 -0
  129. package/docs/cli/browser.md +233 -0
  130. package/docs/cli/channels.md +131 -0
  131. package/docs/cli/clawbot.md +21 -0
  132. package/docs/cli/completion.md +35 -0
  133. package/docs/cli/config.md +353 -0
  134. package/docs/cli/configure.md +70 -0
  135. package/docs/cli/cron.md +167 -0
  136. package/docs/cli/daemon.md +57 -0
  137. package/docs/cli/dashboard.md +22 -0
  138. package/docs/cli/devices.md +171 -0
  139. package/docs/cli/directory.md +63 -0
  140. package/docs/cli/dns.md +48 -0
  141. package/docs/cli/docs.md +28 -0
  142. package/docs/cli/doctor.md +63 -0
  143. package/docs/cli/flows.md +18 -0
  144. package/docs/cli/gateway.md +307 -0
  145. package/docs/cli/health.md +36 -0
  146. package/docs/cli/hooks.md +337 -0
  147. package/docs/cli/index.md +1836 -0
  148. package/docs/cli/logs.md +59 -0
  149. package/docs/cli/mcp.md +505 -0
  150. package/docs/cli/memory.md +139 -0
  151. package/docs/cli/message.md +300 -0
  152. package/docs/cli/models.md +136 -0
  153. package/docs/cli/node.md +137 -0
  154. package/docs/cli/nodes.md +66 -0
  155. package/docs/cli/onboard.md +171 -0
  156. package/docs/cli/pairing.md +65 -0
  157. package/docs/cli/plugins.md +305 -0
  158. package/docs/cli/qr.md +52 -0
  159. package/docs/cli/reset.md +35 -0
  160. package/docs/cli/sandbox.md +197 -0
  161. package/docs/cli/secrets.md +197 -0
  162. package/docs/cli/security.md +86 -0
  163. package/docs/cli/sessions.md +113 -0
  164. package/docs/cli/setup.md +45 -0
  165. package/docs/cli/skills.md +59 -0
  166. package/docs/cli/status.md +35 -0
  167. package/docs/cli/system.md +71 -0
  168. package/docs/cli/tui.md +30 -0
  169. package/docs/cli/uninstall.md +39 -0
  170. package/docs/cli/update.md +113 -0
  171. package/docs/cli/voicecall.md +34 -0
  172. package/docs/cli/webhooks.md +91 -0
  173. package/docs/concepts/agent-loop.md +168 -0
  174. package/docs/concepts/agent-workspace.md +246 -0
  175. package/docs/concepts/agent.md +129 -0
  176. package/docs/concepts/architecture.md +156 -0
  177. package/docs/concepts/compaction.md +122 -0
  178. package/docs/concepts/context-engine.md +274 -0
  179. package/docs/concepts/context.md +179 -0
  180. package/docs/concepts/delegate-architecture.md +307 -0
  181. package/docs/concepts/dreaming.md +173 -0
  182. package/docs/concepts/features.md +76 -0
  183. package/docs/concepts/markdown-formatting.md +130 -0
  184. package/docs/concepts/memory-builtin.md +105 -0
  185. package/docs/concepts/memory-honcho.md +140 -0
  186. package/docs/concepts/memory-qmd.md +163 -0
  187. package/docs/concepts/memory-search.md +141 -0
  188. package/docs/concepts/memory.md +121 -0
  189. package/docs/concepts/messages.md +161 -0
  190. package/docs/concepts/model-failover.md +349 -0
  191. package/docs/concepts/model-providers.md +799 -0
  192. package/docs/concepts/models.md +255 -0
  193. package/docs/concepts/multi-agent.md +615 -0
  194. package/docs/concepts/oauth.md +225 -0
  195. package/docs/concepts/presence.md +102 -0
  196. package/docs/concepts/queue.md +89 -0
  197. package/docs/concepts/retry.md +69 -0
  198. package/docs/concepts/session-pruning.md +92 -0
  199. package/docs/concepts/session-tool.md +141 -0
  200. package/docs/concepts/session.md +116 -0
  201. package/docs/concepts/soul.md +110 -0
  202. package/docs/concepts/streaming.md +161 -0
  203. package/docs/concepts/system-prompt.md +182 -0
  204. package/docs/concepts/timezone.md +97 -0
  205. package/docs/concepts/typebox.md +307 -0
  206. package/docs/concepts/typing-indicators.md +69 -0
  207. package/docs/concepts/usage-tracking.md +59 -0
  208. package/docs/date-time.md +128 -0
  209. package/docs/debug/node-issue.md +85 -0
  210. package/docs/diagnostics/flags.md +91 -0
  211. package/docs/docs.json +1601 -0
  212. package/docs/gateway/authentication.md +218 -0
  213. package/docs/gateway/background-process.md +131 -0
  214. package/docs/gateway/bonjour.md +179 -0
  215. package/docs/gateway/bridge-protocol.md +89 -0
  216. package/docs/gateway/cli-backends.md +310 -0
  217. package/docs/gateway/configuration-examples.md +631 -0
  218. package/docs/gateway/configuration-reference.md +3618 -0
  219. package/docs/gateway/configuration.md +698 -0
  220. package/docs/gateway/discovery.md +141 -0
  221. package/docs/gateway/doctor.md +494 -0
  222. package/docs/gateway/gateway-lock.md +37 -0
  223. package/docs/gateway/health.md +61 -0
  224. package/docs/gateway/heartbeat.md +443 -0
  225. package/docs/gateway/index.md +367 -0
  226. package/docs/gateway/local-models.md +163 -0
  227. package/docs/gateway/logging.md +113 -0
  228. package/docs/gateway/multiple-gateways.md +120 -0
  229. package/docs/gateway/network-model.md +25 -0
  230. package/docs/gateway/openai-http-api.md +280 -0
  231. package/docs/gateway/openresponses-http-api.md +340 -0
  232. package/docs/gateway/openshell.md +307 -0
  233. package/docs/gateway/pairing.md +138 -0
  234. package/docs/gateway/protocol.md +588 -0
  235. package/docs/gateway/remote-gateway-readme.md +164 -0
  236. package/docs/gateway/remote.md +251 -0
  237. package/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md +141 -0
  238. package/docs/gateway/sandboxing.md +473 -0
  239. package/docs/gateway/secrets-plan-contract.md +116 -0
  240. package/docs/gateway/secrets.md +541 -0
  241. package/docs/gateway/security/index.md +1362 -0
  242. package/docs/gateway/tailscale.md +136 -0
  243. package/docs/gateway/tools-invoke-http-api.md +161 -0
  244. package/docs/gateway/troubleshooting.md +451 -0
  245. package/docs/gateway/trusted-proxy-auth.md +399 -0
  246. package/docs/help/debugging.md +168 -0
  247. package/docs/help/environment.md +165 -0
  248. package/docs/help/faq.md +3244 -0
  249. package/docs/help/index.md +28 -0
  250. package/docs/help/scripts.md +27 -0
  251. package/docs/help/testing.md +640 -0
  252. package/docs/help/troubleshooting.md +372 -0
  253. package/docs/images/configure-model-picker-unsearchable.png +0 -0
  254. package/docs/images/feishu-step2-create-app.png +0 -0
  255. package/docs/images/feishu-step3-credentials.png +0 -0
  256. package/docs/images/feishu-step4-permissions.png +0 -0
  257. package/docs/images/feishu-step5-bot-capability.png +0 -0
  258. package/docs/images/feishu-step6-event-subscription.png +0 -0
  259. package/docs/images/feishu-verification-token.png +0 -0
  260. package/docs/images/groups-flow.svg +52 -0
  261. package/docs/images/mobile-ui-screenshot.png +0 -0
  262. package/docs/index.md +196 -0
  263. package/docs/install/ansible.md +230 -0
  264. package/docs/install/azure.md +311 -0
  265. package/docs/install/bun.md +55 -0
  266. package/docs/install/clawdock.md +106 -0
  267. package/docs/install/development-channels.md +131 -0
  268. package/docs/install/digitalocean.md +129 -0
  269. package/docs/install/docker-vm-runtime.md +142 -0
  270. package/docs/install/docker.md +412 -0
  271. package/docs/install/exe-dev.md +133 -0
  272. package/docs/install/fly.md +504 -0
  273. package/docs/install/gcp.md +412 -0
  274. package/docs/install/hetzner.md +259 -0
  275. package/docs/install/index.md +212 -0
  276. package/docs/install/installer.md +443 -0
  277. package/docs/install/kubernetes.md +192 -0
  278. package/docs/install/macos-vm.md +281 -0
  279. package/docs/install/migrating-matrix.md +349 -0
  280. package/docs/install/migrating.md +112 -0
  281. package/docs/install/nix.md +89 -0
  282. package/docs/install/node.md +144 -0
  283. package/docs/install/northflank.mdx +42 -0
  284. package/docs/install/oracle.md +158 -0
  285. package/docs/install/podman.md +210 -0
  286. package/docs/install/railway.mdx +90 -0
  287. package/docs/install/raspberry-pi.md +159 -0
  288. package/docs/install/render.mdx +165 -0
  289. package/docs/install/uninstall.md +128 -0
  290. package/docs/install/updating.md +142 -0
  291. package/docs/logging.md +389 -0
  292. package/docs/nav-tabs-underline.js +100 -0
  293. package/docs/network.md +69 -0
  294. package/docs/nodes/audio.md +191 -0
  295. package/docs/nodes/camera.md +162 -0
  296. package/docs/nodes/images.md +73 -0
  297. package/docs/nodes/index.md +408 -0
  298. package/docs/nodes/location-command.md +98 -0
  299. package/docs/nodes/media-understanding.md +432 -0
  300. package/docs/nodes/talk.md +92 -0
  301. package/docs/nodes/troubleshooting.md +123 -0
  302. package/docs/nodes/voicewake.md +66 -0
  303. package/docs/perplexity.md +181 -0
  304. package/docs/pi-dev.md +80 -0
  305. package/docs/pi.md +570 -0
  306. package/docs/platforms/android.md +244 -0
  307. package/docs/platforms/digitalocean.md +266 -0
  308. package/docs/platforms/index.md +55 -0
  309. package/docs/platforms/ios.md +223 -0
  310. package/docs/platforms/linux.md +100 -0
  311. package/docs/platforms/mac/bundled-gateway.md +75 -0
  312. package/docs/platforms/mac/canvas.md +125 -0
  313. package/docs/platforms/mac/child-process.md +69 -0
  314. package/docs/platforms/mac/dev-setup.md +107 -0
  315. package/docs/platforms/mac/health.md +34 -0
  316. package/docs/platforms/mac/icon.md +31 -0
  317. package/docs/platforms/mac/logging.md +57 -0
  318. package/docs/platforms/mac/menu-bar.md +81 -0
  319. package/docs/platforms/mac/peekaboo.md +65 -0
  320. package/docs/platforms/mac/permissions.md +50 -0
  321. package/docs/platforms/mac/remote.md +84 -0
  322. package/docs/platforms/mac/signing.md +47 -0
  323. package/docs/platforms/mac/skills.md +40 -0
  324. package/docs/platforms/mac/voice-overlay.md +60 -0
  325. package/docs/platforms/mac/voicewake.md +67 -0
  326. package/docs/platforms/mac/webchat.md +51 -0
  327. package/docs/platforms/mac/xpc.md +61 -0
  328. package/docs/platforms/macos.md +229 -0
  329. package/docs/platforms/oracle.md +305 -0
  330. package/docs/platforms/raspberry-pi.md +420 -0
  331. package/docs/platforms/windows.md +241 -0
  332. package/docs/plugins/agent-tools.md +10 -0
  333. package/docs/plugins/architecture.md +1609 -0
  334. package/docs/plugins/building-extensions.md +10 -0
  335. package/docs/plugins/building-plugins.md +319 -0
  336. package/docs/plugins/bundles.md +292 -0
  337. package/docs/plugins/community.md +149 -0
  338. package/docs/plugins/manifest.md +412 -0
  339. package/docs/plugins/sdk-channel-plugins.md +508 -0
  340. package/docs/plugins/sdk-entrypoints.md +210 -0
  341. package/docs/plugins/sdk-migration.md +359 -0
  342. package/docs/plugins/sdk-overview.md +475 -0
  343. package/docs/plugins/sdk-provider-plugins.md +712 -0
  344. package/docs/plugins/sdk-runtime.md +381 -0
  345. package/docs/plugins/sdk-setup.md +516 -0
  346. package/docs/plugins/sdk-testing.md +263 -0
  347. package/docs/plugins/voice-call.md +466 -0
  348. package/docs/plugins/zalouser.md +78 -0
  349. package/docs/prose.md +134 -0
  350. package/docs/providers/anthropic.md +402 -0
  351. package/docs/providers/bedrock-mantle.md +91 -0
  352. package/docs/providers/bedrock.md +273 -0
  353. package/docs/providers/chutes.md +103 -0
  354. package/docs/providers/claude-max-api-proxy.md +163 -0
  355. package/docs/providers/cloudflare-ai-gateway.md +71 -0
  356. package/docs/providers/deepgram.md +93 -0
  357. package/docs/providers/deepseek.md +53 -0
  358. package/docs/providers/fireworks.md +69 -0
  359. package/docs/providers/github-copilot.md +80 -0
  360. package/docs/providers/glm.md +68 -0
  361. package/docs/providers/google.md +149 -0
  362. package/docs/providers/groq.md +105 -0
  363. package/docs/providers/huggingface.md +193 -0
  364. package/docs/providers/index.md +81 -0
  365. package/docs/providers/kilocode.md +89 -0
  366. package/docs/providers/litellm.md +159 -0
  367. package/docs/providers/minimax.md +281 -0
  368. package/docs/providers/mistral.md +68 -0
  369. package/docs/providers/models.md +56 -0
  370. package/docs/providers/moonshot.md +224 -0
  371. package/docs/providers/nvidia.md +58 -0
  372. package/docs/providers/ollama.md +379 -0
  373. package/docs/providers/openai.md +472 -0
  374. package/docs/providers/opencode-go.md +45 -0
  375. package/docs/providers/opencode.md +68 -0
  376. package/docs/providers/openrouter.md +59 -0
  377. package/docs/providers/perplexity-provider.md +62 -0
  378. package/docs/providers/qianfan.md +90 -0
  379. package/docs/providers/qwen.md +128 -0
  380. package/docs/providers/qwen_modelstudio.md +137 -0
  381. package/docs/providers/sglang.md +115 -0
  382. package/docs/providers/stepfun.md +152 -0
  383. package/docs/providers/synthetic.md +101 -0
  384. package/docs/providers/together.md +70 -0
  385. package/docs/providers/venice.md +282 -0
  386. package/docs/providers/vercel-ai-gateway.md +60 -0
  387. package/docs/providers/vllm.md +103 -0
  388. package/docs/providers/volcengine.md +94 -0
  389. package/docs/providers/xai.md +94 -0
  390. package/docs/providers/xiaomi.md +89 -0
  391. package/docs/providers/zai.md +75 -0
  392. package/docs/reference/AGENTS.default.md +126 -0
  393. package/docs/reference/RELEASING.md +138 -0
  394. package/docs/reference/api-usage-costs.md +198 -0
  395. package/docs/reference/credits.md +30 -0
  396. package/docs/reference/device-models.md +47 -0
  397. package/docs/reference/memory-config.md +421 -0
  398. package/docs/reference/prompt-caching.md +344 -0
  399. package/docs/reference/rpc.md +43 -0
  400. package/docs/reference/secretref-credential-surface.md +148 -0
  401. package/docs/reference/secretref-user-supplied-credentials-matrix.json +607 -0
  402. package/docs/reference/session-management-compaction.md +352 -0
  403. package/docs/reference/templates/AGENTS.dev.md +84 -0
  404. package/docs/reference/templates/AGENTS.md +219 -0
  405. package/docs/reference/templates/BOOT.md +12 -0
  406. package/docs/reference/templates/BOOTSTRAP.md +62 -0
  407. package/docs/reference/templates/CLAUDE.md +1 -0
  408. package/docs/reference/templates/HEARTBEAT.md +14 -0
  409. package/docs/reference/templates/IDENTITY.dev.md +48 -0
  410. package/docs/reference/templates/IDENTITY.md +30 -0
  411. package/docs/reference/templates/SOUL.dev.md +77 -0
  412. package/docs/reference/templates/SOUL.md +45 -0
  413. package/docs/reference/templates/TOOLS.dev.md +25 -0
  414. package/docs/reference/templates/TOOLS.md +47 -0
  415. package/docs/reference/templates/USER.dev.md +19 -0
  416. package/docs/reference/templates/USER.md +24 -0
  417. package/docs/reference/test.md +119 -0
  418. package/docs/reference/token-use.md +197 -0
  419. package/docs/reference/transcript-hygiene.md +151 -0
  420. package/docs/reference/wizard.md +245 -0
  421. package/docs/security/CONTRIBUTING-THREAT-MODEL.md +98 -0
  422. package/docs/security/THREAT-MODEL-ATLAS.md +608 -0
  423. package/docs/security/formal-verification.md +167 -0
  424. package/docs/snippets/plugin-publish/minimal-openclaw.plugin.json +9 -0
  425. package/docs/snippets/plugin-publish/minimal-package.json +16 -0
  426. package/docs/start/bootstrapping.md +41 -0
  427. package/docs/start/docs-directory.md +67 -0
  428. package/docs/start/getting-started.md +148 -0
  429. package/docs/start/hubs.md +199 -0
  430. package/docs/start/lore.md +219 -0
  431. package/docs/start/onboarding-overview.md +69 -0
  432. package/docs/start/onboarding.md +92 -0
  433. package/docs/start/openclaw.md +225 -0
  434. package/docs/start/quickstart.md +22 -0
  435. package/docs/start/setup.md +172 -0
  436. package/docs/start/showcase.md +418 -0
  437. package/docs/start/wizard-cli-automation.md +233 -0
  438. package/docs/start/wizard-cli-reference.md +324 -0
  439. package/docs/start/wizard.md +127 -0
  440. package/docs/style.css +37 -0
  441. package/docs/tools/acp-agents.md +837 -0
  442. package/docs/tools/agent-send.md +100 -0
  443. package/docs/tools/apply-patch.md +52 -0
  444. package/docs/tools/brave-search.md +107 -0
  445. package/docs/tools/browser-linux-troubleshooting.md +145 -0
  446. package/docs/tools/browser-login.md +73 -0
  447. package/docs/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md +221 -0
  448. package/docs/tools/browser.md +890 -0
  449. package/docs/tools/btw.md +142 -0
  450. package/docs/tools/capability-cookbook.md +119 -0
  451. package/docs/tools/clawhub.md +348 -0
  452. package/docs/tools/code-execution.md +90 -0
  453. package/docs/tools/creating-skills.md +119 -0
  454. package/docs/tools/diffs.md +434 -0
  455. package/docs/tools/duckduckgo-search.md +102 -0
  456. package/docs/tools/elevated.md +116 -0
  457. package/docs/tools/exa-search.md +127 -0
  458. package/docs/tools/exec-approvals.md +635 -0
  459. package/docs/tools/exec.md +237 -0
  460. package/docs/tools/firecrawl.md +147 -0
  461. package/docs/tools/gemini-search.md +98 -0
  462. package/docs/tools/grok-search.md +102 -0
  463. package/docs/tools/image-generation.md +139 -0
  464. package/docs/tools/index.md +174 -0
  465. package/docs/tools/kimi-search.md +98 -0
  466. package/docs/tools/llm-task.md +119 -0
  467. package/docs/tools/lobster.md +348 -0
  468. package/docs/tools/loop-detection.md +100 -0
  469. package/docs/tools/minimax-search.md +99 -0
  470. package/docs/tools/multi-agent-sandbox-tools.md +373 -0
  471. package/docs/tools/ollama-search.md +100 -0
  472. package/docs/tools/pdf.md +176 -0
  473. package/docs/tools/perplexity-search.md +185 -0
  474. package/docs/tools/plugin.md +348 -0
  475. package/docs/tools/reactions.md +78 -0
  476. package/docs/tools/searxng-search.md +132 -0
  477. package/docs/tools/skills-config.md +133 -0
  478. package/docs/tools/skills.md +377 -0
  479. package/docs/tools/slash-commands.md +322 -0
  480. package/docs/tools/subagents.md +341 -0
  481. package/docs/tools/tavily.md +129 -0
  482. package/docs/tools/thinking.md +102 -0
  483. package/docs/tools/tts.md +452 -0
  484. package/docs/tools/web-fetch.md +159 -0
  485. package/docs/tools/web.md +417 -0
  486. package/docs/tts.md +452 -0
  487. package/docs/vps.md +115 -0
  488. package/docs/web/control-ui.md +318 -0
  489. package/docs/web/dashboard.md +93 -0
  490. package/docs/web/index.md +126 -0
  491. package/docs/web/tui.md +176 -0
  492. package/docs/web/webchat.md +77 -0
  493. package/docs/whatsapp-openclaw-ai-zh.jpg +0 -0
  494. package/docs/whatsapp-openclaw.jpg +0 -0
  495. package/durar.mjs +180 -0
  496. package/package.json +1259 -0
  497. package/scripts/npm-runner.mjs +111 -0
  498. package/scripts/postinstall-bundled-plugins.mjs +188 -0
  499. package/skills/1password/SKILL.md +70 -0
  500. package/skills/1password/references/cli-examples.md +29 -0
  501. package/skills/1password/references/get-started.md +17 -0
  502. package/skills/apple-notes/SKILL.md +77 -0
  503. package/skills/apple-reminders/SKILL.md +118 -0
  504. package/skills/bear-notes/SKILL.md +107 -0
  505. package/skills/blogwatcher/SKILL.md +69 -0
  506. package/skills/blucli/SKILL.md +47 -0
  507. package/skills/bluebubbles/SKILL.md +131 -0
  508. package/skills/camsnap/SKILL.md +45 -0
  509. package/skills/canvas/SKILL.md +199 -0
  510. package/skills/clawhub/SKILL.md +77 -0
  511. package/skills/coding-agent/SKILL.md +316 -0
  512. package/skills/discord/SKILL.md +197 -0
  513. package/skills/eightctl/SKILL.md +50 -0
  514. package/skills/gemini/SKILL.md +43 -0
  515. package/skills/gh-issues/SKILL.md +885 -0
  516. package/skills/gifgrep/SKILL.md +79 -0
  517. package/skills/github/SKILL.md +163 -0
  518. package/skills/gog/SKILL.md +116 -0
  519. package/skills/goplaces/SKILL.md +52 -0
  520. package/skills/healthcheck/SKILL.md +245 -0
  521. package/skills/himalaya/SKILL.md +257 -0
  522. package/skills/himalaya/references/configuration.md +184 -0
  523. package/skills/himalaya/references/message-composition.md +199 -0
  524. package/skills/imsg/SKILL.md +122 -0
  525. package/skills/mcporter/SKILL.md +61 -0
  526. package/skills/model-usage/SKILL.md +69 -0
  527. package/skills/model-usage/references/codexbar-cli.md +33 -0
  528. package/skills/model-usage/scripts/model_usage.py +320 -0
  529. package/skills/model-usage/scripts/test_model_usage.py +40 -0
  530. package/skills/nano-pdf/SKILL.md +38 -0
  531. package/skills/node-connect/SKILL.md +142 -0
  532. package/skills/notion/SKILL.md +174 -0
  533. package/skills/obsidian/SKILL.md +81 -0
  534. package/skills/openai-whisper/SKILL.md +38 -0
  535. package/skills/openai-whisper-api/SKILL.md +62 -0
  536. package/skills/openai-whisper-api/scripts/transcribe.sh +88 -0
  537. package/skills/openhue/SKILL.md +112 -0
  538. package/skills/oracle/SKILL.md +125 -0
  539. package/skills/ordercli/SKILL.md +78 -0
  540. package/skills/peekaboo/SKILL.md +190 -0
  541. package/skills/sag/SKILL.md +87 -0
  542. package/skills/session-logs/SKILL.md +151 -0
  543. package/skills/sherpa-onnx-tts/SKILL.md +109 -0
  544. package/skills/sherpa-onnx-tts/bin/sherpa-onnx-tts +178 -0
  545. package/skills/skill-creator/SKILL.md +372 -0
  546. package/skills/skill-creator/license.txt +202 -0
  547. package/skills/skill-creator/scripts/init_skill.py +378 -0
  548. package/skills/skill-creator/scripts/package_skill.py +139 -0
  549. package/skills/skill-creator/scripts/quick_validate.py +159 -0
  550. package/skills/skill-creator/scripts/test_package_skill.py +160 -0
  551. package/skills/skill-creator/scripts/test_quick_validate.py +72 -0
  552. package/skills/slack/SKILL.md +144 -0
  553. package/skills/songsee/SKILL.md +49 -0
  554. package/skills/sonoscli/SKILL.md +65 -0
  555. package/skills/spotify-player/SKILL.md +64 -0
  556. package/skills/summarize/SKILL.md +87 -0
  557. package/skills/taskflow/SKILL.md +149 -0
  558. package/skills/taskflow/examples/inbox-triage.lobster +33 -0
  559. package/skills/taskflow/examples/pr-intake.lobster +32 -0
  560. package/skills/taskflow-inbox-triage/SKILL.md +119 -0
  561. package/skills/things-mac/SKILL.md +86 -0
  562. package/skills/tmux/SKILL.md +170 -0
  563. package/skills/tmux/scripts/find-sessions.sh +112 -0
  564. package/skills/tmux/scripts/wait-for-text.sh +83 -0
  565. package/skills/trello/SKILL.md +108 -0
  566. package/skills/video-frames/SKILL.md +46 -0
  567. package/skills/video-frames/scripts/frame.sh +81 -0
  568. package/skills/voice-call/SKILL.md +45 -0
  569. package/skills/wacli/SKILL.md +72 -0
  570. package/skills/weather/SKILL.md +129 -0
  571. package/skills/xurl/SKILL.md +461 -0
@@ -0,0 +1,132 @@
1
+ ---
2
+ summary: "SearXNG web search -- self-hosted, key-free meta-search provider"
3
+ read_when:
4
+ - You want a self-hosted web search provider
5
+ - You want to use SearXNG for web_search
6
+ - You need a privacy-focused or air-gapped search option
7
+ title: "SearXNG Search"
8
+ ---
9
+
10
+ # SearXNG Search
11
+
12
+ Durar supports [SearXNG](https://docs.searxng.org/) as a **self-hosted,
13
+ key-free** `web_search` provider. SearXNG is an open-source meta-search engine
14
+ that aggregates results from Google, Bing, DuckDuckGo, and other sources.
15
+
16
+ Advantages:
17
+
18
+ - **Free and unlimited** -- no API key or commercial subscription required
19
+ - **Privacy / air-gap** -- queries never leave your network
20
+ - **Works anywhere** -- no region restrictions on commercial search APIs
21
+
22
+ ## Setup
23
+
24
+ <Steps>
25
+ <Step title="Run a SearXNG instance">
26
+ ```bash
27
+ docker run -d -p 8888:8080 searxng/searxng
28
+ ```
29
+
30
+ Or use any existing SearXNG deployment you have access to. See the
31
+ [SearXNG documentation](https://docs.searxng.org/) for production setup.
32
+
33
+ </Step>
34
+ <Step title="Configure">
35
+ ```bash
36
+ Durar configure --section web
37
+ # Select "searxng" as the provider
38
+ ```
39
+
40
+ Or set the env var and let auto-detection find it:
41
+
42
+ ```bash
43
+ export SEARXNG_BASE_URL="http://localhost:8888"
44
+ ```
45
+
46
+ </Step>
47
+ </Steps>
48
+
49
+ ## Config
50
+
51
+ ```json5
52
+ {
53
+ tools: {
54
+ web: {
55
+ search: {
56
+ provider: "searxng",
57
+ },
58
+ },
59
+ },
60
+ }
61
+ ```
62
+
63
+ Plugin-level settings for the SearXNG instance:
64
+
65
+ ```json5
66
+ {
67
+ plugins: {
68
+ entries: {
69
+ searxng: {
70
+ config: {
71
+ webSearch: {
72
+ baseUrl: "http://localhost:8888",
73
+ categories: "general,news", // optional
74
+ language: "en", // optional
75
+ },
76
+ },
77
+ },
78
+ },
79
+ },
80
+ }
81
+ ```
82
+
83
+ The `baseUrl` field also accepts SecretRef objects.
84
+
85
+ Transport rules:
86
+
87
+ - `https://` works for public or private SearXNG hosts
88
+ - `http://` is only accepted for trusted private-network or loopback hosts
89
+ - public SearXNG hosts must use `https://`
90
+
91
+ ## Environment variable
92
+
93
+ Set `SEARXNG_BASE_URL` as an alternative to config:
94
+
95
+ ```bash
96
+ export SEARXNG_BASE_URL="http://localhost:8888"
97
+ ```
98
+
99
+ When `SEARXNG_BASE_URL` is set and no explicit provider is configured, auto-detection
100
+ picks SearXNG automatically (at the lowest priority -- any API-backed provider with a
101
+ key wins first).
102
+
103
+ ## Plugin config reference
104
+
105
+ | Field | Description |
106
+ | ------------ | ------------------------------------------------------------------ |
107
+ | `baseUrl` | Base URL of your SearXNG instance (required) |
108
+ | `categories` | Comma-separated categories such as `general`, `news`, or `science` |
109
+ | `language` | Language code for results such as `en`, `de`, or `fr` |
110
+
111
+ ## Notes
112
+
113
+ - **JSON API** -- uses SearXNG's native `format=json` endpoint, not HTML scraping
114
+ - **No API key** -- works with any SearXNG instance out of the box
115
+ - **Base URL validation** -- `baseUrl` must be a valid `http://` or `https://`
116
+ URL; public hosts must use `https://`
117
+ - **Auto-detection order** -- SearXNG is checked last (order 200) in
118
+ auto-detection. API-backed providers with configured keys run first, then
119
+ DuckDuckGo (order 100), then Ollama Web Search (order 110)
120
+ - **Self-hosted** -- you control the instance, queries, and upstream search engines
121
+ - **Categories** default to `general` when not configured
122
+
123
+ <Tip>
124
+ For SearXNG JSON API to work, make sure your SearXNG instance has the `json`
125
+ format enabled in its `settings.yml` under `search.formats`.
126
+ </Tip>
127
+
128
+ ## Related
129
+
130
+ - [Web Search overview](/tools/web) -- all providers and auto-detection
131
+ - [DuckDuckGo Search](/tools/duckduckgo-search) -- another key-free fallback
132
+ - [Brave Search](/tools/brave-search) -- structured results with free tier
@@ -0,0 +1,133 @@
1
+ ---
2
+ summary: "Skills config schema and examples"
3
+ read_when:
4
+ - Adding or modifying skills config
5
+ - Adjusting bundled allowlist or install behavior
6
+ title: "Skills Config"
7
+ ---
8
+
9
+ # Skills Config
10
+
11
+ Most skills loader/install configuration lives under `skills` in
12
+ `~/.Durar/Durar.json`. Agent-specific skill visibility lives under
13
+ `agents.defaults.skills` and `agents.list[].skills`.
14
+
15
+ ```json5
16
+ {
17
+ skills: {
18
+ allowBundled: ["gemini", "peekaboo"],
19
+ load: {
20
+ extraDirs: ["~/Projects/agent-scripts/skills", "~/Projects/oss/some-skill-pack/skills"],
21
+ watch: true,
22
+ watchDebounceMs: 250,
23
+ },
24
+ install: {
25
+ preferBrew: true,
26
+ nodeManager: "npm", // npm | pnpm | yarn | bun (Gateway runtime still Node; bun not recommended)
27
+ },
28
+ entries: {
29
+ "image-lab": {
30
+ enabled: true,
31
+ apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
32
+ env: {
33
+ GEMINI_API_KEY: "GEMINI_KEY_HERE",
34
+ },
35
+ },
36
+ peekaboo: { enabled: true },
37
+ sag: { enabled: false },
38
+ },
39
+ },
40
+ }
41
+ ```
42
+
43
+ For built-in image generation/editing, prefer `agents.defaults.imageGenerationModel`
44
+ plus the core `image_generate` tool. `skills.entries.*` is only for custom or
45
+ third-party skill workflows.
46
+
47
+ If you select a specific image provider/model, also configure that provider's
48
+ auth/API key. Typical examples: `GEMINI_API_KEY` or `GOOGLE_API_KEY` for
49
+ `google/*`, `OPENAI_API_KEY` for `openai/*`, and `FAL_KEY` for `fal/*`.
50
+
51
+ Examples:
52
+
53
+ - Native Nano Banana-style setup: `agents.defaults.imageGenerationModel.primary: "google/gemini-3.1-flash-image-preview"`
54
+ - Native fal setup: `agents.defaults.imageGenerationModel.primary: "fal/fal-ai/flux/dev"`
55
+
56
+ ## Agent skill allowlists
57
+
58
+ Use agent config when you want the same machine/workspace skill roots, but a
59
+ different visible skill set per agent.
60
+
61
+ ```json5
62
+ {
63
+ agents: {
64
+ defaults: {
65
+ skills: ["github", "weather"],
66
+ },
67
+ list: [
68
+ { id: "writer" }, // inherits defaults -> github, weather
69
+ { id: "docs", skills: ["docs-search"] }, // replaces defaults
70
+ { id: "locked-down", skills: [] }, // no skills
71
+ ],
72
+ },
73
+ }
74
+ ```
75
+
76
+ Rules:
77
+
78
+ - `agents.defaults.skills`: shared baseline allowlist for agents that omit
79
+ `agents.list[].skills`.
80
+ - Omit `agents.defaults.skills` to leave skills unrestricted by default.
81
+ - `agents.list[].skills`: explicit final skill set for that agent; it does not
82
+ merge with defaults.
83
+ - `agents.list[].skills: []`: expose no skills for that agent.
84
+
85
+ ## Fields
86
+
87
+ - Built-in skill roots always include `~/.Durar/skills`, `~/.agents/skills`,
88
+ `<workspace>/.agents/skills`, and `<workspace>/skills`.
89
+ - `allowBundled`: optional allowlist for **bundled** skills only. When set, only
90
+ bundled skills in the list are eligible (managed, agent, and workspace skills unaffected).
91
+ - `load.extraDirs`: additional skill directories to scan (lowest precedence).
92
+ - `load.watch`: watch skill folders and refresh the skills snapshot (default: true).
93
+ - `load.watchDebounceMs`: debounce for skill watcher events in milliseconds (default: 250).
94
+ - `install.preferBrew`: prefer brew installers when available (default: true).
95
+ - `install.nodeManager`: node installer preference (`npm` | `pnpm` | `yarn` | `bun`, default: npm).
96
+ This only affects **skill installs**; the Gateway runtime should still be Node
97
+ (Bun not recommended for WhatsApp/Telegram).
98
+ - `Durar setup --node-manager` is narrower and currently accepts `npm`,
99
+ `pnpm`, or `bun`. Set `skills.install.nodeManager: "yarn"` manually if you
100
+ want Yarn-backed skill installs.
101
+ - `entries.<skillKey>`: per-skill overrides.
102
+ - `agents.defaults.skills`: optional default skill allowlist inherited by agents
103
+ that omit `agents.list[].skills`.
104
+ - `agents.list[].skills`: optional per-agent final skill allowlist; explicit
105
+ lists replace inherited defaults instead of merging.
106
+
107
+ Per-skill fields:
108
+
109
+ - `enabled`: set `false` to disable a skill even if it’s bundled/installed.
110
+ - `env`: environment variables injected for the agent run (only if not already set).
111
+ - `apiKey`: optional convenience for skills that declare a primary env var.
112
+ Supports plaintext string or SecretRef object (`{ source, provider, id }`).
113
+
114
+ ## Notes
115
+
116
+ - Keys under `entries` map to the skill name by default. If a skill defines
117
+ `metadata.Durar.skillKey`, use that key instead.
118
+ - Load precedence is `<workspace>/skills` → `<workspace>/.agents/skills` →
119
+ `~/.agents/skills` → `~/.Durar/skills` → bundled skills →
120
+ `skills.load.extraDirs`.
121
+ - Changes to skills are picked up on the next agent turn when the watcher is enabled.
122
+
123
+ ### Sandboxed skills + env vars
124
+
125
+ When a session is **sandboxed**, skill processes run inside Docker. The sandbox
126
+ does **not** inherit the host `process.env`.
127
+
128
+ Use one of:
129
+
130
+ - `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
131
+ - bake the env into your custom sandbox image
132
+
133
+ Global `env` and `skills.entries.<skill>.env/apiKey` apply to **host** runs only.
@@ -0,0 +1,377 @@
1
+ ---
2
+ summary: "Skills: managed vs workspace, gating rules, and config/env wiring"
3
+ read_when:
4
+ - Adding or modifying skills
5
+ - Changing skill gating or load rules
6
+ title: "Skills"
7
+ ---
8
+
9
+ # Skills (Durar)
10
+
11
+ Durar uses **[AgentSkills](https://agentskills.io)-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Durar loads **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence.
12
+
13
+ ## Locations and precedence
14
+
15
+ Durar loads skills from these sources:
16
+
17
+ 1. **Extra skill folders**: configured with `skills.load.extraDirs`
18
+ 2. **Bundled skills**: shipped with the install (npm package or Durar.app)
19
+ 3. **Managed/local skills**: `~/.Durar/skills`
20
+ 4. **Personal agent skills**: `~/.agents/skills`
21
+ 5. **Project agent skills**: `<workspace>/.agents/skills`
22
+ 6. **Workspace skills**: `<workspace>/skills`
23
+
24
+ If a skill name conflicts, precedence is:
25
+
26
+ `<workspace>/skills` (highest) → `<workspace>/.agents/skills` → `~/.agents/skills` → `~/.Durar/skills` → bundled skills → `skills.load.extraDirs` (lowest)
27
+
28
+ ## Per-agent vs shared skills
29
+
30
+ In **multi-agent** setups, each agent has its own workspace. That means:
31
+
32
+ - **Per-agent skills** live in `<workspace>/skills` for that agent only.
33
+ - **Project agent skills** live in `<workspace>/.agents/skills` and apply to
34
+ that workspace before the normal workspace `skills/` folder.
35
+ - **Personal agent skills** live in `~/.agents/skills` and apply across
36
+ workspaces on that machine.
37
+ - **Shared skills** live in `~/.Durar/skills` (managed/local) and are visible
38
+ to **all agents** on the same machine.
39
+ - **Shared folders** can also be added via `skills.load.extraDirs` (lowest
40
+ precedence) if you want a common skills pack used by multiple agents.
41
+
42
+ If the same skill name exists in more than one place, the usual precedence
43
+ applies: workspace wins, then project agent skills, then personal agent skills,
44
+ then managed/local, then bundled, then extra dirs.
45
+
46
+ ## Agent skill allowlists
47
+
48
+ Skill **location** and skill **visibility** are separate controls.
49
+
50
+ - Location/precedence decides which copy of a same-named skill wins.
51
+ - Agent allowlists decide which visible skills an agent can actually use.
52
+
53
+ Use `agents.defaults.skills` for a shared baseline, then override per agent with
54
+ `agents.list[].skills`:
55
+
56
+ ```json5
57
+ {
58
+ agents: {
59
+ defaults: {
60
+ skills: ["github", "weather"],
61
+ },
62
+ list: [
63
+ { id: "writer" }, // inherits github, weather
64
+ { id: "docs", skills: ["docs-search"] }, // replaces defaults
65
+ { id: "locked-down", skills: [] }, // no skills
66
+ ],
67
+ },
68
+ }
69
+ ```
70
+
71
+ Rules:
72
+
73
+ - Omit `agents.defaults.skills` for unrestricted skills by default.
74
+ - Omit `agents.list[].skills` to inherit `agents.defaults.skills`.
75
+ - Set `agents.list[].skills: []` for no skills.
76
+ - A non-empty `agents.list[].skills` list is the final set for that agent; it
77
+ does not merge with defaults.
78
+
79
+ Durar applies the effective agent skill set across prompt building, skill
80
+ slash-command discovery, sandbox sync, and skill snapshots.
81
+
82
+ ## Plugins + skills
83
+
84
+ Plugins can ship their own skills by listing `skills` directories in
85
+ `Durar.plugin.json` (paths relative to the plugin root). Plugin skills load
86
+ when the plugin is enabled. Today those directories are merged into the same
87
+ low-precedence path as `skills.load.extraDirs`, so a same-named bundled,
88
+ managed, agent, or workspace skill overrides them.
89
+ You can gate them via `metadata.Durar.requires.config` on the plugin’s config
90
+ entry. See [Plugins](/tools/plugin) for discovery/config and [Tools](/tools) for the
91
+ tool surface those skills teach.
92
+
93
+ ## Durar Gateway (install + sync)
94
+
95
+ Durar Gateway is the public skills registry for Durar. Browse at
96
+ [https://Durar Gateway.ai](https://Durar Gateway.ai). Use native `Durar skills`
97
+ commands to discover/install/update skills, or the separate `Durar Gateway` CLI when
98
+ you need publish/sync workflows.
99
+ Full guide: [Durar Gateway](/tools/Durar Gateway).
100
+
101
+ Common flows:
102
+
103
+ - Install a skill into your workspace:
104
+ - `Durar skills install <skill-slug>`
105
+ - Update all installed skills:
106
+ - `Durar skills update --all`
107
+ - Sync (scan + publish updates):
108
+ - `Durar Gateway sync --all`
109
+
110
+ Native `Durar skills install` installs into the active workspace `skills/`
111
+ directory. The separate `Durar Gateway` CLI also installs into `./skills` under your
112
+ current working directory (or falls back to the configured Durar workspace).
113
+ Durar picks that up as `<workspace>/skills` on the next session.
114
+
115
+ ## Security notes
116
+
117
+ - Treat third-party skills as **untrusted code**. Read them before enabling.
118
+ - Prefer sandboxed runs for untrusted inputs and risky tools. See [Sandboxing](/gateway/sandboxing).
119
+ - Workspace and extra-dir skill discovery only accepts skill roots and `SKILL.md` files whose resolved realpath stays inside the configured root.
120
+ - Gateway-backed skill dependency installs (`skills.install`, onboarding, and the Skills settings UI) run the built-in dangerous-code scanner before executing installer metadata. `critical` findings block by default unless the caller explicitly sets the dangerous override; suspicious findings still warn only.
121
+ - `Durar skills install <slug>` is different: it downloads a Durar Gateway skill folder into the workspace and does not use the installer-metadata path above.
122
+ - `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process
123
+ for that agent turn (not the sandbox). Keep secrets out of prompts and logs.
124
+ - For a broader threat model and checklists, see [Security](/gateway/security).
125
+
126
+ ## Format (AgentSkills + Pi-compatible)
127
+
128
+ `SKILL.md` must include at least:
129
+
130
+ ```markdown
131
+ ---
132
+ name: image-lab
133
+ description: Generate or edit images via a provider-backed image workflow
134
+ ---
135
+ ```
136
+
137
+ Notes:
138
+
139
+ - We follow the AgentSkills spec for layout/intent.
140
+ - The parser used by the embedded agent supports **single-line** frontmatter keys only.
141
+ - `metadata` should be a **single-line JSON object**.
142
+ - Use `{baseDir}` in instructions to reference the skill folder path.
143
+ - Optional frontmatter keys:
144
+ - `homepage` — URL surfaced as “Website” in the macOS Skills UI (also supported via `metadata.Durar.homepage`).
145
+ - `user-invocable` — `true|false` (default: `true`). When `true`, the skill is exposed as a user slash command.
146
+ - `disable-model-invocation` — `true|false` (default: `false`). When `true`, the skill is excluded from the model prompt (still available via user invocation).
147
+ - `command-dispatch` — `tool` (optional). When set to `tool`, the slash command bypasses the model and dispatches directly to a tool.
148
+ - `command-tool` — tool name to invoke when `command-dispatch: tool` is set.
149
+ - `command-arg-mode` — `raw` (default). For tool dispatch, forwards the raw args string to the tool (no core parsing).
150
+
151
+ The tool is invoked with params:
152
+ `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`.
153
+
154
+ ## Gating (load-time filters)
155
+
156
+ Durar **filters skills at load time** using `metadata` (single-line JSON):
157
+
158
+ ```markdown
159
+ ---
160
+ name: image-lab
161
+ description: Generate or edit images via a provider-backed image workflow
162
+ metadata:
163
+ {
164
+ "Durar":
165
+ {
166
+ "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },
167
+ "primaryEnv": "GEMINI_API_KEY",
168
+ },
169
+ }
170
+ ---
171
+ ```
172
+
173
+ Fields under `metadata.Durar`:
174
+
175
+ - `always: true` — always include the skill (skip other gates).
176
+ - `emoji` — optional emoji used by the macOS Skills UI.
177
+ - `homepage` — optional URL shown as “Website” in the macOS Skills UI.
178
+ - `os` — optional list of platforms (`darwin`, `linux`, `win32`). If set, the skill is only eligible on those OSes.
179
+ - `requires.bins` — list; each must exist on `PATH`.
180
+ - `requires.anyBins` — list; at least one must exist on `PATH`.
181
+ - `requires.env` — list; env var must exist **or** be provided in config.
182
+ - `requires.config` — list of `Durar.json` paths that must be truthy.
183
+ - `primaryEnv` — env var name associated with `skills.entries.<name>.apiKey`.
184
+ - `install` — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv/download).
185
+
186
+ Note on sandboxing:
187
+
188
+ - `requires.bins` is checked on the **host** at skill load time.
189
+ - If an agent is sandboxed, the binary must also exist **inside the container**.
190
+ Install it via `agents.defaults.sandbox.docker.setupCommand` (or a custom image).
191
+ `setupCommand` runs once after the container is created.
192
+ Package installs also require network egress, a writable root FS, and a root user in the sandbox.
193
+ Example: the `summarize` skill (`skills/summarize/SKILL.md`) needs the `summarize` CLI
194
+ in the sandbox container to run there.
195
+
196
+ Installer example:
197
+
198
+ ```markdown
199
+ ---
200
+ name: gemini
201
+ description: Use Gemini CLI for coding assistance and Google search lookups.
202
+ metadata:
203
+ {
204
+ "Durar":
205
+ {
206
+ "emoji": "♊️",
207
+ "requires": { "bins": ["gemini"] },
208
+ "install":
209
+ [
210
+ {
211
+ "id": "brew",
212
+ "kind": "brew",
213
+ "formula": "gemini-cli",
214
+ "bins": ["gemini"],
215
+ "label": "Install Gemini CLI (brew)",
216
+ },
217
+ ],
218
+ },
219
+ }
220
+ ---
221
+ ```
222
+
223
+ Notes:
224
+
225
+ - If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).
226
+ - If all installers are `download`, Durar lists each entry so you can see the available artifacts.
227
+ - Installer specs can include `os: ["darwin"|"linux"|"win32"]` to filter options by platform.
228
+ - Node installs honor `skills.install.nodeManager` in `Durar.json` (default: npm; options: npm/pnpm/yarn/bun).
229
+ This only affects **skill installs**; the Gateway runtime should still be Node
230
+ (Bun is not recommended for WhatsApp/Telegram).
231
+ - Gateway-backed installer selection is preference-driven, not node-only:
232
+ when install specs mix kinds, Durar prefers Homebrew when
233
+ `skills.install.preferBrew` is enabled and `brew` exists, then `uv`, then the
234
+ configured node manager, then other fallbacks like `go` or `download`.
235
+ - If every install spec is `download`, Durar surfaces all download options
236
+ instead of collapsing to one preferred installer.
237
+ - Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible.
238
+ - Download installs: `url` (required), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (default: auto when archive detected), `stripComponents`, `targetDir` (default: `~/.Durar/tools/<skillKey>`).
239
+
240
+ If no `metadata.Durar` is present, the skill is always eligible (unless
241
+ disabled in config or blocked by `skills.allowBundled` for bundled skills).
242
+
243
+ ## Config overrides (`~/.Durar/Durar.json`)
244
+
245
+ Bundled/managed skills can be toggled and supplied with env values:
246
+
247
+ ```json5
248
+ {
249
+ skills: {
250
+ entries: {
251
+ "image-lab": {
252
+ enabled: true,
253
+ apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
254
+ env: {
255
+ GEMINI_API_KEY: "GEMINI_KEY_HERE",
256
+ },
257
+ config: {
258
+ endpoint: "https://example.invalid",
259
+ model: "nano-pro",
260
+ },
261
+ },
262
+ peekaboo: { enabled: true },
263
+ sag: { enabled: false },
264
+ },
265
+ },
266
+ }
267
+ ```
268
+
269
+ Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).
270
+
271
+ If you want stock image generation/editing inside Durar itself, use the core
272
+ `image_generate` tool with `agents.defaults.imageGenerationModel` instead of a
273
+ bundled skill. Skill examples here are for custom or third-party workflows.
274
+
275
+ For native image analysis, use the `image` tool with `agents.defaults.imageModel`.
276
+ For native image generation/editing, use `image_generate` with
277
+ `agents.defaults.imageGenerationModel`. If you pick `openai/*`, `google/*`,
278
+ `fal/*`, or another provider-specific image model, add that provider's auth/API
279
+ key too.
280
+
281
+ Config keys match the **skill name** by default. If a skill defines
282
+ `metadata.Durar.skillKey`, use that key under `skills.entries`.
283
+
284
+ Rules:
285
+
286
+ - `enabled: false` disables the skill even if it’s bundled/installed.
287
+ - `env`: injected **only if** the variable isn’t already set in the process.
288
+ - `apiKey`: convenience for skills that declare `metadata.Durar.primaryEnv`.
289
+ Supports plaintext string or SecretRef object (`{ source, provider, id }`).
290
+ - `config`: optional bag for custom per-skill fields; custom keys must live here.
291
+ - `allowBundled`: optional allowlist for **bundled** skills only. If set, only
292
+ bundled skills in the list are eligible (managed/workspace skills unaffected).
293
+
294
+ ## Environment injection (per agent run)
295
+
296
+ When an agent run starts, Durar:
297
+
298
+ 1. Reads skill metadata.
299
+ 2. Applies any `skills.entries.<key>.env` or `skills.entries.<key>.apiKey` to
300
+ `process.env`.
301
+ 3. Builds the system prompt with **eligible** skills.
302
+ 4. Restores the original environment after the run ends.
303
+
304
+ This is **scoped to the agent run**, not a global shell environment.
305
+
306
+ ## Session snapshot (performance)
307
+
308
+ Durar snapshots the eligible skills **when a session starts** and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.
309
+
310
+ Skills can also refresh mid-session when the skills watcher is enabled or when a new eligible remote node appears (see below). Think of this as a **hot reload**: the refreshed list is picked up on the next agent turn.
311
+
312
+ If the effective agent skill allowlist changes for that session, Durar
313
+ refreshes the snapshot so the visible skills stay aligned with the current
314
+ agent.
315
+
316
+ ## Remote macOS nodes (Linux gateway)
317
+
318
+ If the Gateway is running on Linux but a **macOS node** is connected **with `system.run` allowed** (Exec approvals security not set to `deny`), Durar can treat macOS-only skills as eligible when the required binaries are present on that node. The agent should execute those skills via the `exec` tool with `host=node`.
319
+
320
+ This relies on the node reporting its command support and on a bin probe via `system.run`. If the macOS node goes offline later, the skills remain visible; invocations may fail until the node reconnects.
321
+
322
+ ## Skills watcher (auto-refresh)
323
+
324
+ By default, Durar watches skill folders and bumps the skills snapshot when `SKILL.md` files change. Configure this under `skills.load`:
325
+
326
+ ```json5
327
+ {
328
+ skills: {
329
+ load: {
330
+ watch: true,
331
+ watchDebounceMs: 250,
332
+ },
333
+ },
334
+ }
335
+ ```
336
+
337
+ ## Token impact (skills list)
338
+
339
+ When skills are eligible, Durar injects a compact XML list of available skills into the system prompt (via `formatSkillsForPrompt` in `pi-coding-agent`). The cost is deterministic:
340
+
341
+ - **Base overhead (only when ≥1 skill):** 195 characters.
342
+ - **Per skill:** 97 characters + the length of the XML-escaped `<name>`, `<description>`, and `<location>` values.
343
+
344
+ Formula (characters):
345
+
346
+ ```
347
+ total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
348
+ ```
349
+
350
+ Notes:
351
+
352
+ - XML escaping expands `& < > " '` into entities (`&amp;`, `&lt;`, etc.), increasing length.
353
+ - Token counts vary by model tokenizer. A rough OpenAI-style estimate is ~4 chars/token, so **97 chars ≈ 24 tokens** per skill plus your actual field lengths.
354
+
355
+ ## Managed skills lifecycle
356
+
357
+ Durar ships a baseline set of skills as **bundled skills** as part of the
358
+ install (npm package or Durar.app). `~/.Durar/skills` exists for local
359
+ overrides (for example, pinning/patching a skill without changing the bundled
360
+ copy). Workspace skills are user-owned and override both on name conflicts.
361
+
362
+ ## Config reference
363
+
364
+ See [Skills config](/tools/skills-config) for the full configuration schema.
365
+
366
+ ## Looking for more skills?
367
+
368
+ Browse [https://Durar Gateway.ai](https://Durar Gateway.ai).
369
+
370
+ ---
371
+
372
+ ## Related
373
+
374
+ - [Creating Skills](/tools/creating-skills) — building custom skills
375
+ - [Skills Config](/tools/skills-config) — skill configuration reference
376
+ - [Slash Commands](/tools/slash-commands) — all available slash commands
377
+ - [Plugins](/tools/plugin) — plugin system overview