From aaca615b6b1bd3b0844dbe4ddf3fe71b0adc2c0d Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 5 Apr 2026 15:54:45 +0100 Subject: [PATCH] chore(i18n): add it tr id pl translations --- docs/.i18n/id.tm.jsonl | 1 - docs/.i18n/it.tm.jsonl | 1 - docs/.i18n/pl.tm.jsonl | 1 - docs/.i18n/tr.tm.jsonl | 1 - docs/id/.i18n/README.md | 81 + docs/id/auth-credential-semantics.md | 87 + docs/id/automation/auth-monitoring.md | 15 + docs/id/automation/clawflow.md | 15 + docs/id/automation/cron-jobs.md | 414 +++ docs/id/automation/cron-vs-heartbeat.md | 15 + docs/id/automation/gmail-pubsub.md | 15 + docs/id/automation/hooks.md | 310 ++ docs/id/automation/index.md | 122 + docs/id/automation/poll.md | 15 + docs/id/automation/standing-orders.md | 261 ++ docs/id/automation/taskflow.md | 89 + docs/id/automation/tasks.md | 317 ++ docs/id/automation/troubleshooting.md | 15 + docs/id/automation/webhook.md | 15 + docs/id/brave-search.md | 110 + docs/id/channels/bluebubbles.md | 442 +++ docs/id/channels/broadcast-groups.md | 449 +++ docs/id/channels/channel-routing.md | 136 + docs/id/channels/discord.md | 1261 +++++++ docs/id/channels/feishu.md | 800 +++++ docs/id/channels/googlechat.md | 277 ++ docs/id/channels/group-messages.md | 91 + docs/id/channels/groups.md | 417 +++ docs/id/channels/imessage.md | 434 +++ docs/id/channels/index.md | 57 + docs/id/channels/irc.md | 259 ++ docs/id/channels/line.md | 232 ++ docs/id/channels/location.md | 63 + docs/id/channels/matrix.md | 870 +++++ docs/id/channels/mattermost.md | 479 +++ docs/id/channels/msteams.md | 810 +++++ docs/id/channels/nextcloud-talk.md | 156 + docs/id/channels/nostr.md | 259 ++ docs/id/channels/pairing.md | 136 + docs/id/channels/qqbot.md | 200 ++ docs/id/channels/signal.md | 344 ++ docs/id/channels/slack.md | 688 ++++ docs/id/channels/synology-chat.md | 192 ++ docs/id/channels/telegram.md | 1075 ++++++ docs/id/channels/tlon.md | 297 ++ docs/id/channels/troubleshooting.md | 140 + docs/id/channels/twitch.md | 401 +++ docs/id/channels/whatsapp.md | 495 +++ docs/id/channels/zalo.md | 261 ++ docs/id/channels/zalouser.md | 202 ++ docs/id/ci.md | 73 + docs/id/cli/acp.md | 293 ++ docs/id/cli/agent.md | 64 + docs/id/cli/agents.md | 227 ++ docs/id/cli/approvals.md | 143 + docs/id/cli/backup.md | 91 + docs/id/cli/browser.md | 240 ++ docs/id/cli/channels.md | 138 + docs/id/cli/clawbot.md | 28 + docs/id/cli/completion.md | 42 + docs/id/cli/config.md | 360 ++ docs/id/cli/configure.md | 75 + docs/id/cli/cron.md | 174 + docs/id/cli/daemon.md | 64 + docs/id/cli/dashboard.md | 29 + docs/id/cli/devices.md | 178 + docs/id/cli/directory.md | 69 + docs/id/cli/dns.md | 55 + docs/id/cli/docs.md | 35 + docs/id/cli/doctor.md | 70 + docs/id/cli/flows.md | 25 + docs/id/cli/gateway.md | 314 ++ docs/id/cli/health.md | 43 + docs/id/cli/hooks.md | 344 ++ docs/id/cli/index.md | 1828 ++++++++++ docs/id/cli/logs.md | 66 + docs/id/cli/mcp.md | 523 +++ docs/id/cli/memory.md | 142 + docs/id/cli/message.md | 307 ++ docs/id/cli/models.md | 142 + docs/id/cli/node.md | 144 + docs/id/cli/nodes.md | 73 + docs/id/cli/onboard.md | 178 + docs/id/cli/pairing.md | 72 + docs/id/cli/plugins.md | 304 ++ docs/id/cli/qr.md | 59 + docs/id/cli/reset.md | 42 + docs/id/cli/sandbox.md | 204 ++ docs/id/cli/secrets.md | 204 ++ docs/id/cli/security.md | 93 + docs/id/cli/sessions.md | 120 + docs/id/cli/setup.md | 52 + docs/id/cli/skills.md | 66 + docs/id/cli/status.md | 42 + docs/id/cli/system.md | 78 + docs/id/cli/tui.md | 37 + docs/id/cli/uninstall.md | 46 + docs/id/cli/update.md | 120 + docs/id/cli/voicecall.md | 41 + docs/id/cli/webhooks.md | 98 + docs/id/concepts/agent-loop.md | 175 + docs/id/concepts/agent-workspace.md | 253 ++ docs/id/concepts/agent.md | 136 + docs/id/concepts/architecture.md | 163 + docs/id/concepts/compaction.md | 128 + docs/id/concepts/context-engine.md | 281 ++ docs/id/concepts/context.md | 186 ++ docs/id/concepts/delegate-architecture.md | 310 ++ docs/id/concepts/features.md | 83 + docs/id/concepts/markdown-formatting.md | 137 + docs/id/concepts/memory-builtin.md | 112 + docs/id/concepts/memory-dreaming.md | 157 + docs/id/concepts/memory-honcho.md | 145 + docs/id/concepts/memory-qmd.md | 170 + docs/id/concepts/memory-search.md | 148 + docs/id/concepts/memory.md | 128 + docs/id/concepts/messages.md | 168 + docs/id/concepts/model-failover.md | 352 ++ docs/id/concepts/model-providers.md | 800 +++++ docs/id/concepts/models.md | 260 ++ docs/id/concepts/multi-agent.md | 622 ++++ docs/id/concepts/oauth.md | 228 ++ docs/id/concepts/presence.md | 109 + docs/id/concepts/queue.md | 96 + docs/id/concepts/retry.md | 76 + docs/id/concepts/session-pruning.md | 99 + docs/id/concepts/session-tool.md | 146 + docs/id/concepts/session.md | 123 + docs/id/concepts/soul.md | 118 + docs/id/concepts/streaming.md | 168 + docs/id/concepts/system-prompt.md | 189 ++ docs/id/concepts/timezone.md | 104 + docs/id/concepts/typebox.md | 311 ++ docs/id/concepts/typing-indicators.md | 76 + docs/id/concepts/usage-tracking.md | 66 + docs/id/date-time.md | 135 + docs/id/debug/node-issue.md | 92 + docs/id/diagnostics/flags.md | 98 + docs/id/gateway/authentication.md | 224 ++ docs/id/gateway/background-process.md | 131 + docs/id/gateway/bonjour.md | 186 ++ docs/id/gateway/bridge-protocol.md | 96 + docs/id/gateway/cli-backends.md | 317 ++ docs/id/gateway/configuration-examples.md | 638 ++++ docs/id/gateway/configuration-reference.md | 2974 +++++++++++++++++ docs/id/gateway/configuration.md | 704 ++++ docs/id/gateway/discovery.md | 148 + docs/id/gateway/doctor.md | 494 +++ docs/id/gateway/gateway-lock.md | 44 + docs/id/gateway/health.md | 68 + docs/id/gateway/heartbeat.md | 449 +++ docs/id/gateway/index.md | 374 +++ docs/id/gateway/local-models.md | 169 + docs/id/gateway/logging.md | 120 + docs/id/gateway/multiple-gateways.md | 127 + docs/id/gateway/network-model.md | 32 + docs/id/gateway/openai-http-api.md | 287 ++ docs/id/gateway/openresponses-http-api.md | 347 ++ docs/id/gateway/openshell.md | 312 ++ docs/id/gateway/pairing.md | 145 + docs/id/gateway/protocol.md | 575 ++++ docs/id/gateway/remote-gateway-readme.md | 171 + docs/id/gateway/remote.md | 254 ++ .../sandbox-vs-tool-policy-vs-elevated.md | 148 + docs/id/gateway/sandboxing.md | 480 +++ docs/id/gateway/secrets-plan-contract.md | 123 + docs/id/gateway/secrets.md | 548 +++ docs/id/gateway/security/index.md | 1349 ++++++++ docs/id/gateway/tailscale.md | 143 + docs/id/gateway/tools-invoke-http-api.md | 168 + docs/id/gateway/troubleshooting.md | 457 +++ docs/id/gateway/trusted-proxy-auth.md | 406 +++ docs/id/help/debugging.md | 174 + docs/id/help/environment.md | 172 + docs/id/help/faq.md | 2744 +++++++++++++++ docs/id/help/index.md | 35 + docs/id/help/scripts.md | 34 + docs/id/help/testing.md | 647 ++++ docs/id/help/troubleshooting.md | 378 +++ docs/id/index.md | 203 ++ docs/id/install/ansible.md | 237 ++ docs/id/install/azure.md | 318 ++ docs/id/install/bun.md | 62 + docs/id/install/clawdock.md | 113 + docs/id/install/development-channels.md | 137 + docs/id/install/digitalocean.md | 136 + docs/id/install/docker-vm-runtime.md | 149 + docs/id/install/docker.md | 418 +++ docs/id/install/exe-dev.md | 140 + docs/id/install/fly.md | 511 +++ docs/id/install/gcp.md | 418 +++ docs/id/install/hetzner.md | 266 ++ docs/id/install/index.md | 219 ++ docs/id/install/installer.md | 450 +++ docs/id/install/kubernetes.md | 199 ++ docs/id/install/macos-vm.md | 288 ++ docs/id/install/migrating-matrix.md | 356 ++ docs/id/install/migrating.md | 118 + docs/id/install/nix.md | 96 + docs/id/install/node.md | 151 + docs/id/install/northflank.mdx | 49 + docs/id/install/oracle.md | 165 + docs/id/install/podman.md | 216 ++ docs/id/install/railway.mdx | 97 + docs/id/install/raspberry-pi.md | 166 + docs/id/install/render.mdx | 172 + docs/id/install/uninstall.md | 135 + docs/id/install/updating.md | 149 + docs/id/logging.md | 396 +++ docs/id/network.md | 76 + docs/id/nodes/audio.md | 198 ++ docs/id/nodes/camera.md | 169 + docs/id/nodes/images.md | 80 + docs/id/nodes/index.md | 415 +++ docs/id/nodes/location-command.md | 105 + docs/id/nodes/media-understanding.md | 439 +++ docs/id/nodes/talk.md | 99 + docs/id/nodes/troubleshooting.md | 130 + docs/id/nodes/voicewake.md | 73 + docs/id/perplexity.md | 188 ++ docs/id/pi-dev.md | 87 + docs/id/pi.md | 577 ++++ docs/id/platforms/android.md | 250 ++ docs/id/platforms/digitalocean.md | 273 ++ docs/id/platforms/index.md | 62 + docs/id/platforms/ios.md | 228 ++ docs/id/platforms/linux.md | 107 + docs/id/platforms/mac/bundled-gateway.md | 82 + docs/id/platforms/mac/canvas.md | 132 + docs/id/platforms/mac/child-process.md | 76 + docs/id/platforms/mac/dev-setup.md | 114 + docs/id/platforms/mac/health.md | 41 + docs/id/platforms/mac/icon.md | 38 + docs/id/platforms/mac/logging.md | 64 + docs/id/platforms/mac/menu-bar.md | 88 + docs/id/platforms/mac/peekaboo.md | 72 + docs/id/platforms/mac/permissions.md | 57 + docs/id/platforms/mac/remote.md | 91 + docs/id/platforms/mac/signing.md | 54 + docs/id/platforms/mac/skills.md | 47 + docs/id/platforms/mac/voice-overlay.md | 67 + docs/id/platforms/mac/voicewake.md | 74 + docs/id/platforms/mac/webchat.md | 58 + docs/id/platforms/mac/xpc.md | 68 + docs/id/platforms/macos.md | 222 ++ docs/id/platforms/oracle.md | 312 ++ docs/id/platforms/raspberry-pi.md | 427 +++ docs/id/platforms/windows.md | 248 ++ docs/id/plugins/agent-tools.md | 17 + docs/id/plugins/architecture.md | 1587 +++++++++ docs/id/plugins/building-extensions.md | 17 + docs/id/plugins/building-plugins.md | 325 ++ docs/id/plugins/bundles.md | 299 ++ docs/id/plugins/community.md | 156 + docs/id/plugins/manifest.md | 414 +++ docs/id/plugins/sdk-channel-plugins.md | 514 +++ docs/id/plugins/sdk-entrypoints.md | 217 ++ docs/id/plugins/sdk-migration.md | 365 ++ docs/id/plugins/sdk-overview.md | 479 +++ docs/id/plugins/sdk-provider-plugins.md | 717 ++++ docs/id/plugins/sdk-runtime.md | 388 +++ docs/id/plugins/sdk-setup.md | 522 +++ docs/id/plugins/sdk-testing.md | 269 ++ docs/id/plugins/voice-call.md | 468 +++ docs/id/plugins/zalouser.md | 85 + docs/id/prose.md | 141 + docs/id/providers/anthropic.md | 407 +++ docs/id/providers/bedrock-mantle.md | 98 + docs/id/providers/bedrock.md | 280 ++ docs/id/providers/chutes.md | 109 + docs/id/providers/claude-max-api-proxy.md | 167 + docs/id/providers/cloudflare-ai-gateway.md | 78 + docs/id/providers/deepgram.md | 100 + docs/id/providers/deepseek.md | 60 + docs/id/providers/fireworks.md | 76 + docs/id/providers/github-copilot.md | 87 + docs/id/providers/glm.md | 75 + docs/id/providers/google.md | 156 + docs/id/providers/groq.md | 111 + docs/id/providers/huggingface.md | 200 ++ docs/id/providers/index.md | 88 + docs/id/providers/kilocode.md | 96 + docs/id/providers/litellm.md | 164 + docs/id/providers/minimax.md | 287 ++ docs/id/providers/mistral.md | 75 + docs/id/providers/models.md | 63 + docs/id/providers/moonshot.md | 230 ++ docs/id/providers/nvidia.md | 65 + docs/id/providers/ollama.md | 386 +++ docs/id/providers/openai.md | 475 +++ docs/id/providers/opencode-go.md | 52 + docs/id/providers/opencode.md | 75 + docs/id/providers/openrouter.md | 66 + docs/id/providers/perplexity-provider.md | 69 + docs/id/providers/qianfan.md | 97 + docs/id/providers/qwen.md | 137 + docs/id/providers/qwen_modelstudio.md | 146 + docs/id/providers/sglang.md | 121 + docs/id/providers/stepfun.md | 158 + docs/id/providers/synthetic.md | 108 + docs/id/providers/together.md | 77 + docs/id/providers/venice.md | 289 ++ docs/id/providers/vercel-ai-gateway.md | 67 + docs/id/providers/vllm.md | 107 + docs/id/providers/volcengine.md | 100 + docs/id/providers/xai.md | 101 + docs/id/providers/xiaomi.md | 96 + docs/id/providers/zai.md | 82 + docs/id/reference/AGENTS.default.md | 133 + docs/id/reference/RELEASING.md | 145 + docs/id/reference/api-usage-costs.md | 202 ++ docs/id/reference/credits.md | 37 + docs/id/reference/device-models.md | 54 + docs/id/reference/memory-config.md | 425 +++ docs/id/reference/prompt-caching.md | 345 ++ docs/id/reference/rpc.md | 50 + .../reference/secretref-credential-surface.md | 155 + .../session-management-compaction.md | 358 ++ docs/id/reference/templates/AGENTS.dev.md | 91 + docs/id/reference/templates/AGENTS.md | 226 ++ docs/id/reference/templates/BOOT.md | 19 + docs/id/reference/templates/BOOTSTRAP.md | 69 + docs/id/reference/templates/CLAUDE.md | 226 ++ docs/id/reference/templates/HEARTBEAT.md | 21 + docs/id/reference/templates/IDENTITY.dev.md | 55 + docs/id/reference/templates/IDENTITY.md | 37 + docs/id/reference/templates/SOUL.dev.md | 84 + docs/id/reference/templates/SOUL.md | 52 + docs/id/reference/templates/TOOLS.dev.md | 32 + docs/id/reference/templates/TOOLS.md | 54 + docs/id/reference/templates/USER.dev.md | 26 + docs/id/reference/templates/USER.md | 31 + docs/id/reference/test.md | 126 + docs/id/reference/token-use.md | 202 ++ docs/id/reference/transcript-hygiene.md | 158 + docs/id/reference/wizard.md | 252 ++ docs/id/security/CONTRIBUTING-THREAT-MODEL.md | 105 + docs/id/security/THREAT-MODEL-ATLAS.md | 615 ++++ docs/id/security/formal-verification.md | 174 + docs/id/start/bootstrapping.md | 48 + docs/id/start/docs-directory.md | 74 + docs/id/start/getting-started.md | 155 + docs/id/start/hubs.md | 206 ++ docs/id/start/lore.md | 226 ++ docs/id/start/onboarding-overview.md | 76 + docs/id/start/onboarding.md | 99 + docs/id/start/openclaw.md | 232 ++ docs/id/start/quickstart.md | 29 + docs/id/start/setup.md | 178 + docs/id/start/showcase.md | 425 +++ docs/id/start/wizard-cli-automation.md | 240 ++ docs/id/start/wizard-cli-reference.md | 331 ++ docs/id/start/wizard.md | 134 + docs/id/tools/acp-agents.md | 841 +++++ docs/id/tools/agent-send.md | 107 + docs/id/tools/apply-patch.md | 59 + docs/id/tools/brave-search.md | 114 + .../id/tools/browser-linux-troubleshooting.md | 152 + docs/id/tools/browser-login.md | 80 + ...wsl2-windows-remote-cdp-troubleshooting.md | 227 ++ docs/id/tools/browser.md | 892 +++++ docs/id/tools/btw.md | 149 + docs/id/tools/capability-cookbook.md | 125 + docs/id/tools/clawhub.md | 354 ++ docs/id/tools/code-execution.md | 97 + docs/id/tools/creating-skills.md | 126 + docs/id/tools/diffs.md | 441 +++ docs/id/tools/duckduckgo-search.md | 109 + docs/id/tools/elevated.md | 123 + docs/id/tools/exa-search.md | 133 + docs/id/tools/exec-approvals.md | 562 ++++ docs/id/tools/exec.md | 243 ++ docs/id/tools/firecrawl.md | 154 + docs/id/tools/gemini-search.md | 105 + docs/id/tools/grok-search.md | 109 + docs/id/tools/image-generation.md | 146 + docs/id/tools/index.md | 181 + docs/id/tools/kimi-search.md | 105 + docs/id/tools/llm-task.md | 126 + docs/id/tools/lobster.md | 355 ++ docs/id/tools/loop-detection.md | 107 + docs/id/tools/minimax-search.md | 106 + docs/id/tools/multi-agent-sandbox-tools.md | 380 +++ docs/id/tools/ollama-search.md | 107 + docs/id/tools/pdf.md | 182 + docs/id/tools/perplexity-search.md | 192 ++ docs/id/tools/plugin.md | 353 ++ docs/id/tools/reactions.md | 85 + docs/id/tools/searxng-search.md | 139 + docs/id/tools/skills-config.md | 140 + docs/id/tools/skills.md | 380 +++ docs/id/tools/slash-commands.md | 328 ++ docs/id/tools/subagents.md | 348 ++ docs/id/tools/tavily.md | 136 + docs/id/tools/thinking.md | 109 + docs/id/tools/tts.md | 457 +++ docs/id/tools/web-fetch.md | 166 + docs/id/tools/web.md | 424 +++ docs/id/tts.md | 459 +++ docs/id/vps.md | 122 + docs/id/web/control-ui.md | 325 ++ docs/id/web/dashboard.md | 99 + docs/id/web/index.md | 133 + docs/id/web/tui.md | 183 + docs/id/web/webchat.md | 84 + docs/it/.i18n/README.md | 81 + docs/it/auth-credential-semantics.md | 87 + docs/it/automation/auth-monitoring.md | 15 + docs/it/automation/clawflow.md | 15 + docs/it/automation/cron-jobs.md | 417 +++ docs/it/automation/cron-vs-heartbeat.md | 15 + docs/it/automation/gmail-pubsub.md | 15 + docs/it/automation/hooks.md | 310 ++ docs/it/automation/index.md | 122 + docs/it/automation/poll.md | 15 + docs/it/automation/standing-orders.md | 261 ++ docs/it/automation/taskflow.md | 89 + docs/it/automation/tasks.md | 317 ++ docs/it/automation/troubleshooting.md | 15 + docs/it/automation/webhook.md | 15 + docs/it/brave-search.md | 110 + docs/it/channels/bluebubbles.md | 442 +++ docs/it/channels/broadcast-groups.md | 449 +++ docs/it/channels/channel-routing.md | 135 + docs/it/channels/discord.md | 1261 +++++++ docs/it/channels/feishu.md | 800 +++++ docs/it/channels/googlechat.md | 277 ++ docs/it/channels/group-messages.md | 91 + docs/it/channels/groups.md | 417 +++ docs/it/channels/imessage.md | 434 +++ docs/it/channels/index.md | 57 + docs/it/channels/irc.md | 259 ++ docs/it/channels/line.md | 232 ++ docs/it/channels/location.md | 63 + docs/it/channels/matrix.md | 870 +++++ docs/it/channels/mattermost.md | 477 +++ docs/it/channels/msteams.md | 812 +++++ docs/it/channels/nextcloud-talk.md | 154 + docs/it/channels/nostr.md | 259 ++ docs/it/channels/pairing.md | 136 + docs/it/channels/qqbot.md | 200 ++ docs/it/channels/signal.md | 344 ++ docs/it/channels/slack.md | 688 ++++ docs/it/channels/synology-chat.md | 192 ++ docs/it/channels/telegram.md | 1079 ++++++ docs/it/channels/tlon.md | 297 ++ docs/it/channels/troubleshooting.md | 140 + docs/it/channels/twitch.md | 398 +++ docs/it/channels/whatsapp.md | 495 +++ docs/it/channels/zalo.md | 261 ++ docs/it/channels/zalouser.md | 200 ++ docs/it/ci.md | 73 + docs/it/cli/acp.md | 292 ++ docs/it/cli/agent.md | 64 + docs/it/cli/agents.md | 227 ++ docs/it/cli/approvals.md | 143 + docs/it/cli/backup.md | 91 + docs/it/cli/browser.md | 240 ++ docs/it/cli/channels.md | 138 + docs/it/cli/clawbot.md | 28 + docs/it/cli/completion.md | 42 + docs/it/cli/config.md | 360 ++ docs/it/cli/configure.md | 66 + docs/it/cli/cron.md | 173 + docs/it/cli/daemon.md | 64 + docs/it/cli/dashboard.md | 29 + docs/it/cli/devices.md | 179 + docs/it/cli/directory.md | 70 + docs/it/cli/dns.md | 55 + docs/it/cli/docs.md | 35 + docs/it/cli/doctor.md | 70 + docs/it/cli/flows.md | 25 + docs/it/cli/gateway.md | 314 ++ docs/it/cli/health.md | 43 + docs/it/cli/hooks.md | 334 ++ docs/it/cli/index.md | 1833 ++++++++++ docs/it/cli/logs.md | 66 + docs/it/cli/mcp.md | 509 +++ docs/it/cli/memory.md | 142 + docs/it/cli/message.md | 307 ++ docs/it/cli/models.md | 143 + docs/it/cli/node.md | 144 + docs/it/cli/nodes.md | 73 + docs/it/cli/onboard.md | 169 + docs/it/cli/pairing.md | 72 + docs/it/cli/plugins.md | 237 ++ docs/it/cli/qr.md | 59 + docs/it/cli/reset.md | 42 + docs/it/cli/sandbox.md | 204 ++ docs/it/cli/secrets.md | 204 ++ docs/it/cli/security.md | 93 + docs/it/cli/sessions.md | 121 + docs/it/cli/setup.md | 52 + docs/it/cli/skills.md | 66 + docs/it/cli/status.md | 42 + docs/it/cli/system.md | 78 + docs/it/cli/tui.md | 37 + docs/it/cli/uninstall.md | 46 + docs/it/cli/update.md | 120 + docs/it/cli/voicecall.md | 41 + docs/it/cli/webhooks.md | 98 + docs/it/concepts/agent-loop.md | 176 + docs/it/concepts/agent-workspace.md | 253 ++ docs/it/concepts/agent.md | 135 + docs/it/concepts/architecture.md | 163 + docs/it/concepts/compaction.md | 129 + docs/it/concepts/context-engine.md | 281 ++ docs/it/concepts/context.md | 186 ++ docs/it/concepts/delegate-architecture.md | 309 ++ docs/it/concepts/features.md | 83 + docs/it/concepts/markdown-formatting.md | 138 + docs/it/concepts/memory-builtin.md | 112 + docs/it/concepts/memory-dreaming.md | 158 + docs/it/concepts/memory-honcho.md | 146 + docs/it/concepts/memory-qmd.md | 166 + docs/it/concepts/memory-search.md | 147 + docs/it/concepts/memory.md | 128 + docs/it/concepts/messages.md | 168 + docs/it/concepts/model-failover.md | 352 ++ docs/it/concepts/model-providers.md | 799 +++++ docs/it/concepts/models.md | 260 ++ docs/it/concepts/multi-agent.md | 622 ++++ docs/it/concepts/oauth.md | 231 ++ docs/it/concepts/presence.md | 109 + docs/it/concepts/queue.md | 96 + docs/it/concepts/retry.md | 76 + docs/it/concepts/session-pruning.md | 96 + docs/it/concepts/session-tool.md | 148 + docs/it/concepts/session.md | 123 + docs/it/concepts/soul.md | 117 + docs/it/concepts/streaming.md | 168 + docs/it/concepts/system-prompt.md | 187 ++ docs/it/concepts/timezone.md | 104 + docs/it/concepts/typebox.md | 313 ++ docs/it/concepts/typing-indicators.md | 76 + docs/it/concepts/usage-tracking.md | 66 + docs/it/date-time.md | 135 + docs/it/debug/node-issue.md | 92 + docs/it/diagnostics/flags.md | 98 + docs/it/gateway/authentication.md | 224 ++ docs/it/gateway/background-process.md | 131 + docs/it/gateway/bonjour.md | 186 ++ docs/it/gateway/bridge-protocol.md | 96 + docs/it/gateway/cli-backends.md | 316 ++ docs/it/gateway/configuration-examples.md | 638 ++++ docs/it/gateway/configuration-reference.md | 2817 ++++++++++++++++ docs/it/gateway/configuration.md | 702 ++++ docs/it/gateway/discovery.md | 148 + docs/it/gateway/doctor.md | 498 +++ docs/it/gateway/gateway-lock.md | 44 + docs/it/gateway/health.md | 63 + docs/it/gateway/heartbeat.md | 450 +++ docs/it/gateway/index.md | 372 +++ docs/it/gateway/local-models.md | 169 + docs/it/gateway/logging.md | 120 + docs/it/gateway/multiple-gateways.md | 127 + docs/it/gateway/network-model.md | 32 + docs/it/gateway/openai-http-api.md | 287 ++ docs/it/gateway/openresponses-http-api.md | 347 ++ docs/it/gateway/openshell.md | 313 ++ docs/it/gateway/pairing.md | 145 + docs/it/gateway/protocol.md | 585 ++++ docs/it/gateway/remote-gateway-readme.md | 171 + docs/it/gateway/remote.md | 257 ++ .../sandbox-vs-tool-policy-vs-elevated.md | 147 + docs/it/gateway/sandboxing.md | 479 +++ docs/it/gateway/secrets-plan-contract.md | 123 + docs/it/gateway/secrets.md | 548 +++ docs/it/gateway/security/index.md | 1353 ++++++++ docs/it/gateway/tailscale.md | 140 + docs/it/gateway/tools-invoke-http-api.md | 168 + docs/it/gateway/troubleshooting.md | 457 +++ docs/it/gateway/trusted-proxy-auth.md | 406 +++ docs/it/help/debugging.md | 175 + docs/it/help/environment.md | 172 + docs/it/help/faq.md | 2532 ++++++++++++++ docs/it/help/index.md | 35 + docs/it/help/scripts.md | 34 + docs/it/help/testing.md | 647 ++++ docs/it/help/troubleshooting.md | 371 ++ docs/it/index.md | 203 ++ docs/it/install/ansible.md | 237 ++ docs/it/install/azure.md | 318 ++ docs/it/install/bun.md | 62 + docs/it/install/clawdock.md | 113 + docs/it/install/development-channels.md | 136 + docs/it/install/digitalocean.md | 136 + docs/it/install/docker-vm-runtime.md | 149 + docs/it/install/docker.md | 416 +++ docs/it/install/exe-dev.md | 140 + docs/it/install/fly.md | 511 +++ docs/it/install/gcp.md | 419 +++ docs/it/install/hetzner.md | 266 ++ docs/it/install/index.md | 219 ++ docs/it/install/installer.md | 450 +++ docs/it/install/kubernetes.md | 199 ++ docs/it/install/macos-vm.md | 288 ++ docs/it/install/migrating-matrix.md | 353 ++ docs/it/install/migrating.md | 119 + docs/it/install/nix.md | 96 + docs/it/install/node.md | 151 + docs/it/install/northflank.mdx | 49 + docs/it/install/oracle.md | 165 + docs/it/install/podman.md | 216 ++ docs/it/install/railway.mdx | 97 + docs/it/install/raspberry-pi.md | 166 + docs/it/install/render.mdx | 171 + docs/it/install/uninstall.md | 135 + docs/it/install/updating.md | 149 + docs/it/logging.md | 396 +++ docs/it/network.md | 74 + docs/it/nodes/audio.md | 198 ++ docs/it/nodes/camera.md | 168 + docs/it/nodes/images.md | 80 + docs/it/nodes/index.md | 412 +++ docs/it/nodes/location-command.md | 105 + docs/it/nodes/media-understanding.md | 422 +++ docs/it/nodes/talk.md | 99 + docs/it/nodes/troubleshooting.md | 127 + docs/it/nodes/voicewake.md | 73 + docs/it/perplexity.md | 188 ++ docs/it/pi-dev.md | 87 + docs/it/pi.md | 577 ++++ docs/it/platforms/android.md | 251 ++ docs/it/platforms/digitalocean.md | 273 ++ docs/it/platforms/index.md | 62 + docs/it/platforms/ios.md | 229 ++ docs/it/platforms/linux.md | 107 + docs/it/platforms/mac/bundled-gateway.md | 82 + docs/it/platforms/mac/canvas.md | 131 + docs/it/platforms/mac/child-process.md | 76 + docs/it/platforms/mac/dev-setup.md | 114 + docs/it/platforms/mac/health.md | 41 + docs/it/platforms/mac/icon.md | 38 + docs/it/platforms/mac/logging.md | 64 + docs/it/platforms/mac/menu-bar.md | 88 + docs/it/platforms/mac/peekaboo.md | 70 + docs/it/platforms/mac/permissions.md | 56 + docs/it/platforms/mac/remote.md | 91 + docs/it/platforms/mac/signing.md | 54 + docs/it/platforms/mac/skills.md | 47 + docs/it/platforms/mac/voice-overlay.md | 67 + docs/it/platforms/mac/voicewake.md | 74 + docs/it/platforms/mac/webchat.md | 58 + docs/it/platforms/mac/xpc.md | 68 + docs/it/platforms/macos.md | 222 ++ docs/it/platforms/oracle.md | 312 ++ docs/it/platforms/raspberry-pi.md | 427 +++ docs/it/platforms/windows.md | 248 ++ docs/it/plugins/agent-tools.md | 17 + docs/it/plugins/architecture.md | 1553 +++++++++ docs/it/plugins/building-extensions.md | 17 + docs/it/plugins/building-plugins.md | 326 ++ docs/it/plugins/bundles.md | 288 ++ docs/it/plugins/community.md | 155 + docs/it/plugins/manifest.md | 411 +++ docs/it/plugins/sdk-channel-plugins.md | 499 +++ docs/it/plugins/sdk-entrypoints.md | 214 ++ docs/it/plugins/sdk-migration.md | 366 ++ docs/it/plugins/sdk-overview.md | 480 +++ docs/it/plugins/sdk-provider-plugins.md | 718 ++++ docs/it/plugins/sdk-runtime.md | 387 +++ docs/it/plugins/sdk-setup.md | 518 +++ docs/it/plugins/sdk-testing.md | 269 ++ docs/it/plugins/voice-call.md | 471 +++ docs/it/plugins/zalouser.md | 85 + docs/it/prose.md | 141 + docs/it/providers/anthropic.md | 405 +++ docs/it/providers/bedrock-mantle.md | 98 + docs/it/providers/bedrock.md | 279 ++ docs/it/providers/chutes.md | 108 + docs/it/providers/claude-max-api-proxy.md | 166 + docs/it/providers/cloudflare-ai-gateway.md | 78 + docs/it/providers/deepgram.md | 100 + docs/it/providers/deepseek.md | 60 + docs/it/providers/fireworks.md | 76 + docs/it/providers/github-copilot.md | 87 + docs/it/providers/glm.md | 75 + docs/it/providers/google.md | 156 + docs/it/providers/groq.md | 110 + docs/it/providers/huggingface.md | 200 ++ docs/it/providers/index.md | 88 + docs/it/providers/kilocode.md | 96 + docs/it/providers/litellm.md | 164 + docs/it/providers/minimax.md | 286 ++ docs/it/providers/mistral.md | 75 + docs/it/providers/models.md | 63 + docs/it/providers/moonshot.md | 230 ++ docs/it/providers/nvidia.md | 65 + docs/it/providers/ollama.md | 384 +++ docs/it/providers/openai.md | 471 +++ docs/it/providers/opencode-go.md | 52 + docs/it/providers/opencode.md | 75 + docs/it/providers/openrouter.md | 66 + docs/it/providers/perplexity-provider.md | 69 + docs/it/providers/qianfan.md | 97 + docs/it/providers/qwen.md | 138 + docs/it/providers/qwen_modelstudio.md | 146 + docs/it/providers/sglang.md | 122 + docs/it/providers/stepfun.md | 159 + docs/it/providers/synthetic.md | 108 + docs/it/providers/together.md | 77 + docs/it/providers/venice.md | 289 ++ docs/it/providers/vercel-ai-gateway.md | 67 + docs/it/providers/vllm.md | 109 + docs/it/providers/volcengine.md | 100 + docs/it/providers/xai.md | 101 + docs/it/providers/xiaomi.md | 96 + docs/it/providers/zai.md | 82 + docs/it/reference/AGENTS.default.md | 133 + docs/it/reference/RELEASING.md | 139 + docs/it/reference/api-usage-costs.md | 204 ++ docs/it/reference/credits.md | 37 + docs/it/reference/device-models.md | 54 + docs/it/reference/memory-config.md | 421 +++ docs/it/reference/prompt-caching.md | 351 ++ docs/it/reference/rpc.md | 50 + .../reference/secretref-credential-surface.md | 155 + .../session-management-compaction.md | 352 ++ docs/it/reference/templates/AGENTS.dev.md | 91 + docs/it/reference/templates/AGENTS.md | 226 ++ docs/it/reference/templates/BOOT.md | 19 + docs/it/reference/templates/BOOTSTRAP.md | 69 + docs/it/reference/templates/CLAUDE.md | 226 ++ docs/it/reference/templates/HEARTBEAT.md | 21 + docs/it/reference/templates/IDENTITY.dev.md | 55 + docs/it/reference/templates/IDENTITY.md | 37 + docs/it/reference/templates/SOUL.dev.md | 84 + docs/it/reference/templates/SOUL.md | 52 + docs/it/reference/templates/TOOLS.dev.md | 32 + docs/it/reference/templates/TOOLS.md | 54 + docs/it/reference/templates/USER.dev.md | 26 + docs/it/reference/templates/USER.md | 31 + docs/it/reference/test.md | 126 + docs/it/reference/token-use.md | 199 ++ docs/it/reference/transcript-hygiene.md | 157 + docs/it/reference/wizard.md | 252 ++ docs/it/security/CONTRIBUTING-THREAT-MODEL.md | 105 + docs/it/security/THREAT-MODEL-ATLAS.md | 615 ++++ docs/it/security/formal-verification.md | 174 + docs/it/start/bootstrapping.md | 48 + docs/it/start/docs-directory.md | 74 + docs/it/start/getting-started.md | 155 + docs/it/start/hubs.md | 206 ++ docs/it/start/lore.md | 226 ++ docs/it/start/onboarding-overview.md | 76 + docs/it/start/onboarding.md | 95 + docs/it/start/openclaw.md | 232 ++ docs/it/start/quickstart.md | 29 + docs/it/start/setup.md | 179 + docs/it/start/showcase.md | 425 +++ docs/it/start/wizard-cli-automation.md | 240 ++ docs/it/start/wizard-cli-reference.md | 331 ++ docs/it/start/wizard.md | 134 + docs/it/tools/acp-agents.md | 843 +++++ docs/it/tools/agent-send.md | 107 + docs/it/tools/apply-patch.md | 59 + docs/it/tools/brave-search.md | 114 + .../it/tools/browser-linux-troubleshooting.md | 151 + docs/it/tools/browser-login.md | 80 + ...wsl2-windows-remote-cdp-troubleshooting.md | 228 ++ docs/it/tools/browser.md | 895 +++++ docs/it/tools/btw.md | 148 + docs/it/tools/capability-cookbook.md | 125 + docs/it/tools/clawhub.md | 355 ++ docs/it/tools/code-execution.md | 95 + docs/it/tools/creating-skills.md | 126 + docs/it/tools/diffs.md | 441 +++ docs/it/tools/duckduckgo-search.md | 107 + docs/it/tools/elevated.md | 123 + docs/it/tools/exa-search.md | 134 + docs/it/tools/exec-approvals.md | 567 ++++ docs/it/tools/exec.md | 243 ++ docs/it/tools/firecrawl.md | 154 + docs/it/tools/gemini-search.md | 105 + docs/it/tools/grok-search.md | 109 + docs/it/tools/image-generation.md | 146 + docs/it/tools/index.md | 181 + docs/it/tools/kimi-search.md | 105 + docs/it/tools/llm-task.md | 126 + docs/it/tools/lobster.md | 355 ++ docs/it/tools/loop-detection.md | 107 + docs/it/tools/minimax-search.md | 106 + docs/it/tools/multi-agent-sandbox-tools.md | 380 +++ docs/it/tools/ollama-search.md | 107 + docs/it/tools/pdf.md | 183 + docs/it/tools/perplexity-search.md | 192 ++ docs/it/tools/plugin.md | 352 ++ docs/it/tools/reactions.md | 85 + docs/it/tools/searxng-search.md | 138 + docs/it/tools/skills-config.md | 140 + docs/it/tools/skills.md | 383 +++ docs/it/tools/slash-commands.md | 329 ++ docs/it/tools/subagents.md | 344 ++ docs/it/tools/tavily.md | 136 + docs/it/tools/thinking.md | 109 + docs/it/tools/tts.md | 459 +++ docs/it/tools/web-fetch.md | 166 + docs/it/tools/web.md | 424 +++ docs/it/tts.md | 459 +++ docs/it/vps.md | 122 + docs/it/web/control-ui.md | 325 ++ docs/it/web/dashboard.md | 99 + docs/it/web/index.md | 133 + docs/it/web/tui.md | 183 + docs/it/web/webchat.md | 84 + docs/pl/.i18n/README.md | 81 + docs/pl/auth-credential-semantics.md | 79 + docs/pl/automation/auth-monitoring.md | 15 + docs/pl/automation/clawflow.md | 15 + docs/pl/automation/cron-jobs.md | 386 +++ docs/pl/automation/cron-vs-heartbeat.md | 15 + docs/pl/automation/gmail-pubsub.md | 15 + docs/pl/automation/hooks.md | 310 ++ docs/pl/automation/index.md | 122 + docs/pl/automation/poll.md | 15 + docs/pl/automation/standing-orders.md | 261 ++ docs/pl/automation/taskflow.md | 89 + docs/pl/automation/tasks.md | 317 ++ docs/pl/automation/troubleshooting.md | 15 + docs/pl/automation/webhook.md | 15 + docs/pl/brave-search.md | 110 + docs/pl/channels/bluebubbles.md | 442 +++ docs/pl/channels/broadcast-groups.md | 449 +++ docs/pl/channels/channel-routing.md | 137 + docs/pl/channels/discord.md | 1261 +++++++ docs/pl/channels/feishu.md | 799 +++++ docs/pl/channels/googlechat.md | 277 ++ docs/pl/channels/group-messages.md | 91 + docs/pl/channels/groups.md | 417 +++ docs/pl/channels/imessage.md | 434 +++ docs/pl/channels/index.md | 57 + docs/pl/channels/irc.md | 259 ++ docs/pl/channels/line.md | 232 ++ docs/pl/channels/location.md | 63 + docs/pl/channels/matrix.md | 870 +++++ docs/pl/channels/mattermost.md | 479 +++ docs/pl/channels/msteams.md | 811 +++++ docs/pl/channels/nextcloud-talk.md | 156 + docs/pl/channels/nostr.md | 259 ++ docs/pl/channels/pairing.md | 136 + docs/pl/channels/qqbot.md | 200 ++ docs/pl/channels/signal.md | 344 ++ docs/pl/channels/slack.md | 688 ++++ docs/pl/channels/synology-chat.md | 192 ++ docs/pl/channels/telegram.md | 1078 ++++++ docs/pl/channels/tlon.md | 297 ++ docs/pl/channels/troubleshooting.md | 140 + docs/pl/channels/twitch.md | 401 +++ docs/pl/channels/whatsapp.md | 495 +++ docs/pl/channels/zalo.md | 261 ++ docs/pl/channels/zalouser.md | 202 ++ docs/pl/ci.md | 73 + docs/pl/cli/acp.md | 323 ++ docs/pl/cli/agent.md | 64 + docs/pl/cli/agents.md | 227 ++ docs/pl/cli/approvals.md | 143 + docs/pl/cli/backup.md | 91 + docs/pl/cli/browser.md | 240 ++ docs/pl/cli/channels.md | 138 + docs/pl/cli/clawbot.md | 28 + docs/pl/cli/completion.md | 42 + docs/pl/cli/config.md | 360 ++ docs/pl/cli/configure.md | 76 + docs/pl/cli/cron.md | 173 + docs/pl/cli/daemon.md | 64 + docs/pl/cli/dashboard.md | 29 + docs/pl/cli/devices.md | 180 + docs/pl/cli/directory.md | 70 + docs/pl/cli/dns.md | 55 + docs/pl/cli/docs.md | 35 + docs/pl/cli/doctor.md | 70 + docs/pl/cli/flows.md | 25 + docs/pl/cli/gateway.md | 311 ++ docs/pl/cli/health.md | 43 + docs/pl/cli/hooks.md | 344 ++ docs/pl/cli/index.md | 1843 ++++++++++ docs/pl/cli/logs.md | 66 + docs/pl/cli/mcp.md | 509 +++ docs/pl/cli/memory.md | 142 + docs/pl/cli/message.md | 307 ++ docs/pl/cli/models.md | 143 + docs/pl/cli/node.md | 144 + docs/pl/cli/nodes.md | 73 + docs/pl/cli/onboard.md | 178 + docs/pl/cli/pairing.md | 72 + docs/pl/cli/plugins.md | 311 ++ docs/pl/cli/qr.md | 59 + docs/pl/cli/reset.md | 42 + docs/pl/cli/sandbox.md | 204 ++ docs/pl/cli/secrets.md | 204 ++ docs/pl/cli/security.md | 93 + docs/pl/cli/sessions.md | 120 + docs/pl/cli/setup.md | 52 + docs/pl/cli/skills.md | 66 + docs/pl/cli/status.md | 42 + docs/pl/cli/system.md | 78 + docs/pl/cli/tui.md | 37 + docs/pl/cli/uninstall.md | 46 + docs/pl/cli/update.md | 120 + docs/pl/cli/voicecall.md | 41 + docs/pl/cli/webhooks.md | 98 + docs/pl/concepts/agent-loop.md | 174 + docs/pl/concepts/agent-workspace.md | 254 ++ docs/pl/concepts/agent.md | 134 + docs/pl/concepts/architecture.md | 162 + docs/pl/concepts/compaction.md | 129 + docs/pl/concepts/context-engine.md | 281 ++ docs/pl/concepts/context.md | 186 ++ docs/pl/concepts/delegate-architecture.md | 314 ++ docs/pl/concepts/features.md | 83 + docs/pl/concepts/markdown-formatting.md | 137 + docs/pl/concepts/memory-builtin.md | 112 + docs/pl/concepts/memory-dreaming.md | 158 + docs/pl/concepts/memory-honcho.md | 145 + docs/pl/concepts/memory-qmd.md | 170 + docs/pl/concepts/memory-search.md | 146 + docs/pl/concepts/memory.md | 128 + docs/pl/concepts/messages.md | 168 + docs/pl/concepts/model-failover.md | 353 ++ docs/pl/concepts/model-providers.md | 804 +++++ docs/pl/concepts/models.md | 261 ++ docs/pl/concepts/multi-agent.md | 620 ++++ docs/pl/concepts/oauth.md | 230 ++ docs/pl/concepts/presence.md | 109 + docs/pl/concepts/queue.md | 96 + docs/pl/concepts/retry.md | 76 + docs/pl/concepts/session-pruning.md | 99 + docs/pl/concepts/session-tool.md | 148 + docs/pl/concepts/session.md | 122 + docs/pl/concepts/soul.md | 117 + docs/pl/concepts/streaming.md | 168 + docs/pl/concepts/system-prompt.md | 184 + docs/pl/concepts/timezone.md | 104 + docs/pl/concepts/typebox.md | 313 ++ docs/pl/concepts/typing-indicators.md | 76 + docs/pl/concepts/usage-tracking.md | 62 + docs/pl/date-time.md | 135 + docs/pl/debug/node-issue.md | 92 + docs/pl/diagnostics/flags.md | 98 + docs/pl/gateway/authentication.md | 223 ++ docs/pl/gateway/background-process.md | 138 + docs/pl/gateway/bonjour.md | 186 ++ docs/pl/gateway/bridge-protocol.md | 95 + docs/pl/gateway/cli-backends.md | 317 ++ docs/pl/gateway/configuration-examples.md | 638 ++++ docs/pl/gateway/configuration-reference.md | 2658 +++++++++++++++ docs/pl/gateway/configuration.md | 705 ++++ docs/pl/gateway/discovery.md | 148 + docs/pl/gateway/doctor.md | 498 +++ docs/pl/gateway/gateway-lock.md | 44 + docs/pl/gateway/health.md | 68 + docs/pl/gateway/heartbeat.md | 450 +++ docs/pl/gateway/index.md | 373 +++ docs/pl/gateway/local-models.md | 170 + docs/pl/gateway/logging.md | 120 + docs/pl/gateway/multiple-gateways.md | 127 + docs/pl/gateway/network-model.md | 32 + docs/pl/gateway/openai-http-api.md | 287 ++ docs/pl/gateway/openresponses-http-api.md | 347 ++ docs/pl/gateway/openshell.md | 313 ++ docs/pl/gateway/pairing.md | 145 + docs/pl/gateway/protocol.md | 592 ++++ docs/pl/gateway/remote-gateway-readme.md | 171 + docs/pl/gateway/remote.md | 254 ++ .../sandbox-vs-tool-policy-vs-elevated.md | 148 + docs/pl/gateway/sandboxing.md | 480 +++ docs/pl/gateway/secrets-plan-contract.md | 123 + docs/pl/gateway/secrets.md | 548 +++ docs/pl/gateway/security/index.md | 1359 ++++++++ docs/pl/gateway/tailscale.md | 142 + docs/pl/gateway/tools-invoke-http-api.md | 168 + docs/pl/gateway/troubleshooting.md | 457 +++ docs/pl/gateway/trusted-proxy-auth.md | 406 +++ docs/pl/help/debugging.md | 175 + docs/pl/help/environment.md | 172 + docs/pl/help/faq.md | 2255 +++++++++++++ docs/pl/help/index.md | 35 + docs/pl/help/scripts.md | 34 + docs/pl/help/testing.md | 647 ++++ docs/pl/help/troubleshooting.md | 372 +++ docs/pl/index.md | 203 ++ docs/pl/install/ansible.md | 237 ++ docs/pl/install/azure.md | 318 ++ docs/pl/install/bun.md | 62 + docs/pl/install/clawdock.md | 113 + docs/pl/install/development-channels.md | 137 + docs/pl/install/digitalocean.md | 136 + docs/pl/install/docker-vm-runtime.md | 149 + docs/pl/install/docker.md | 418 +++ docs/pl/install/exe-dev.md | 140 + docs/pl/install/fly.md | 509 +++ docs/pl/install/gcp.md | 419 +++ docs/pl/install/hetzner.md | 266 ++ docs/pl/install/index.md | 219 ++ docs/pl/install/installer.md | 450 +++ docs/pl/install/kubernetes.md | 199 ++ docs/pl/install/macos-vm.md | 288 ++ docs/pl/install/migrating-matrix.md | 355 ++ docs/pl/install/migrating.md | 119 + docs/pl/install/nix.md | 96 + docs/pl/install/node.md | 151 + docs/pl/install/northflank.mdx | 49 + docs/pl/install/oracle.md | 165 + docs/pl/install/podman.md | 217 ++ docs/pl/install/railway.mdx | 97 + docs/pl/install/raspberry-pi.md | 166 + docs/pl/install/render.mdx | 171 + docs/pl/install/uninstall.md | 135 + docs/pl/install/updating.md | 149 + docs/pl/logging.md | 391 +++ docs/pl/network.md | 73 + docs/pl/nodes/audio.md | 198 ++ docs/pl/nodes/camera.md | 169 + docs/pl/nodes/images.md | 80 + docs/pl/nodes/index.md | 415 +++ docs/pl/nodes/location-command.md | 105 + docs/pl/nodes/media-understanding.md | 438 +++ docs/pl/nodes/talk.md | 99 + docs/pl/nodes/troubleshooting.md | 130 + docs/pl/nodes/voicewake.md | 73 + docs/pl/perplexity.md | 188 ++ docs/pl/pi-dev.md | 87 + docs/pl/pi.md | 574 ++++ docs/pl/platforms/android.md | 249 ++ docs/pl/platforms/digitalocean.md | 273 ++ docs/pl/platforms/index.md | 62 + docs/pl/platforms/ios.md | 230 ++ docs/pl/platforms/linux.md | 105 + docs/pl/platforms/mac/bundled-gateway.md | 82 + docs/pl/platforms/mac/canvas.md | 132 + docs/pl/platforms/mac/child-process.md | 76 + docs/pl/platforms/mac/dev-setup.md | 114 + docs/pl/platforms/mac/health.md | 41 + docs/pl/platforms/mac/icon.md | 38 + docs/pl/platforms/mac/logging.md | 64 + docs/pl/platforms/mac/menu-bar.md | 88 + docs/pl/platforms/mac/peekaboo.md | 72 + docs/pl/platforms/mac/permissions.md | 57 + docs/pl/platforms/mac/remote.md | 91 + docs/pl/platforms/mac/signing.md | 54 + docs/pl/platforms/mac/skills.md | 47 + docs/pl/platforms/mac/voice-overlay.md | 67 + docs/pl/platforms/mac/voicewake.md | 74 + docs/pl/platforms/mac/webchat.md | 58 + docs/pl/platforms/mac/xpc.md | 68 + docs/pl/platforms/macos.md | 222 ++ docs/pl/platforms/oracle.md | 312 ++ docs/pl/platforms/raspberry-pi.md | 427 +++ docs/pl/platforms/windows.md | 248 ++ docs/pl/plugins/agent-tools.md | 17 + docs/pl/plugins/architecture.md | 1542 +++++++++ docs/pl/plugins/building-extensions.md | 17 + docs/pl/plugins/building-plugins.md | 326 ++ docs/pl/plugins/bundles.md | 299 ++ docs/pl/plugins/community.md | 156 + docs/pl/plugins/manifest.md | 417 +++ docs/pl/plugins/sdk-channel-plugins.md | 518 +++ docs/pl/plugins/sdk-entrypoints.md | 216 ++ docs/pl/plugins/sdk-migration.md | 367 ++ docs/pl/plugins/sdk-overview.md | 480 +++ docs/pl/plugins/sdk-provider-plugins.md | 719 ++++ docs/pl/plugins/sdk-runtime.md | 388 +++ docs/pl/plugins/sdk-setup.md | 520 +++ docs/pl/plugins/sdk-testing.md | 270 ++ docs/pl/plugins/voice-call.md | 469 +++ docs/pl/plugins/zalouser.md | 85 + docs/pl/prose.md | 141 + docs/pl/providers/anthropic.md | 408 +++ docs/pl/providers/bedrock-mantle.md | 98 + docs/pl/providers/bedrock.md | 280 ++ docs/pl/providers/chutes.md | 109 + docs/pl/providers/claude-max-api-proxy.md | 170 + docs/pl/providers/cloudflare-ai-gateway.md | 78 + docs/pl/providers/deepgram.md | 100 + docs/pl/providers/deepseek.md | 60 + docs/pl/providers/fireworks.md | 76 + docs/pl/providers/github-copilot.md | 87 + docs/pl/providers/glm.md | 75 + docs/pl/providers/google.md | 156 + docs/pl/providers/groq.md | 110 + docs/pl/providers/huggingface.md | 200 ++ docs/pl/providers/index.md | 87 + docs/pl/providers/kilocode.md | 96 + docs/pl/providers/litellm.md | 165 + docs/pl/providers/minimax.md | 287 ++ docs/pl/providers/mistral.md | 75 + docs/pl/providers/models.md | 62 + docs/pl/providers/moonshot.md | 230 ++ docs/pl/providers/nvidia.md | 65 + docs/pl/providers/ollama.md | 386 +++ docs/pl/providers/openai.md | 473 +++ docs/pl/providers/opencode-go.md | 52 + docs/pl/providers/opencode.md | 75 + docs/pl/providers/openrouter.md | 66 + docs/pl/providers/perplexity-provider.md | 69 + docs/pl/providers/qianfan.md | 97 + docs/pl/providers/qwen.md | 136 + docs/pl/providers/qwen_modelstudio.md | 145 + docs/pl/providers/sglang.md | 122 + docs/pl/providers/stepfun.md | 159 + docs/pl/providers/synthetic.md | 108 + docs/pl/providers/together.md | 77 + docs/pl/providers/venice.md | 289 ++ docs/pl/providers/vercel-ai-gateway.md | 67 + docs/pl/providers/vllm.md | 110 + docs/pl/providers/volcengine.md | 101 + docs/pl/providers/xai.md | 101 + docs/pl/providers/xiaomi.md | 96 + docs/pl/providers/zai.md | 82 + docs/pl/reference/AGENTS.default.md | 133 + docs/pl/reference/RELEASING.md | 145 + docs/pl/reference/api-usage-costs.md | 204 ++ docs/pl/reference/credits.md | 37 + docs/pl/reference/device-models.md | 54 + docs/pl/reference/memory-config.md | 423 +++ docs/pl/reference/prompt-caching.md | 348 ++ docs/pl/reference/rpc.md | 50 + .../reference/secretref-credential-surface.md | 155 + .../session-management-compaction.md | 357 ++ docs/pl/reference/templates/AGENTS.dev.md | 91 + docs/pl/reference/templates/AGENTS.md | 226 ++ docs/pl/reference/templates/BOOT.md | 19 + docs/pl/reference/templates/BOOTSTRAP.md | 69 + docs/pl/reference/templates/CLAUDE.md | 226 ++ docs/pl/reference/templates/HEARTBEAT.md | 21 + docs/pl/reference/templates/IDENTITY.dev.md | 55 + docs/pl/reference/templates/IDENTITY.md | 37 + docs/pl/reference/templates/SOUL.dev.md | 84 + docs/pl/reference/templates/SOUL.md | 52 + docs/pl/reference/templates/TOOLS.dev.md | 32 + docs/pl/reference/templates/TOOLS.md | 54 + docs/pl/reference/templates/USER.dev.md | 26 + docs/pl/reference/templates/USER.md | 31 + docs/pl/reference/test.md | 126 + docs/pl/reference/token-use.md | 203 ++ docs/pl/reference/transcript-hygiene.md | 157 + docs/pl/reference/wizard.md | 252 ++ docs/pl/security/CONTRIBUTING-THREAT-MODEL.md | 105 + docs/pl/security/THREAT-MODEL-ATLAS.md | 615 ++++ docs/pl/security/formal-verification.md | 174 + docs/pl/start/bootstrapping.md | 48 + docs/pl/start/docs-directory.md | 74 + docs/pl/start/getting-started.md | 154 + docs/pl/start/hubs.md | 206 ++ docs/pl/start/lore.md | 226 ++ docs/pl/start/onboarding-overview.md | 76 + docs/pl/start/onboarding.md | 99 + docs/pl/start/openclaw.md | 232 ++ docs/pl/start/quickstart.md | 29 + docs/pl/start/setup.md | 179 + docs/pl/start/showcase.md | 425 +++ docs/pl/start/wizard-cli-automation.md | 240 ++ docs/pl/start/wizard-cli-reference.md | 331 ++ docs/pl/start/wizard.md | 134 + docs/pl/tools/acp-agents.md | 842 +++++ docs/pl/tools/agent-send.md | 107 + docs/pl/tools/apply-patch.md | 59 + docs/pl/tools/brave-search.md | 114 + .../pl/tools/browser-linux-troubleshooting.md | 152 + docs/pl/tools/browser-login.md | 80 + ...wsl2-windows-remote-cdp-troubleshooting.md | 228 ++ docs/pl/tools/browser.md | 892 +++++ docs/pl/tools/btw.md | 149 + docs/pl/tools/capability-cookbook.md | 125 + docs/pl/tools/clawhub.md | 354 ++ docs/pl/tools/code-execution.md | 97 + docs/pl/tools/creating-skills.md | 126 + docs/pl/tools/diffs.md | 441 +++ docs/pl/tools/duckduckgo-search.md | 109 + docs/pl/tools/elevated.md | 123 + docs/pl/tools/exa-search.md | 134 + docs/pl/tools/exec-approvals.md | 569 ++++ docs/pl/tools/exec.md | 244 ++ docs/pl/tools/firecrawl.md | 154 + docs/pl/tools/gemini-search.md | 105 + docs/pl/tools/grok-search.md | 109 + docs/pl/tools/image-generation.md | 146 + docs/pl/tools/index.md | 181 + docs/pl/tools/kimi-search.md | 105 + docs/pl/tools/llm-task.md | 126 + docs/pl/tools/lobster.md | 354 ++ docs/pl/tools/loop-detection.md | 107 + docs/pl/tools/minimax-search.md | 106 + docs/pl/tools/multi-agent-sandbox-tools.md | 380 +++ docs/pl/tools/ollama-search.md | 105 + docs/pl/tools/pdf.md | 181 + docs/pl/tools/perplexity-search.md | 192 ++ docs/pl/tools/plugin.md | 351 ++ docs/pl/tools/reactions.md | 85 + docs/pl/tools/searxng-search.md | 139 + docs/pl/tools/skills-config.md | 140 + docs/pl/tools/skills.md | 383 +++ docs/pl/tools/slash-commands.md | 328 ++ docs/pl/tools/subagents.md | 344 ++ docs/pl/tools/tavily.md | 136 + docs/pl/tools/thinking.md | 109 + docs/pl/tools/tts.md | 459 +++ docs/pl/tools/web-fetch.md | 166 + docs/pl/tools/web.md | 423 +++ docs/pl/tts.md | 459 +++ docs/pl/vps.md | 122 + docs/pl/web/control-ui.md | 325 ++ docs/pl/web/dashboard.md | 99 + docs/pl/web/index.md | 133 + docs/pl/web/tui.md | 183 + docs/pl/web/webchat.md | 84 + docs/tr/.i18n/README.md | 81 + docs/tr/auth-credential-semantics.md | 79 + docs/tr/automation/auth-monitoring.md | 15 + docs/tr/automation/clawflow.md | 15 + docs/tr/automation/cron-jobs.md | 386 +++ docs/tr/automation/cron-vs-heartbeat.md | 15 + docs/tr/automation/gmail-pubsub.md | 15 + docs/tr/automation/hooks.md | 310 ++ docs/tr/automation/index.md | 122 + docs/tr/automation/poll.md | 15 + docs/tr/automation/standing-orders.md | 261 ++ docs/tr/automation/taskflow.md | 89 + docs/tr/automation/tasks.md | 319 ++ docs/tr/automation/troubleshooting.md | 15 + docs/tr/automation/webhook.md | 15 + docs/tr/brave-search.md | 110 + docs/tr/channels/bluebubbles.md | 441 +++ docs/tr/channels/broadcast-groups.md | 449 +++ docs/tr/channels/channel-routing.md | 135 + docs/tr/channels/discord.md | 1262 +++++++ docs/tr/channels/feishu.md | 794 +++++ docs/tr/channels/googlechat.md | 277 ++ docs/tr/channels/group-messages.md | 91 + docs/tr/channels/groups.md | 417 +++ docs/tr/channels/imessage.md | 434 +++ docs/tr/channels/index.md | 57 + docs/tr/channels/irc.md | 259 ++ docs/tr/channels/line.md | 217 ++ docs/tr/channels/location.md | 63 + docs/tr/channels/matrix.md | 868 +++++ docs/tr/channels/mattermost.md | 479 +++ docs/tr/channels/msteams.md | 810 +++++ docs/tr/channels/nextcloud-talk.md | 154 + docs/tr/channels/nostr.md | 257 ++ docs/tr/channels/pairing.md | 129 + docs/tr/channels/qqbot.md | 187 ++ docs/tr/channels/signal.md | 344 ++ docs/tr/channels/slack.md | 687 ++++ docs/tr/channels/synology-chat.md | 193 ++ docs/tr/channels/telegram.md | 1078 ++++++ docs/tr/channels/tlon.md | 297 ++ docs/tr/channels/troubleshooting.md | 140 + docs/tr/channels/twitch.md | 401 +++ docs/tr/channels/whatsapp.md | 495 +++ docs/tr/channels/zalo.md | 261 ++ docs/tr/channels/zalouser.md | 200 ++ docs/tr/ci.md | 73 + docs/tr/cli/acp.md | 292 ++ docs/tr/cli/agent.md | 64 + docs/tr/cli/agents.md | 228 ++ docs/tr/cli/approvals.md | 143 + docs/tr/cli/backup.md | 87 + docs/tr/cli/browser.md | 240 ++ docs/tr/cli/channels.md | 138 + docs/tr/cli/clawbot.md | 28 + docs/tr/cli/completion.md | 42 + docs/tr/cli/config.md | 359 ++ docs/tr/cli/configure.md | 77 + docs/tr/cli/cron.md | 173 + docs/tr/cli/daemon.md | 64 + docs/tr/cli/dashboard.md | 29 + docs/tr/cli/devices.md | 163 + docs/tr/cli/directory.md | 70 + docs/tr/cli/dns.md | 55 + docs/tr/cli/docs.md | 35 + docs/tr/cli/doctor.md | 70 + docs/tr/cli/flows.md | 25 + docs/tr/cli/gateway.md | 308 ++ docs/tr/cli/health.md | 43 + docs/tr/cli/hooks.md | 344 ++ docs/tr/cli/index.md | 1845 ++++++++++ docs/tr/cli/logs.md | 66 + docs/tr/cli/mcp.md | 458 +++ docs/tr/cli/memory.md | 142 + docs/tr/cli/message.md | 307 ++ docs/tr/cli/models.md | 143 + docs/tr/cli/node.md | 141 + docs/tr/cli/nodes.md | 72 + docs/tr/cli/onboard.md | 178 + docs/tr/cli/pairing.md | 72 + docs/tr/cli/plugins.md | 311 ++ docs/tr/cli/qr.md | 59 + docs/tr/cli/reset.md | 42 + docs/tr/cli/sandbox.md | 202 ++ docs/tr/cli/secrets.md | 204 ++ docs/tr/cli/security.md | 91 + docs/tr/cli/sessions.md | 118 + docs/tr/cli/setup.md | 52 + docs/tr/cli/skills.md | 67 + docs/tr/cli/status.md | 42 + docs/tr/cli/system.md | 78 + docs/tr/cli/tui.md | 37 + docs/tr/cli/uninstall.md | 46 + docs/tr/cli/update.md | 118 + docs/tr/cli/voicecall.md | 41 + docs/tr/cli/webhooks.md | 98 + docs/tr/concepts/agent-loop.md | 175 + docs/tr/concepts/agent-workspace.md | 231 ++ docs/tr/concepts/agent.md | 131 + docs/tr/concepts/architecture.md | 143 + docs/tr/concepts/compaction.md | 129 + docs/tr/concepts/context-engine.md | 281 ++ docs/tr/concepts/context.md | 186 ++ docs/tr/concepts/delegate-architecture.md | 312 ++ docs/tr/concepts/features.md | 83 + docs/tr/concepts/markdown-formatting.md | 138 + docs/tr/concepts/memory-builtin.md | 105 + docs/tr/concepts/memory-dreaming.md | 158 + docs/tr/concepts/memory-honcho.md | 129 + docs/tr/concepts/memory-qmd.md | 146 + docs/tr/concepts/memory-search.md | 145 + docs/tr/concepts/memory.md | 111 + docs/tr/concepts/messages.md | 168 + docs/tr/concepts/model-failover.md | 318 ++ docs/tr/concepts/model-providers.md | 757 +++++ docs/tr/concepts/models.md | 242 ++ docs/tr/concepts/multi-agent.md | 627 ++++ docs/tr/concepts/oauth.md | 232 ++ docs/tr/concepts/presence.md | 108 + docs/tr/concepts/queue.md | 96 + docs/tr/concepts/retry.md | 76 + docs/tr/concepts/session-pruning.md | 99 + docs/tr/concepts/session-tool.md | 142 + docs/tr/concepts/session.md | 123 + docs/tr/concepts/soul.md | 110 + docs/tr/concepts/streaming.md | 168 + docs/tr/concepts/system-prompt.md | 183 + docs/tr/concepts/timezone.md | 104 + docs/tr/concepts/typebox.md | 310 ++ docs/tr/concepts/typing-indicators.md | 69 + docs/tr/concepts/usage-tracking.md | 58 + docs/tr/date-time.md | 135 + docs/tr/debug/node-issue.md | 92 + docs/tr/diagnostics/flags.md | 98 + docs/tr/gateway/authentication.md | 226 ++ docs/tr/gateway/background-process.md | 131 + docs/tr/gateway/bonjour.md | 186 ++ docs/tr/gateway/bridge-protocol.md | 84 + docs/tr/gateway/cli-backends.md | 316 ++ docs/tr/gateway/configuration-examples.md | 638 ++++ docs/tr/gateway/configuration-reference.md | 2758 +++++++++++++++ docs/tr/gateway/configuration.md | 703 ++++ docs/tr/gateway/discovery.md | 147 + docs/tr/gateway/doctor.md | 492 +++ docs/tr/gateway/gateway-lock.md | 44 + docs/tr/gateway/health.md | 68 + docs/tr/gateway/heartbeat.md | 443 +++ docs/tr/gateway/index.md | 371 ++ docs/tr/gateway/local-models.md | 166 + docs/tr/gateway/logging.md | 119 + docs/tr/gateway/multiple-gateways.md | 127 + docs/tr/gateway/network-model.md | 31 + docs/tr/gateway/openai-http-api.md | 287 ++ docs/tr/gateway/openresponses-http-api.md | 348 ++ docs/tr/gateway/openshell.md | 312 ++ docs/tr/gateway/pairing.md | 139 + docs/tr/gateway/protocol.md | 548 +++ docs/tr/gateway/remote-gateway-readme.md | 171 + docs/tr/gateway/remote.md | 254 ++ .../sandbox-vs-tool-policy-vs-elevated.md | 148 + docs/tr/gateway/sandboxing.md | 478 +++ docs/tr/gateway/secrets-plan-contract.md | 123 + docs/tr/gateway/secrets.md | 549 +++ docs/tr/gateway/security/index.md | 1353 ++++++++ docs/tr/gateway/tailscale.md | 141 + docs/tr/gateway/tools-invoke-http-api.md | 168 + docs/tr/gateway/troubleshooting.md | 456 +++ docs/tr/gateway/trusted-proxy-auth.md | 404 +++ docs/tr/help/debugging.md | 171 + docs/tr/help/environment.md | 172 + docs/tr/help/faq.md | 2337 +++++++++++++ docs/tr/help/index.md | 35 + docs/tr/help/scripts.md | 34 + docs/tr/help/testing.md | 643 ++++ docs/tr/help/troubleshooting.md | 371 ++ docs/tr/index.md | 203 ++ docs/tr/install/ansible.md | 237 ++ docs/tr/install/azure.md | 318 ++ docs/tr/install/bun.md | 62 + docs/tr/install/clawdock.md | 113 + docs/tr/install/development-channels.md | 139 + docs/tr/install/digitalocean.md | 136 + docs/tr/install/docker-vm-runtime.md | 149 + docs/tr/install/docker.md | 418 +++ docs/tr/install/exe-dev.md | 139 + docs/tr/install/fly.md | 509 +++ docs/tr/install/gcp.md | 419 +++ docs/tr/install/hetzner.md | 265 ++ docs/tr/install/index.md | 219 ++ docs/tr/install/installer.md | 449 +++ docs/tr/install/kubernetes.md | 199 ++ docs/tr/install/macos-vm.md | 288 ++ docs/tr/install/migrating-matrix.md | 356 ++ docs/tr/install/migrating.md | 119 + docs/tr/install/nix.md | 96 + docs/tr/install/node.md | 151 + docs/tr/install/northflank.mdx | 49 + docs/tr/install/oracle.md | 165 + docs/tr/install/podman.md | 215 ++ docs/tr/install/railway.mdx | 97 + docs/tr/install/raspberry-pi.md | 166 + docs/tr/install/render.mdx | 172 + docs/tr/install/uninstall.md | 135 + docs/tr/install/updating.md | 147 + docs/tr/logging.md | 394 +++ docs/tr/network.md | 72 + docs/tr/nodes/audio.md | 198 ++ docs/tr/nodes/camera.md | 169 + docs/tr/nodes/images.md | 80 + docs/tr/nodes/index.md | 396 +++ docs/tr/nodes/location-command.md | 105 + docs/tr/nodes/media-understanding.md | 437 +++ docs/tr/nodes/talk.md | 99 + docs/tr/nodes/troubleshooting.md | 130 + docs/tr/nodes/voicewake.md | 73 + docs/tr/perplexity.md | 187 ++ docs/tr/pi-dev.md | 87 + docs/tr/pi.md | 574 ++++ docs/tr/platforms/android.md | 251 ++ docs/tr/platforms/digitalocean.md | 273 ++ docs/tr/platforms/index.md | 62 + docs/tr/platforms/ios.md | 229 ++ docs/tr/platforms/linux.md | 107 + docs/tr/platforms/mac/bundled-gateway.md | 75 + docs/tr/platforms/mac/canvas.md | 127 + docs/tr/platforms/mac/child-process.md | 76 + docs/tr/platforms/mac/dev-setup.md | 114 + docs/tr/platforms/mac/health.md | 41 + docs/tr/platforms/mac/icon.md | 38 + docs/tr/platforms/mac/logging.md | 64 + docs/tr/platforms/mac/menu-bar.md | 88 + docs/tr/platforms/mac/peekaboo.md | 63 + docs/tr/platforms/mac/permissions.md | 57 + docs/tr/platforms/mac/remote.md | 91 + docs/tr/platforms/mac/signing.md | 54 + docs/tr/platforms/mac/skills.md | 43 + docs/tr/platforms/mac/voice-overlay.md | 67 + docs/tr/platforms/mac/voicewake.md | 74 + docs/tr/platforms/mac/webchat.md | 55 + docs/tr/platforms/mac/xpc.md | 68 + docs/tr/platforms/macos.md | 221 ++ docs/tr/platforms/oracle.md | 312 ++ docs/tr/platforms/raspberry-pi.md | 426 +++ docs/tr/platforms/windows.md | 247 ++ docs/tr/plugins/agent-tools.md | 17 + docs/tr/plugins/architecture.md | 1600 +++++++++ docs/tr/plugins/building-extensions.md | 17 + docs/tr/plugins/building-plugins.md | 331 ++ docs/tr/plugins/bundles.md | 298 ++ docs/tr/plugins/community.md | 153 + docs/tr/plugins/manifest.md | 416 +++ docs/tr/plugins/sdk-channel-plugins.md | 515 +++ docs/tr/plugins/sdk-entrypoints.md | 222 ++ docs/tr/plugins/sdk-migration.md | 361 ++ docs/tr/plugins/sdk-overview.md | 479 +++ docs/tr/plugins/sdk-provider-plugins.md | 728 ++++ docs/tr/plugins/sdk-runtime.md | 391 +++ docs/tr/plugins/sdk-setup.md | 509 +++ docs/tr/plugins/sdk-testing.md | 270 ++ docs/tr/plugins/voice-call.md | 474 +++ docs/tr/plugins/zalouser.md | 85 + docs/tr/prose.md | 141 + docs/tr/providers/anthropic.md | 411 +++ docs/tr/providers/bedrock-mantle.md | 97 + docs/tr/providers/bedrock.md | 276 ++ docs/tr/providers/chutes.md | 110 + docs/tr/providers/claude-max-api-proxy.md | 170 + docs/tr/providers/cloudflare-ai-gateway.md | 78 + docs/tr/providers/deepgram.md | 100 + docs/tr/providers/deepseek.md | 60 + docs/tr/providers/fireworks.md | 77 + docs/tr/providers/github-copilot.md | 87 + docs/tr/providers/glm.md | 75 + docs/tr/providers/google.md | 155 + docs/tr/providers/groq.md | 112 + docs/tr/providers/huggingface.md | 200 ++ docs/tr/providers/index.md | 88 + docs/tr/providers/kilocode.md | 96 + docs/tr/providers/litellm.md | 166 + docs/tr/providers/minimax.md | 278 ++ docs/tr/providers/mistral.md | 75 + docs/tr/providers/models.md | 63 + docs/tr/providers/moonshot.md | 231 ++ docs/tr/providers/nvidia.md | 66 + docs/tr/providers/ollama.md | 386 +++ docs/tr/providers/openai.md | 473 +++ docs/tr/providers/opencode-go.md | 52 + docs/tr/providers/opencode.md | 76 + docs/tr/providers/openrouter.md | 66 + docs/tr/providers/perplexity-provider.md | 69 + docs/tr/providers/qianfan.md | 97 + docs/tr/providers/qwen.md | 138 + docs/tr/providers/qwen_modelstudio.md | 145 + docs/tr/providers/sglang.md | 121 + docs/tr/providers/stepfun.md | 159 + docs/tr/providers/synthetic.md | 108 + docs/tr/providers/together.md | 77 + docs/tr/providers/venice.md | 289 ++ docs/tr/providers/vercel-ai-gateway.md | 66 + docs/tr/providers/vllm.md | 108 + docs/tr/providers/volcengine.md | 91 + docs/tr/providers/xai.md | 100 + docs/tr/providers/xiaomi.md | 93 + docs/tr/providers/zai.md | 75 + docs/tr/reference/AGENTS.default.md | 125 + docs/tr/reference/RELEASING.md | 144 + docs/tr/reference/api-usage-costs.md | 168 + docs/tr/reference/credits.md | 37 + docs/tr/reference/device-models.md | 54 + docs/tr/reference/memory-config.md | 425 +++ docs/tr/reference/prompt-caching.md | 339 ++ docs/tr/reference/rpc.md | 50 + .../reference/secretref-credential-surface.md | 155 + .../session-management-compaction.md | 348 ++ docs/tr/reference/templates/AGENTS.dev.md | 91 + docs/tr/reference/templates/AGENTS.md | 226 ++ docs/tr/reference/templates/BOOT.md | 19 + docs/tr/reference/templates/BOOTSTRAP.md | 69 + docs/tr/reference/templates/CLAUDE.md | 226 ++ docs/tr/reference/templates/HEARTBEAT.md | 21 + docs/tr/reference/templates/IDENTITY.dev.md | 55 + docs/tr/reference/templates/IDENTITY.md | 37 + docs/tr/reference/templates/SOUL.dev.md | 84 + docs/tr/reference/templates/SOUL.md | 52 + docs/tr/reference/templates/TOOLS.dev.md | 32 + docs/tr/reference/templates/TOOLS.md | 54 + docs/tr/reference/templates/USER.dev.md | 26 + docs/tr/reference/templates/USER.md | 31 + docs/tr/reference/test.md | 126 + docs/tr/reference/token-use.md | 208 ++ docs/tr/reference/transcript-hygiene.md | 157 + docs/tr/reference/wizard.md | 252 ++ docs/tr/security/CONTRIBUTING-THREAT-MODEL.md | 105 + docs/tr/security/THREAT-MODEL-ATLAS.md | 615 ++++ docs/tr/security/formal-verification.md | 175 + docs/tr/start/bootstrapping.md | 48 + docs/tr/start/docs-directory.md | 74 + docs/tr/start/getting-started.md | 155 + docs/tr/start/hubs.md | 206 ++ docs/tr/start/lore.md | 226 ++ docs/tr/start/onboarding-overview.md | 75 + docs/tr/start/onboarding.md | 94 + docs/tr/start/openclaw.md | 232 ++ docs/tr/start/quickstart.md | 29 + docs/tr/start/setup.md | 179 + docs/tr/start/showcase.md | 425 +++ docs/tr/start/wizard-cli-automation.md | 240 ++ docs/tr/start/wizard-cli-reference.md | 330 ++ docs/tr/start/wizard.md | 133 + docs/tr/tools/acp-agents.md | 827 +++++ docs/tr/tools/agent-send.md | 107 + docs/tr/tools/apply-patch.md | 59 + docs/tr/tools/brave-search.md | 114 + .../tr/tools/browser-linux-troubleshooting.md | 152 + docs/tr/tools/browser-login.md | 80 + ...wsl2-windows-remote-cdp-troubleshooting.md | 228 ++ docs/tr/tools/browser.md | 892 +++++ docs/tr/tools/btw.md | 146 + docs/tr/tools/capability-cookbook.md | 126 + docs/tr/tools/clawhub.md | 353 ++ docs/tr/tools/code-execution.md | 97 + docs/tr/tools/creating-skills.md | 123 + docs/tr/tools/diffs.md | 441 +++ docs/tr/tools/duckduckgo-search.md | 107 + docs/tr/tools/elevated.md | 123 + docs/tr/tools/exa-search.md | 134 + docs/tr/tools/exec-approvals.md | 573 ++++ docs/tr/tools/exec.md | 243 ++ docs/tr/tools/firecrawl.md | 154 + docs/tr/tools/gemini-search.md | 106 + docs/tr/tools/grok-search.md | 108 + docs/tr/tools/image-generation.md | 146 + docs/tr/tools/index.md | 180 + docs/tr/tools/kimi-search.md | 105 + docs/tr/tools/llm-task.md | 126 + docs/tr/tools/lobster.md | 355 ++ docs/tr/tools/loop-detection.md | 107 + docs/tr/tools/minimax-search.md | 106 + docs/tr/tools/multi-agent-sandbox-tools.md | 380 +++ docs/tr/tools/ollama-search.md | 99 + docs/tr/tools/pdf.md | 177 + docs/tr/tools/perplexity-search.md | 192 ++ docs/tr/tools/plugin.md | 355 ++ docs/tr/tools/reactions.md | 85 + docs/tr/tools/searxng-search.md | 138 + docs/tr/tools/skills-config.md | 141 + docs/tr/tools/skills.md | 374 +++ docs/tr/tools/slash-commands.md | 326 ++ docs/tr/tools/subagents.md | 341 ++ docs/tr/tools/tavily.md | 134 + docs/tr/tools/thinking.md | 109 + docs/tr/tools/tts.md | 456 +++ docs/tr/tools/web-fetch.md | 166 + docs/tr/tools/web.md | 425 +++ docs/tr/tts.md | 456 +++ docs/tr/vps.md | 120 + docs/tr/web/control-ui.md | 318 ++ docs/tr/web/dashboard.md | 100 + docs/tr/web/index.md | 134 + docs/tr/web/tui.md | 183 + docs/tr/web/webchat.md | 83 + 1608 files changed, 360417 insertions(+), 4 deletions(-) create mode 100644 docs/id/.i18n/README.md create mode 100644 docs/id/auth-credential-semantics.md create mode 100644 docs/id/automation/auth-monitoring.md create mode 100644 docs/id/automation/clawflow.md create mode 100644 docs/id/automation/cron-jobs.md create mode 100644 docs/id/automation/cron-vs-heartbeat.md create mode 100644 docs/id/automation/gmail-pubsub.md create mode 100644 docs/id/automation/hooks.md create mode 100644 docs/id/automation/index.md create mode 100644 docs/id/automation/poll.md create mode 100644 docs/id/automation/standing-orders.md create mode 100644 docs/id/automation/taskflow.md create mode 100644 docs/id/automation/tasks.md create mode 100644 docs/id/automation/troubleshooting.md create mode 100644 docs/id/automation/webhook.md create mode 100644 docs/id/brave-search.md create mode 100644 docs/id/channels/bluebubbles.md create mode 100644 docs/id/channels/broadcast-groups.md create mode 100644 docs/id/channels/channel-routing.md create mode 100644 docs/id/channels/discord.md create mode 100644 docs/id/channels/feishu.md create mode 100644 docs/id/channels/googlechat.md create mode 100644 docs/id/channels/group-messages.md create mode 100644 docs/id/channels/groups.md create mode 100644 docs/id/channels/imessage.md create mode 100644 docs/id/channels/index.md create mode 100644 docs/id/channels/irc.md create mode 100644 docs/id/channels/line.md create mode 100644 docs/id/channels/location.md create mode 100644 docs/id/channels/matrix.md create mode 100644 docs/id/channels/mattermost.md create mode 100644 docs/id/channels/msteams.md create mode 100644 docs/id/channels/nextcloud-talk.md create mode 100644 docs/id/channels/nostr.md create mode 100644 docs/id/channels/pairing.md create mode 100644 docs/id/channels/qqbot.md create mode 100644 docs/id/channels/signal.md create mode 100644 docs/id/channels/slack.md create mode 100644 docs/id/channels/synology-chat.md create mode 100644 docs/id/channels/telegram.md create mode 100644 docs/id/channels/tlon.md create mode 100644 docs/id/channels/troubleshooting.md create mode 100644 docs/id/channels/twitch.md create mode 100644 docs/id/channels/whatsapp.md create mode 100644 docs/id/channels/zalo.md create mode 100644 docs/id/channels/zalouser.md create mode 100644 docs/id/ci.md create mode 100644 docs/id/cli/acp.md create mode 100644 docs/id/cli/agent.md create mode 100644 docs/id/cli/agents.md create mode 100644 docs/id/cli/approvals.md create mode 100644 docs/id/cli/backup.md create mode 100644 docs/id/cli/browser.md create mode 100644 docs/id/cli/channels.md create mode 100644 docs/id/cli/clawbot.md create mode 100644 docs/id/cli/completion.md create mode 100644 docs/id/cli/config.md create mode 100644 docs/id/cli/configure.md create mode 100644 docs/id/cli/cron.md create mode 100644 docs/id/cli/daemon.md create mode 100644 docs/id/cli/dashboard.md create mode 100644 docs/id/cli/devices.md create mode 100644 docs/id/cli/directory.md create mode 100644 docs/id/cli/dns.md create mode 100644 docs/id/cli/docs.md create mode 100644 docs/id/cli/doctor.md create mode 100644 docs/id/cli/flows.md create mode 100644 docs/id/cli/gateway.md create mode 100644 docs/id/cli/health.md create mode 100644 docs/id/cli/hooks.md create mode 100644 docs/id/cli/index.md create mode 100644 docs/id/cli/logs.md create mode 100644 docs/id/cli/mcp.md create mode 100644 docs/id/cli/memory.md create mode 100644 docs/id/cli/message.md create mode 100644 docs/id/cli/models.md create mode 100644 docs/id/cli/node.md create mode 100644 docs/id/cli/nodes.md create mode 100644 docs/id/cli/onboard.md create mode 100644 docs/id/cli/pairing.md create mode 100644 docs/id/cli/plugins.md create mode 100644 docs/id/cli/qr.md create mode 100644 docs/id/cli/reset.md create mode 100644 docs/id/cli/sandbox.md create mode 100644 docs/id/cli/secrets.md create mode 100644 docs/id/cli/security.md create mode 100644 docs/id/cli/sessions.md create mode 100644 docs/id/cli/setup.md create mode 100644 docs/id/cli/skills.md create mode 100644 docs/id/cli/status.md create mode 100644 docs/id/cli/system.md create mode 100644 docs/id/cli/tui.md create mode 100644 docs/id/cli/uninstall.md create mode 100644 docs/id/cli/update.md create mode 100644 docs/id/cli/voicecall.md create mode 100644 docs/id/cli/webhooks.md create mode 100644 docs/id/concepts/agent-loop.md create mode 100644 docs/id/concepts/agent-workspace.md create mode 100644 docs/id/concepts/agent.md create mode 100644 docs/id/concepts/architecture.md create mode 100644 docs/id/concepts/compaction.md create mode 100644 docs/id/concepts/context-engine.md create mode 100644 docs/id/concepts/context.md create mode 100644 docs/id/concepts/delegate-architecture.md create mode 100644 docs/id/concepts/features.md create mode 100644 docs/id/concepts/markdown-formatting.md create mode 100644 docs/id/concepts/memory-builtin.md create mode 100644 docs/id/concepts/memory-dreaming.md create mode 100644 docs/id/concepts/memory-honcho.md create mode 100644 docs/id/concepts/memory-qmd.md create mode 100644 docs/id/concepts/memory-search.md create mode 100644 docs/id/concepts/memory.md create mode 100644 docs/id/concepts/messages.md create mode 100644 docs/id/concepts/model-failover.md create mode 100644 docs/id/concepts/model-providers.md create mode 100644 docs/id/concepts/models.md create mode 100644 docs/id/concepts/multi-agent.md create mode 100644 docs/id/concepts/oauth.md create mode 100644 docs/id/concepts/presence.md create mode 100644 docs/id/concepts/queue.md create mode 100644 docs/id/concepts/retry.md create mode 100644 docs/id/concepts/session-pruning.md create mode 100644 docs/id/concepts/session-tool.md create mode 100644 docs/id/concepts/session.md create mode 100644 docs/id/concepts/soul.md create mode 100644 docs/id/concepts/streaming.md create mode 100644 docs/id/concepts/system-prompt.md create mode 100644 docs/id/concepts/timezone.md create mode 100644 docs/id/concepts/typebox.md create mode 100644 docs/id/concepts/typing-indicators.md create mode 100644 docs/id/concepts/usage-tracking.md create mode 100644 docs/id/date-time.md create mode 100644 docs/id/debug/node-issue.md create mode 100644 docs/id/diagnostics/flags.md create mode 100644 docs/id/gateway/authentication.md create mode 100644 docs/id/gateway/background-process.md create mode 100644 docs/id/gateway/bonjour.md create mode 100644 docs/id/gateway/bridge-protocol.md create mode 100644 docs/id/gateway/cli-backends.md create mode 100644 docs/id/gateway/configuration-examples.md create mode 100644 docs/id/gateway/configuration-reference.md create mode 100644 docs/id/gateway/configuration.md create mode 100644 docs/id/gateway/discovery.md create mode 100644 docs/id/gateway/doctor.md create mode 100644 docs/id/gateway/gateway-lock.md create mode 100644 docs/id/gateway/health.md create mode 100644 docs/id/gateway/heartbeat.md create mode 100644 docs/id/gateway/index.md create mode 100644 docs/id/gateway/local-models.md create mode 100644 docs/id/gateway/logging.md create mode 100644 docs/id/gateway/multiple-gateways.md create mode 100644 docs/id/gateway/network-model.md create mode 100644 docs/id/gateway/openai-http-api.md create mode 100644 docs/id/gateway/openresponses-http-api.md create mode 100644 docs/id/gateway/openshell.md create mode 100644 docs/id/gateway/pairing.md create mode 100644 docs/id/gateway/protocol.md create mode 100644 docs/id/gateway/remote-gateway-readme.md create mode 100644 docs/id/gateway/remote.md create mode 100644 docs/id/gateway/sandbox-vs-tool-policy-vs-elevated.md create mode 100644 docs/id/gateway/sandboxing.md create mode 100644 docs/id/gateway/secrets-plan-contract.md create mode 100644 docs/id/gateway/secrets.md create mode 100644 docs/id/gateway/security/index.md create mode 100644 docs/id/gateway/tailscale.md create mode 100644 docs/id/gateway/tools-invoke-http-api.md create mode 100644 docs/id/gateway/troubleshooting.md create mode 100644 docs/id/gateway/trusted-proxy-auth.md create mode 100644 docs/id/help/debugging.md create mode 100644 docs/id/help/environment.md create mode 100644 docs/id/help/faq.md create mode 100644 docs/id/help/index.md create mode 100644 docs/id/help/scripts.md create mode 100644 docs/id/help/testing.md create mode 100644 docs/id/help/troubleshooting.md create mode 100644 docs/id/index.md create mode 100644 docs/id/install/ansible.md create mode 100644 docs/id/install/azure.md create mode 100644 docs/id/install/bun.md create mode 100644 docs/id/install/clawdock.md create mode 100644 docs/id/install/development-channels.md create mode 100644 docs/id/install/digitalocean.md create mode 100644 docs/id/install/docker-vm-runtime.md create mode 100644 docs/id/install/docker.md create mode 100644 docs/id/install/exe-dev.md create mode 100644 docs/id/install/fly.md create mode 100644 docs/id/install/gcp.md create mode 100644 docs/id/install/hetzner.md create mode 100644 docs/id/install/index.md create mode 100644 docs/id/install/installer.md create mode 100644 docs/id/install/kubernetes.md create mode 100644 docs/id/install/macos-vm.md create mode 100644 docs/id/install/migrating-matrix.md create mode 100644 docs/id/install/migrating.md create mode 100644 docs/id/install/nix.md create mode 100644 docs/id/install/node.md create mode 100644 docs/id/install/northflank.mdx create mode 100644 docs/id/install/oracle.md create mode 100644 docs/id/install/podman.md create mode 100644 docs/id/install/railway.mdx create mode 100644 docs/id/install/raspberry-pi.md create mode 100644 docs/id/install/render.mdx create mode 100644 docs/id/install/uninstall.md create mode 100644 docs/id/install/updating.md create mode 100644 docs/id/logging.md create mode 100644 docs/id/network.md create mode 100644 docs/id/nodes/audio.md create mode 100644 docs/id/nodes/camera.md create mode 100644 docs/id/nodes/images.md create mode 100644 docs/id/nodes/index.md create mode 100644 docs/id/nodes/location-command.md create mode 100644 docs/id/nodes/media-understanding.md create mode 100644 docs/id/nodes/talk.md create mode 100644 docs/id/nodes/troubleshooting.md create mode 100644 docs/id/nodes/voicewake.md create mode 100644 docs/id/perplexity.md create mode 100644 docs/id/pi-dev.md create mode 100644 docs/id/pi.md create mode 100644 docs/id/platforms/android.md create mode 100644 docs/id/platforms/digitalocean.md create mode 100644 docs/id/platforms/index.md create mode 100644 docs/id/platforms/ios.md create mode 100644 docs/id/platforms/linux.md create mode 100644 docs/id/platforms/mac/bundled-gateway.md create mode 100644 docs/id/platforms/mac/canvas.md create mode 100644 docs/id/platforms/mac/child-process.md create mode 100644 docs/id/platforms/mac/dev-setup.md create mode 100644 docs/id/platforms/mac/health.md create mode 100644 docs/id/platforms/mac/icon.md create mode 100644 docs/id/platforms/mac/logging.md create mode 100644 docs/id/platforms/mac/menu-bar.md create mode 100644 docs/id/platforms/mac/peekaboo.md create mode 100644 docs/id/platforms/mac/permissions.md create mode 100644 docs/id/platforms/mac/remote.md create mode 100644 docs/id/platforms/mac/signing.md create mode 100644 docs/id/platforms/mac/skills.md create mode 100644 docs/id/platforms/mac/voice-overlay.md create mode 100644 docs/id/platforms/mac/voicewake.md create mode 100644 docs/id/platforms/mac/webchat.md create mode 100644 docs/id/platforms/mac/xpc.md create mode 100644 docs/id/platforms/macos.md create mode 100644 docs/id/platforms/oracle.md create mode 100644 docs/id/platforms/raspberry-pi.md create mode 100644 docs/id/platforms/windows.md create mode 100644 docs/id/plugins/agent-tools.md create mode 100644 docs/id/plugins/architecture.md create mode 100644 docs/id/plugins/building-extensions.md create mode 100644 docs/id/plugins/building-plugins.md create mode 100644 docs/id/plugins/bundles.md create mode 100644 docs/id/plugins/community.md create mode 100644 docs/id/plugins/manifest.md create mode 100644 docs/id/plugins/sdk-channel-plugins.md create mode 100644 docs/id/plugins/sdk-entrypoints.md create mode 100644 docs/id/plugins/sdk-migration.md create mode 100644 docs/id/plugins/sdk-overview.md create mode 100644 docs/id/plugins/sdk-provider-plugins.md create mode 100644 docs/id/plugins/sdk-runtime.md create mode 100644 docs/id/plugins/sdk-setup.md create mode 100644 docs/id/plugins/sdk-testing.md create mode 100644 docs/id/plugins/voice-call.md create mode 100644 docs/id/plugins/zalouser.md create mode 100644 docs/id/prose.md create mode 100644 docs/id/providers/anthropic.md create mode 100644 docs/id/providers/bedrock-mantle.md create mode 100644 docs/id/providers/bedrock.md create mode 100644 docs/id/providers/chutes.md create mode 100644 docs/id/providers/claude-max-api-proxy.md create mode 100644 docs/id/providers/cloudflare-ai-gateway.md create mode 100644 docs/id/providers/deepgram.md create mode 100644 docs/id/providers/deepseek.md create mode 100644 docs/id/providers/fireworks.md create mode 100644 docs/id/providers/github-copilot.md create mode 100644 docs/id/providers/glm.md create mode 100644 docs/id/providers/google.md create mode 100644 docs/id/providers/groq.md create mode 100644 docs/id/providers/huggingface.md create mode 100644 docs/id/providers/index.md create mode 100644 docs/id/providers/kilocode.md create mode 100644 docs/id/providers/litellm.md create mode 100644 docs/id/providers/minimax.md create mode 100644 docs/id/providers/mistral.md create mode 100644 docs/id/providers/models.md create mode 100644 docs/id/providers/moonshot.md create mode 100644 docs/id/providers/nvidia.md create mode 100644 docs/id/providers/ollama.md create mode 100644 docs/id/providers/openai.md create mode 100644 docs/id/providers/opencode-go.md create mode 100644 docs/id/providers/opencode.md create mode 100644 docs/id/providers/openrouter.md create mode 100644 docs/id/providers/perplexity-provider.md create mode 100644 docs/id/providers/qianfan.md create mode 100644 docs/id/providers/qwen.md create mode 100644 docs/id/providers/qwen_modelstudio.md create mode 100644 docs/id/providers/sglang.md create mode 100644 docs/id/providers/stepfun.md create mode 100644 docs/id/providers/synthetic.md create mode 100644 docs/id/providers/together.md create mode 100644 docs/id/providers/venice.md create mode 100644 docs/id/providers/vercel-ai-gateway.md create mode 100644 docs/id/providers/vllm.md create mode 100644 docs/id/providers/volcengine.md create mode 100644 docs/id/providers/xai.md create mode 100644 docs/id/providers/xiaomi.md create mode 100644 docs/id/providers/zai.md create mode 100644 docs/id/reference/AGENTS.default.md create mode 100644 docs/id/reference/RELEASING.md create mode 100644 docs/id/reference/api-usage-costs.md create mode 100644 docs/id/reference/credits.md create mode 100644 docs/id/reference/device-models.md create mode 100644 docs/id/reference/memory-config.md create mode 100644 docs/id/reference/prompt-caching.md create mode 100644 docs/id/reference/rpc.md create mode 100644 docs/id/reference/secretref-credential-surface.md create mode 100644 docs/id/reference/session-management-compaction.md create mode 100644 docs/id/reference/templates/AGENTS.dev.md create mode 100644 docs/id/reference/templates/AGENTS.md create mode 100644 docs/id/reference/templates/BOOT.md create mode 100644 docs/id/reference/templates/BOOTSTRAP.md create mode 100644 docs/id/reference/templates/CLAUDE.md create mode 100644 docs/id/reference/templates/HEARTBEAT.md create mode 100644 docs/id/reference/templates/IDENTITY.dev.md create mode 100644 docs/id/reference/templates/IDENTITY.md create mode 100644 docs/id/reference/templates/SOUL.dev.md create mode 100644 docs/id/reference/templates/SOUL.md create mode 100644 docs/id/reference/templates/TOOLS.dev.md create mode 100644 docs/id/reference/templates/TOOLS.md create mode 100644 docs/id/reference/templates/USER.dev.md create mode 100644 docs/id/reference/templates/USER.md create mode 100644 docs/id/reference/test.md create mode 100644 docs/id/reference/token-use.md create mode 100644 docs/id/reference/transcript-hygiene.md create mode 100644 docs/id/reference/wizard.md create mode 100644 docs/id/security/CONTRIBUTING-THREAT-MODEL.md create mode 100644 docs/id/security/THREAT-MODEL-ATLAS.md create mode 100644 docs/id/security/formal-verification.md create mode 100644 docs/id/start/bootstrapping.md create mode 100644 docs/id/start/docs-directory.md create mode 100644 docs/id/start/getting-started.md create mode 100644 docs/id/start/hubs.md create mode 100644 docs/id/start/lore.md create mode 100644 docs/id/start/onboarding-overview.md create mode 100644 docs/id/start/onboarding.md create mode 100644 docs/id/start/openclaw.md create mode 100644 docs/id/start/quickstart.md create mode 100644 docs/id/start/setup.md create mode 100644 docs/id/start/showcase.md create mode 100644 docs/id/start/wizard-cli-automation.md create mode 100644 docs/id/start/wizard-cli-reference.md create mode 100644 docs/id/start/wizard.md create mode 100644 docs/id/tools/acp-agents.md create mode 100644 docs/id/tools/agent-send.md create mode 100644 docs/id/tools/apply-patch.md create mode 100644 docs/id/tools/brave-search.md create mode 100644 docs/id/tools/browser-linux-troubleshooting.md create mode 100644 docs/id/tools/browser-login.md create mode 100644 docs/id/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md create mode 100644 docs/id/tools/browser.md create mode 100644 docs/id/tools/btw.md create mode 100644 docs/id/tools/capability-cookbook.md create mode 100644 docs/id/tools/clawhub.md create mode 100644 docs/id/tools/code-execution.md create mode 100644 docs/id/tools/creating-skills.md create mode 100644 docs/id/tools/diffs.md create mode 100644 docs/id/tools/duckduckgo-search.md create mode 100644 docs/id/tools/elevated.md create mode 100644 docs/id/tools/exa-search.md create mode 100644 docs/id/tools/exec-approvals.md create mode 100644 docs/id/tools/exec.md create mode 100644 docs/id/tools/firecrawl.md create mode 100644 docs/id/tools/gemini-search.md create mode 100644 docs/id/tools/grok-search.md create mode 100644 docs/id/tools/image-generation.md create mode 100644 docs/id/tools/index.md create mode 100644 docs/id/tools/kimi-search.md create mode 100644 docs/id/tools/llm-task.md create mode 100644 docs/id/tools/lobster.md create mode 100644 docs/id/tools/loop-detection.md create mode 100644 docs/id/tools/minimax-search.md create mode 100644 docs/id/tools/multi-agent-sandbox-tools.md create mode 100644 docs/id/tools/ollama-search.md create mode 100644 docs/id/tools/pdf.md create mode 100644 docs/id/tools/perplexity-search.md create mode 100644 docs/id/tools/plugin.md create mode 100644 docs/id/tools/reactions.md create mode 100644 docs/id/tools/searxng-search.md create mode 100644 docs/id/tools/skills-config.md create mode 100644 docs/id/tools/skills.md create mode 100644 docs/id/tools/slash-commands.md create mode 100644 docs/id/tools/subagents.md create mode 100644 docs/id/tools/tavily.md create mode 100644 docs/id/tools/thinking.md create mode 100644 docs/id/tools/tts.md create mode 100644 docs/id/tools/web-fetch.md create mode 100644 docs/id/tools/web.md create mode 100644 docs/id/tts.md create mode 100644 docs/id/vps.md create mode 100644 docs/id/web/control-ui.md create mode 100644 docs/id/web/dashboard.md create mode 100644 docs/id/web/index.md create mode 100644 docs/id/web/tui.md create mode 100644 docs/id/web/webchat.md create mode 100644 docs/it/.i18n/README.md create mode 100644 docs/it/auth-credential-semantics.md create mode 100644 docs/it/automation/auth-monitoring.md create mode 100644 docs/it/automation/clawflow.md create mode 100644 docs/it/automation/cron-jobs.md create mode 100644 docs/it/automation/cron-vs-heartbeat.md create mode 100644 docs/it/automation/gmail-pubsub.md create mode 100644 docs/it/automation/hooks.md create mode 100644 docs/it/automation/index.md create mode 100644 docs/it/automation/poll.md create mode 100644 docs/it/automation/standing-orders.md create mode 100644 docs/it/automation/taskflow.md create mode 100644 docs/it/automation/tasks.md create mode 100644 docs/it/automation/troubleshooting.md create mode 100644 docs/it/automation/webhook.md create mode 100644 docs/it/brave-search.md create mode 100644 docs/it/channels/bluebubbles.md create mode 100644 docs/it/channels/broadcast-groups.md create mode 100644 docs/it/channels/channel-routing.md create mode 100644 docs/it/channels/discord.md create mode 100644 docs/it/channels/feishu.md create mode 100644 docs/it/channels/googlechat.md create mode 100644 docs/it/channels/group-messages.md create mode 100644 docs/it/channels/groups.md create mode 100644 docs/it/channels/imessage.md create mode 100644 docs/it/channels/index.md create mode 100644 docs/it/channels/irc.md create mode 100644 docs/it/channels/line.md create mode 100644 docs/it/channels/location.md create mode 100644 docs/it/channels/matrix.md create mode 100644 docs/it/channels/mattermost.md create mode 100644 docs/it/channels/msteams.md create mode 100644 docs/it/channels/nextcloud-talk.md create mode 100644 docs/it/channels/nostr.md create mode 100644 docs/it/channels/pairing.md create mode 100644 docs/it/channels/qqbot.md create mode 100644 docs/it/channels/signal.md create mode 100644 docs/it/channels/slack.md create mode 100644 docs/it/channels/synology-chat.md create mode 100644 docs/it/channels/telegram.md create mode 100644 docs/it/channels/tlon.md create mode 100644 docs/it/channels/troubleshooting.md create mode 100644 docs/it/channels/twitch.md create mode 100644 docs/it/channels/whatsapp.md create mode 100644 docs/it/channels/zalo.md create mode 100644 docs/it/channels/zalouser.md create mode 100644 docs/it/ci.md create mode 100644 docs/it/cli/acp.md create mode 100644 docs/it/cli/agent.md create mode 100644 docs/it/cli/agents.md create mode 100644 docs/it/cli/approvals.md create mode 100644 docs/it/cli/backup.md create mode 100644 docs/it/cli/browser.md create mode 100644 docs/it/cli/channels.md create mode 100644 docs/it/cli/clawbot.md create mode 100644 docs/it/cli/completion.md create mode 100644 docs/it/cli/config.md create mode 100644 docs/it/cli/configure.md create mode 100644 docs/it/cli/cron.md create mode 100644 docs/it/cli/daemon.md create mode 100644 docs/it/cli/dashboard.md create mode 100644 docs/it/cli/devices.md create mode 100644 docs/it/cli/directory.md create mode 100644 docs/it/cli/dns.md create mode 100644 docs/it/cli/docs.md create mode 100644 docs/it/cli/doctor.md create mode 100644 docs/it/cli/flows.md create mode 100644 docs/it/cli/gateway.md create mode 100644 docs/it/cli/health.md create mode 100644 docs/it/cli/hooks.md create mode 100644 docs/it/cli/index.md create mode 100644 docs/it/cli/logs.md create mode 100644 docs/it/cli/mcp.md create mode 100644 docs/it/cli/memory.md create mode 100644 docs/it/cli/message.md create mode 100644 docs/it/cli/models.md create mode 100644 docs/it/cli/node.md create mode 100644 docs/it/cli/nodes.md create mode 100644 docs/it/cli/onboard.md create mode 100644 docs/it/cli/pairing.md create mode 100644 docs/it/cli/plugins.md create mode 100644 docs/it/cli/qr.md create mode 100644 docs/it/cli/reset.md create mode 100644 docs/it/cli/sandbox.md create mode 100644 docs/it/cli/secrets.md create mode 100644 docs/it/cli/security.md create mode 100644 docs/it/cli/sessions.md create mode 100644 docs/it/cli/setup.md create mode 100644 docs/it/cli/skills.md create mode 100644 docs/it/cli/status.md create mode 100644 docs/it/cli/system.md create mode 100644 docs/it/cli/tui.md create mode 100644 docs/it/cli/uninstall.md create mode 100644 docs/it/cli/update.md create mode 100644 docs/it/cli/voicecall.md create mode 100644 docs/it/cli/webhooks.md create mode 100644 docs/it/concepts/agent-loop.md create mode 100644 docs/it/concepts/agent-workspace.md create mode 100644 docs/it/concepts/agent.md create mode 100644 docs/it/concepts/architecture.md create mode 100644 docs/it/concepts/compaction.md create mode 100644 docs/it/concepts/context-engine.md create mode 100644 docs/it/concepts/context.md create mode 100644 docs/it/concepts/delegate-architecture.md create mode 100644 docs/it/concepts/features.md create mode 100644 docs/it/concepts/markdown-formatting.md create mode 100644 docs/it/concepts/memory-builtin.md create mode 100644 docs/it/concepts/memory-dreaming.md create mode 100644 docs/it/concepts/memory-honcho.md create mode 100644 docs/it/concepts/memory-qmd.md create mode 100644 docs/it/concepts/memory-search.md create mode 100644 docs/it/concepts/memory.md create mode 100644 docs/it/concepts/messages.md create mode 100644 docs/it/concepts/model-failover.md create mode 100644 docs/it/concepts/model-providers.md create mode 100644 docs/it/concepts/models.md create mode 100644 docs/it/concepts/multi-agent.md create mode 100644 docs/it/concepts/oauth.md create mode 100644 docs/it/concepts/presence.md create mode 100644 docs/it/concepts/queue.md create mode 100644 docs/it/concepts/retry.md create mode 100644 docs/it/concepts/session-pruning.md create mode 100644 docs/it/concepts/session-tool.md create mode 100644 docs/it/concepts/session.md create mode 100644 docs/it/concepts/soul.md create mode 100644 docs/it/concepts/streaming.md create mode 100644 docs/it/concepts/system-prompt.md create mode 100644 docs/it/concepts/timezone.md create mode 100644 docs/it/concepts/typebox.md create mode 100644 docs/it/concepts/typing-indicators.md create mode 100644 docs/it/concepts/usage-tracking.md create mode 100644 docs/it/date-time.md create mode 100644 docs/it/debug/node-issue.md create mode 100644 docs/it/diagnostics/flags.md create mode 100644 docs/it/gateway/authentication.md create mode 100644 docs/it/gateway/background-process.md create mode 100644 docs/it/gateway/bonjour.md create mode 100644 docs/it/gateway/bridge-protocol.md create mode 100644 docs/it/gateway/cli-backends.md create mode 100644 docs/it/gateway/configuration-examples.md create mode 100644 docs/it/gateway/configuration-reference.md create mode 100644 docs/it/gateway/configuration.md create mode 100644 docs/it/gateway/discovery.md create mode 100644 docs/it/gateway/doctor.md create mode 100644 docs/it/gateway/gateway-lock.md create mode 100644 docs/it/gateway/health.md create mode 100644 docs/it/gateway/heartbeat.md create mode 100644 docs/it/gateway/index.md create mode 100644 docs/it/gateway/local-models.md create mode 100644 docs/it/gateway/logging.md create mode 100644 docs/it/gateway/multiple-gateways.md create mode 100644 docs/it/gateway/network-model.md create mode 100644 docs/it/gateway/openai-http-api.md create mode 100644 docs/it/gateway/openresponses-http-api.md create mode 100644 docs/it/gateway/openshell.md create mode 100644 docs/it/gateway/pairing.md create mode 100644 docs/it/gateway/protocol.md create mode 100644 docs/it/gateway/remote-gateway-readme.md create mode 100644 docs/it/gateway/remote.md create mode 100644 docs/it/gateway/sandbox-vs-tool-policy-vs-elevated.md create mode 100644 docs/it/gateway/sandboxing.md create mode 100644 docs/it/gateway/secrets-plan-contract.md create mode 100644 docs/it/gateway/secrets.md create mode 100644 docs/it/gateway/security/index.md create mode 100644 docs/it/gateway/tailscale.md create mode 100644 docs/it/gateway/tools-invoke-http-api.md create mode 100644 docs/it/gateway/troubleshooting.md create mode 100644 docs/it/gateway/trusted-proxy-auth.md create mode 100644 docs/it/help/debugging.md create mode 100644 docs/it/help/environment.md create mode 100644 docs/it/help/faq.md create mode 100644 docs/it/help/index.md create mode 100644 docs/it/help/scripts.md create mode 100644 docs/it/help/testing.md create mode 100644 docs/it/help/troubleshooting.md create mode 100644 docs/it/index.md create mode 100644 docs/it/install/ansible.md create mode 100644 docs/it/install/azure.md create mode 100644 docs/it/install/bun.md create mode 100644 docs/it/install/clawdock.md create mode 100644 docs/it/install/development-channels.md create mode 100644 docs/it/install/digitalocean.md create mode 100644 docs/it/install/docker-vm-runtime.md create mode 100644 docs/it/install/docker.md create mode 100644 docs/it/install/exe-dev.md create mode 100644 docs/it/install/fly.md create mode 100644 docs/it/install/gcp.md create mode 100644 docs/it/install/hetzner.md create mode 100644 docs/it/install/index.md create mode 100644 docs/it/install/installer.md create mode 100644 docs/it/install/kubernetes.md create mode 100644 docs/it/install/macos-vm.md create mode 100644 docs/it/install/migrating-matrix.md create mode 100644 docs/it/install/migrating.md create mode 100644 docs/it/install/nix.md create mode 100644 docs/it/install/node.md create mode 100644 docs/it/install/northflank.mdx create mode 100644 docs/it/install/oracle.md create mode 100644 docs/it/install/podman.md create mode 100644 docs/it/install/railway.mdx create mode 100644 docs/it/install/raspberry-pi.md create mode 100644 docs/it/install/render.mdx create mode 100644 docs/it/install/uninstall.md create mode 100644 docs/it/install/updating.md create mode 100644 docs/it/logging.md create mode 100644 docs/it/network.md create mode 100644 docs/it/nodes/audio.md create mode 100644 docs/it/nodes/camera.md create mode 100644 docs/it/nodes/images.md create mode 100644 docs/it/nodes/index.md create mode 100644 docs/it/nodes/location-command.md create mode 100644 docs/it/nodes/media-understanding.md create mode 100644 docs/it/nodes/talk.md create mode 100644 docs/it/nodes/troubleshooting.md create mode 100644 docs/it/nodes/voicewake.md create mode 100644 docs/it/perplexity.md create mode 100644 docs/it/pi-dev.md create mode 100644 docs/it/pi.md create mode 100644 docs/it/platforms/android.md create mode 100644 docs/it/platforms/digitalocean.md create mode 100644 docs/it/platforms/index.md create mode 100644 docs/it/platforms/ios.md create mode 100644 docs/it/platforms/linux.md create mode 100644 docs/it/platforms/mac/bundled-gateway.md create mode 100644 docs/it/platforms/mac/canvas.md create mode 100644 docs/it/platforms/mac/child-process.md create mode 100644 docs/it/platforms/mac/dev-setup.md create mode 100644 docs/it/platforms/mac/health.md create mode 100644 docs/it/platforms/mac/icon.md create mode 100644 docs/it/platforms/mac/logging.md create mode 100644 docs/it/platforms/mac/menu-bar.md create mode 100644 docs/it/platforms/mac/peekaboo.md create mode 100644 docs/it/platforms/mac/permissions.md create mode 100644 docs/it/platforms/mac/remote.md create mode 100644 docs/it/platforms/mac/signing.md create mode 100644 docs/it/platforms/mac/skills.md create mode 100644 docs/it/platforms/mac/voice-overlay.md create mode 100644 docs/it/platforms/mac/voicewake.md create mode 100644 docs/it/platforms/mac/webchat.md create mode 100644 docs/it/platforms/mac/xpc.md create mode 100644 docs/it/platforms/macos.md create mode 100644 docs/it/platforms/oracle.md create mode 100644 docs/it/platforms/raspberry-pi.md create mode 100644 docs/it/platforms/windows.md create mode 100644 docs/it/plugins/agent-tools.md create mode 100644 docs/it/plugins/architecture.md create mode 100644 docs/it/plugins/building-extensions.md create mode 100644 docs/it/plugins/building-plugins.md create mode 100644 docs/it/plugins/bundles.md create mode 100644 docs/it/plugins/community.md create mode 100644 docs/it/plugins/manifest.md create mode 100644 docs/it/plugins/sdk-channel-plugins.md create mode 100644 docs/it/plugins/sdk-entrypoints.md create mode 100644 docs/it/plugins/sdk-migration.md create mode 100644 docs/it/plugins/sdk-overview.md create mode 100644 docs/it/plugins/sdk-provider-plugins.md create mode 100644 docs/it/plugins/sdk-runtime.md create mode 100644 docs/it/plugins/sdk-setup.md create mode 100644 docs/it/plugins/sdk-testing.md create mode 100644 docs/it/plugins/voice-call.md create mode 100644 docs/it/plugins/zalouser.md create mode 100644 docs/it/prose.md create mode 100644 docs/it/providers/anthropic.md create mode 100644 docs/it/providers/bedrock-mantle.md create mode 100644 docs/it/providers/bedrock.md create mode 100644 docs/it/providers/chutes.md create mode 100644 docs/it/providers/claude-max-api-proxy.md create mode 100644 docs/it/providers/cloudflare-ai-gateway.md create mode 100644 docs/it/providers/deepgram.md create mode 100644 docs/it/providers/deepseek.md create mode 100644 docs/it/providers/fireworks.md create mode 100644 docs/it/providers/github-copilot.md create mode 100644 docs/it/providers/glm.md create mode 100644 docs/it/providers/google.md create mode 100644 docs/it/providers/groq.md create mode 100644 docs/it/providers/huggingface.md create mode 100644 docs/it/providers/index.md create mode 100644 docs/it/providers/kilocode.md create mode 100644 docs/it/providers/litellm.md create mode 100644 docs/it/providers/minimax.md create mode 100644 docs/it/providers/mistral.md create mode 100644 docs/it/providers/models.md create mode 100644 docs/it/providers/moonshot.md create mode 100644 docs/it/providers/nvidia.md create mode 100644 docs/it/providers/ollama.md create mode 100644 docs/it/providers/openai.md create mode 100644 docs/it/providers/opencode-go.md create mode 100644 docs/it/providers/opencode.md create mode 100644 docs/it/providers/openrouter.md create mode 100644 docs/it/providers/perplexity-provider.md create mode 100644 docs/it/providers/qianfan.md create mode 100644 docs/it/providers/qwen.md create mode 100644 docs/it/providers/qwen_modelstudio.md create mode 100644 docs/it/providers/sglang.md create mode 100644 docs/it/providers/stepfun.md create mode 100644 docs/it/providers/synthetic.md create mode 100644 docs/it/providers/together.md create mode 100644 docs/it/providers/venice.md create mode 100644 docs/it/providers/vercel-ai-gateway.md create mode 100644 docs/it/providers/vllm.md create mode 100644 docs/it/providers/volcengine.md create mode 100644 docs/it/providers/xai.md create mode 100644 docs/it/providers/xiaomi.md create mode 100644 docs/it/providers/zai.md create mode 100644 docs/it/reference/AGENTS.default.md create mode 100644 docs/it/reference/RELEASING.md create mode 100644 docs/it/reference/api-usage-costs.md create mode 100644 docs/it/reference/credits.md create mode 100644 docs/it/reference/device-models.md create mode 100644 docs/it/reference/memory-config.md create mode 100644 docs/it/reference/prompt-caching.md create mode 100644 docs/it/reference/rpc.md create mode 100644 docs/it/reference/secretref-credential-surface.md create mode 100644 docs/it/reference/session-management-compaction.md create mode 100644 docs/it/reference/templates/AGENTS.dev.md create mode 100644 docs/it/reference/templates/AGENTS.md create mode 100644 docs/it/reference/templates/BOOT.md create mode 100644 docs/it/reference/templates/BOOTSTRAP.md create mode 100644 docs/it/reference/templates/CLAUDE.md create mode 100644 docs/it/reference/templates/HEARTBEAT.md create mode 100644 docs/it/reference/templates/IDENTITY.dev.md create mode 100644 docs/it/reference/templates/IDENTITY.md create mode 100644 docs/it/reference/templates/SOUL.dev.md create mode 100644 docs/it/reference/templates/SOUL.md create mode 100644 docs/it/reference/templates/TOOLS.dev.md create mode 100644 docs/it/reference/templates/TOOLS.md create mode 100644 docs/it/reference/templates/USER.dev.md create mode 100644 docs/it/reference/templates/USER.md create mode 100644 docs/it/reference/test.md create mode 100644 docs/it/reference/token-use.md create mode 100644 docs/it/reference/transcript-hygiene.md create mode 100644 docs/it/reference/wizard.md create mode 100644 docs/it/security/CONTRIBUTING-THREAT-MODEL.md create mode 100644 docs/it/security/THREAT-MODEL-ATLAS.md create mode 100644 docs/it/security/formal-verification.md create mode 100644 docs/it/start/bootstrapping.md create mode 100644 docs/it/start/docs-directory.md create mode 100644 docs/it/start/getting-started.md create mode 100644 docs/it/start/hubs.md create mode 100644 docs/it/start/lore.md create mode 100644 docs/it/start/onboarding-overview.md create mode 100644 docs/it/start/onboarding.md create mode 100644 docs/it/start/openclaw.md create mode 100644 docs/it/start/quickstart.md create mode 100644 docs/it/start/setup.md create mode 100644 docs/it/start/showcase.md create mode 100644 docs/it/start/wizard-cli-automation.md create mode 100644 docs/it/start/wizard-cli-reference.md create mode 100644 docs/it/start/wizard.md create mode 100644 docs/it/tools/acp-agents.md create mode 100644 docs/it/tools/agent-send.md create mode 100644 docs/it/tools/apply-patch.md create mode 100644 docs/it/tools/brave-search.md create mode 100644 docs/it/tools/browser-linux-troubleshooting.md create mode 100644 docs/it/tools/browser-login.md create mode 100644 docs/it/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md create mode 100644 docs/it/tools/browser.md create mode 100644 docs/it/tools/btw.md create mode 100644 docs/it/tools/capability-cookbook.md create mode 100644 docs/it/tools/clawhub.md create mode 100644 docs/it/tools/code-execution.md create mode 100644 docs/it/tools/creating-skills.md create mode 100644 docs/it/tools/diffs.md create mode 100644 docs/it/tools/duckduckgo-search.md create mode 100644 docs/it/tools/elevated.md create mode 100644 docs/it/tools/exa-search.md create mode 100644 docs/it/tools/exec-approvals.md create mode 100644 docs/it/tools/exec.md create mode 100644 docs/it/tools/firecrawl.md create mode 100644 docs/it/tools/gemini-search.md create mode 100644 docs/it/tools/grok-search.md create mode 100644 docs/it/tools/image-generation.md create mode 100644 docs/it/tools/index.md create mode 100644 docs/it/tools/kimi-search.md create mode 100644 docs/it/tools/llm-task.md create mode 100644 docs/it/tools/lobster.md create mode 100644 docs/it/tools/loop-detection.md create mode 100644 docs/it/tools/minimax-search.md create mode 100644 docs/it/tools/multi-agent-sandbox-tools.md create mode 100644 docs/it/tools/ollama-search.md create mode 100644 docs/it/tools/pdf.md create mode 100644 docs/it/tools/perplexity-search.md create mode 100644 docs/it/tools/plugin.md create mode 100644 docs/it/tools/reactions.md create mode 100644 docs/it/tools/searxng-search.md create mode 100644 docs/it/tools/skills-config.md create mode 100644 docs/it/tools/skills.md create mode 100644 docs/it/tools/slash-commands.md create mode 100644 docs/it/tools/subagents.md create mode 100644 docs/it/tools/tavily.md create mode 100644 docs/it/tools/thinking.md create mode 100644 docs/it/tools/tts.md create mode 100644 docs/it/tools/web-fetch.md create mode 100644 docs/it/tools/web.md create mode 100644 docs/it/tts.md create mode 100644 docs/it/vps.md create mode 100644 docs/it/web/control-ui.md create mode 100644 docs/it/web/dashboard.md create mode 100644 docs/it/web/index.md create mode 100644 docs/it/web/tui.md create mode 100644 docs/it/web/webchat.md create mode 100644 docs/pl/.i18n/README.md create mode 100644 docs/pl/auth-credential-semantics.md create mode 100644 docs/pl/automation/auth-monitoring.md create mode 100644 docs/pl/automation/clawflow.md create mode 100644 docs/pl/automation/cron-jobs.md create mode 100644 docs/pl/automation/cron-vs-heartbeat.md create mode 100644 docs/pl/automation/gmail-pubsub.md create mode 100644 docs/pl/automation/hooks.md create mode 100644 docs/pl/automation/index.md create mode 100644 docs/pl/automation/poll.md create mode 100644 docs/pl/automation/standing-orders.md create mode 100644 docs/pl/automation/taskflow.md create mode 100644 docs/pl/automation/tasks.md create mode 100644 docs/pl/automation/troubleshooting.md create mode 100644 docs/pl/automation/webhook.md create mode 100644 docs/pl/brave-search.md create mode 100644 docs/pl/channels/bluebubbles.md create mode 100644 docs/pl/channels/broadcast-groups.md create mode 100644 docs/pl/channels/channel-routing.md create mode 100644 docs/pl/channels/discord.md create mode 100644 docs/pl/channels/feishu.md create mode 100644 docs/pl/channels/googlechat.md create mode 100644 docs/pl/channels/group-messages.md create mode 100644 docs/pl/channels/groups.md create mode 100644 docs/pl/channels/imessage.md create mode 100644 docs/pl/channels/index.md create mode 100644 docs/pl/channels/irc.md create mode 100644 docs/pl/channels/line.md create mode 100644 docs/pl/channels/location.md create mode 100644 docs/pl/channels/matrix.md create mode 100644 docs/pl/channels/mattermost.md create mode 100644 docs/pl/channels/msteams.md create mode 100644 docs/pl/channels/nextcloud-talk.md create mode 100644 docs/pl/channels/nostr.md create mode 100644 docs/pl/channels/pairing.md create mode 100644 docs/pl/channels/qqbot.md create mode 100644 docs/pl/channels/signal.md create mode 100644 docs/pl/channels/slack.md create mode 100644 docs/pl/channels/synology-chat.md create mode 100644 docs/pl/channels/telegram.md create mode 100644 docs/pl/channels/tlon.md create mode 100644 docs/pl/channels/troubleshooting.md create mode 100644 docs/pl/channels/twitch.md create mode 100644 docs/pl/channels/whatsapp.md create mode 100644 docs/pl/channels/zalo.md create mode 100644 docs/pl/channels/zalouser.md create mode 100644 docs/pl/ci.md create mode 100644 docs/pl/cli/acp.md create mode 100644 docs/pl/cli/agent.md create mode 100644 docs/pl/cli/agents.md create mode 100644 docs/pl/cli/approvals.md create mode 100644 docs/pl/cli/backup.md create mode 100644 docs/pl/cli/browser.md create mode 100644 docs/pl/cli/channels.md create mode 100644 docs/pl/cli/clawbot.md create mode 100644 docs/pl/cli/completion.md create mode 100644 docs/pl/cli/config.md create mode 100644 docs/pl/cli/configure.md create mode 100644 docs/pl/cli/cron.md create mode 100644 docs/pl/cli/daemon.md create mode 100644 docs/pl/cli/dashboard.md create mode 100644 docs/pl/cli/devices.md create mode 100644 docs/pl/cli/directory.md create mode 100644 docs/pl/cli/dns.md create mode 100644 docs/pl/cli/docs.md create mode 100644 docs/pl/cli/doctor.md create mode 100644 docs/pl/cli/flows.md create mode 100644 docs/pl/cli/gateway.md create mode 100644 docs/pl/cli/health.md create mode 100644 docs/pl/cli/hooks.md create mode 100644 docs/pl/cli/index.md create mode 100644 docs/pl/cli/logs.md create mode 100644 docs/pl/cli/mcp.md create mode 100644 docs/pl/cli/memory.md create mode 100644 docs/pl/cli/message.md create mode 100644 docs/pl/cli/models.md create mode 100644 docs/pl/cli/node.md create mode 100644 docs/pl/cli/nodes.md create mode 100644 docs/pl/cli/onboard.md create mode 100644 docs/pl/cli/pairing.md create mode 100644 docs/pl/cli/plugins.md create mode 100644 docs/pl/cli/qr.md create mode 100644 docs/pl/cli/reset.md create mode 100644 docs/pl/cli/sandbox.md create mode 100644 docs/pl/cli/secrets.md create mode 100644 docs/pl/cli/security.md create mode 100644 docs/pl/cli/sessions.md create mode 100644 docs/pl/cli/setup.md create mode 100644 docs/pl/cli/skills.md create mode 100644 docs/pl/cli/status.md create mode 100644 docs/pl/cli/system.md create mode 100644 docs/pl/cli/tui.md create mode 100644 docs/pl/cli/uninstall.md create mode 100644 docs/pl/cli/update.md create mode 100644 docs/pl/cli/voicecall.md create mode 100644 docs/pl/cli/webhooks.md create mode 100644 docs/pl/concepts/agent-loop.md create mode 100644 docs/pl/concepts/agent-workspace.md create mode 100644 docs/pl/concepts/agent.md create mode 100644 docs/pl/concepts/architecture.md create mode 100644 docs/pl/concepts/compaction.md create mode 100644 docs/pl/concepts/context-engine.md create mode 100644 docs/pl/concepts/context.md create mode 100644 docs/pl/concepts/delegate-architecture.md create mode 100644 docs/pl/concepts/features.md create mode 100644 docs/pl/concepts/markdown-formatting.md create mode 100644 docs/pl/concepts/memory-builtin.md create mode 100644 docs/pl/concepts/memory-dreaming.md create mode 100644 docs/pl/concepts/memory-honcho.md create mode 100644 docs/pl/concepts/memory-qmd.md create mode 100644 docs/pl/concepts/memory-search.md create mode 100644 docs/pl/concepts/memory.md create mode 100644 docs/pl/concepts/messages.md create mode 100644 docs/pl/concepts/model-failover.md create mode 100644 docs/pl/concepts/model-providers.md create mode 100644 docs/pl/concepts/models.md create mode 100644 docs/pl/concepts/multi-agent.md create mode 100644 docs/pl/concepts/oauth.md create mode 100644 docs/pl/concepts/presence.md create mode 100644 docs/pl/concepts/queue.md create mode 100644 docs/pl/concepts/retry.md create mode 100644 docs/pl/concepts/session-pruning.md create mode 100644 docs/pl/concepts/session-tool.md create mode 100644 docs/pl/concepts/session.md create mode 100644 docs/pl/concepts/soul.md create mode 100644 docs/pl/concepts/streaming.md create mode 100644 docs/pl/concepts/system-prompt.md create mode 100644 docs/pl/concepts/timezone.md create mode 100644 docs/pl/concepts/typebox.md create mode 100644 docs/pl/concepts/typing-indicators.md create mode 100644 docs/pl/concepts/usage-tracking.md create mode 100644 docs/pl/date-time.md create mode 100644 docs/pl/debug/node-issue.md create mode 100644 docs/pl/diagnostics/flags.md create mode 100644 docs/pl/gateway/authentication.md create mode 100644 docs/pl/gateway/background-process.md create mode 100644 docs/pl/gateway/bonjour.md create mode 100644 docs/pl/gateway/bridge-protocol.md create mode 100644 docs/pl/gateway/cli-backends.md create mode 100644 docs/pl/gateway/configuration-examples.md create mode 100644 docs/pl/gateway/configuration-reference.md create mode 100644 docs/pl/gateway/configuration.md create mode 100644 docs/pl/gateway/discovery.md create mode 100644 docs/pl/gateway/doctor.md create mode 100644 docs/pl/gateway/gateway-lock.md create mode 100644 docs/pl/gateway/health.md create mode 100644 docs/pl/gateway/heartbeat.md create mode 100644 docs/pl/gateway/index.md create mode 100644 docs/pl/gateway/local-models.md create mode 100644 docs/pl/gateway/logging.md create mode 100644 docs/pl/gateway/multiple-gateways.md create mode 100644 docs/pl/gateway/network-model.md create mode 100644 docs/pl/gateway/openai-http-api.md create mode 100644 docs/pl/gateway/openresponses-http-api.md create mode 100644 docs/pl/gateway/openshell.md create mode 100644 docs/pl/gateway/pairing.md create mode 100644 docs/pl/gateway/protocol.md create mode 100644 docs/pl/gateway/remote-gateway-readme.md create mode 100644 docs/pl/gateway/remote.md create mode 100644 docs/pl/gateway/sandbox-vs-tool-policy-vs-elevated.md create mode 100644 docs/pl/gateway/sandboxing.md create mode 100644 docs/pl/gateway/secrets-plan-contract.md create mode 100644 docs/pl/gateway/secrets.md create mode 100644 docs/pl/gateway/security/index.md create mode 100644 docs/pl/gateway/tailscale.md create mode 100644 docs/pl/gateway/tools-invoke-http-api.md create mode 100644 docs/pl/gateway/troubleshooting.md create mode 100644 docs/pl/gateway/trusted-proxy-auth.md create mode 100644 docs/pl/help/debugging.md create mode 100644 docs/pl/help/environment.md create mode 100644 docs/pl/help/faq.md create mode 100644 docs/pl/help/index.md create mode 100644 docs/pl/help/scripts.md create mode 100644 docs/pl/help/testing.md create mode 100644 docs/pl/help/troubleshooting.md create mode 100644 docs/pl/index.md create mode 100644 docs/pl/install/ansible.md create mode 100644 docs/pl/install/azure.md create mode 100644 docs/pl/install/bun.md create mode 100644 docs/pl/install/clawdock.md create mode 100644 docs/pl/install/development-channels.md create mode 100644 docs/pl/install/digitalocean.md create mode 100644 docs/pl/install/docker-vm-runtime.md create mode 100644 docs/pl/install/docker.md create mode 100644 docs/pl/install/exe-dev.md create mode 100644 docs/pl/install/fly.md create mode 100644 docs/pl/install/gcp.md create mode 100644 docs/pl/install/hetzner.md create mode 100644 docs/pl/install/index.md create mode 100644 docs/pl/install/installer.md create mode 100644 docs/pl/install/kubernetes.md create mode 100644 docs/pl/install/macos-vm.md create mode 100644 docs/pl/install/migrating-matrix.md create mode 100644 docs/pl/install/migrating.md create mode 100644 docs/pl/install/nix.md create mode 100644 docs/pl/install/node.md create mode 100644 docs/pl/install/northflank.mdx create mode 100644 docs/pl/install/oracle.md create mode 100644 docs/pl/install/podman.md create mode 100644 docs/pl/install/railway.mdx create mode 100644 docs/pl/install/raspberry-pi.md create mode 100644 docs/pl/install/render.mdx create mode 100644 docs/pl/install/uninstall.md create mode 100644 docs/pl/install/updating.md create mode 100644 docs/pl/logging.md create mode 100644 docs/pl/network.md create mode 100644 docs/pl/nodes/audio.md create mode 100644 docs/pl/nodes/camera.md create mode 100644 docs/pl/nodes/images.md create mode 100644 docs/pl/nodes/index.md create mode 100644 docs/pl/nodes/location-command.md create mode 100644 docs/pl/nodes/media-understanding.md create mode 100644 docs/pl/nodes/talk.md create mode 100644 docs/pl/nodes/troubleshooting.md create mode 100644 docs/pl/nodes/voicewake.md create mode 100644 docs/pl/perplexity.md create mode 100644 docs/pl/pi-dev.md create mode 100644 docs/pl/pi.md create mode 100644 docs/pl/platforms/android.md create mode 100644 docs/pl/platforms/digitalocean.md create mode 100644 docs/pl/platforms/index.md create mode 100644 docs/pl/platforms/ios.md create mode 100644 docs/pl/platforms/linux.md create mode 100644 docs/pl/platforms/mac/bundled-gateway.md create mode 100644 docs/pl/platforms/mac/canvas.md create mode 100644 docs/pl/platforms/mac/child-process.md create mode 100644 docs/pl/platforms/mac/dev-setup.md create mode 100644 docs/pl/platforms/mac/health.md create mode 100644 docs/pl/platforms/mac/icon.md create mode 100644 docs/pl/platforms/mac/logging.md create mode 100644 docs/pl/platforms/mac/menu-bar.md create mode 100644 docs/pl/platforms/mac/peekaboo.md create mode 100644 docs/pl/platforms/mac/permissions.md create mode 100644 docs/pl/platforms/mac/remote.md create mode 100644 docs/pl/platforms/mac/signing.md create mode 100644 docs/pl/platforms/mac/skills.md create mode 100644 docs/pl/platforms/mac/voice-overlay.md create mode 100644 docs/pl/platforms/mac/voicewake.md create mode 100644 docs/pl/platforms/mac/webchat.md create mode 100644 docs/pl/platforms/mac/xpc.md create mode 100644 docs/pl/platforms/macos.md create mode 100644 docs/pl/platforms/oracle.md create mode 100644 docs/pl/platforms/raspberry-pi.md create mode 100644 docs/pl/platforms/windows.md create mode 100644 docs/pl/plugins/agent-tools.md create mode 100644 docs/pl/plugins/architecture.md create mode 100644 docs/pl/plugins/building-extensions.md create mode 100644 docs/pl/plugins/building-plugins.md create mode 100644 docs/pl/plugins/bundles.md create mode 100644 docs/pl/plugins/community.md create mode 100644 docs/pl/plugins/manifest.md create mode 100644 docs/pl/plugins/sdk-channel-plugins.md create mode 100644 docs/pl/plugins/sdk-entrypoints.md create mode 100644 docs/pl/plugins/sdk-migration.md create mode 100644 docs/pl/plugins/sdk-overview.md create mode 100644 docs/pl/plugins/sdk-provider-plugins.md create mode 100644 docs/pl/plugins/sdk-runtime.md create mode 100644 docs/pl/plugins/sdk-setup.md create mode 100644 docs/pl/plugins/sdk-testing.md create mode 100644 docs/pl/plugins/voice-call.md create mode 100644 docs/pl/plugins/zalouser.md create mode 100644 docs/pl/prose.md create mode 100644 docs/pl/providers/anthropic.md create mode 100644 docs/pl/providers/bedrock-mantle.md create mode 100644 docs/pl/providers/bedrock.md create mode 100644 docs/pl/providers/chutes.md create mode 100644 docs/pl/providers/claude-max-api-proxy.md create mode 100644 docs/pl/providers/cloudflare-ai-gateway.md create mode 100644 docs/pl/providers/deepgram.md create mode 100644 docs/pl/providers/deepseek.md create mode 100644 docs/pl/providers/fireworks.md create mode 100644 docs/pl/providers/github-copilot.md create mode 100644 docs/pl/providers/glm.md create mode 100644 docs/pl/providers/google.md create mode 100644 docs/pl/providers/groq.md create mode 100644 docs/pl/providers/huggingface.md create mode 100644 docs/pl/providers/index.md create mode 100644 docs/pl/providers/kilocode.md create mode 100644 docs/pl/providers/litellm.md create mode 100644 docs/pl/providers/minimax.md create mode 100644 docs/pl/providers/mistral.md create mode 100644 docs/pl/providers/models.md create mode 100644 docs/pl/providers/moonshot.md create mode 100644 docs/pl/providers/nvidia.md create mode 100644 docs/pl/providers/ollama.md create mode 100644 docs/pl/providers/openai.md create mode 100644 docs/pl/providers/opencode-go.md create mode 100644 docs/pl/providers/opencode.md create mode 100644 docs/pl/providers/openrouter.md create mode 100644 docs/pl/providers/perplexity-provider.md create mode 100644 docs/pl/providers/qianfan.md create mode 100644 docs/pl/providers/qwen.md create mode 100644 docs/pl/providers/qwen_modelstudio.md create mode 100644 docs/pl/providers/sglang.md create mode 100644 docs/pl/providers/stepfun.md create mode 100644 docs/pl/providers/synthetic.md create mode 100644 docs/pl/providers/together.md create mode 100644 docs/pl/providers/venice.md create mode 100644 docs/pl/providers/vercel-ai-gateway.md create mode 100644 docs/pl/providers/vllm.md create mode 100644 docs/pl/providers/volcengine.md create mode 100644 docs/pl/providers/xai.md create mode 100644 docs/pl/providers/xiaomi.md create mode 100644 docs/pl/providers/zai.md create mode 100644 docs/pl/reference/AGENTS.default.md create mode 100644 docs/pl/reference/RELEASING.md create mode 100644 docs/pl/reference/api-usage-costs.md create mode 100644 docs/pl/reference/credits.md create mode 100644 docs/pl/reference/device-models.md create mode 100644 docs/pl/reference/memory-config.md create mode 100644 docs/pl/reference/prompt-caching.md create mode 100644 docs/pl/reference/rpc.md create mode 100644 docs/pl/reference/secretref-credential-surface.md create mode 100644 docs/pl/reference/session-management-compaction.md create mode 100644 docs/pl/reference/templates/AGENTS.dev.md create mode 100644 docs/pl/reference/templates/AGENTS.md create mode 100644 docs/pl/reference/templates/BOOT.md create mode 100644 docs/pl/reference/templates/BOOTSTRAP.md create mode 100644 docs/pl/reference/templates/CLAUDE.md create mode 100644 docs/pl/reference/templates/HEARTBEAT.md create mode 100644 docs/pl/reference/templates/IDENTITY.dev.md create mode 100644 docs/pl/reference/templates/IDENTITY.md create mode 100644 docs/pl/reference/templates/SOUL.dev.md create mode 100644 docs/pl/reference/templates/SOUL.md create mode 100644 docs/pl/reference/templates/TOOLS.dev.md create mode 100644 docs/pl/reference/templates/TOOLS.md create mode 100644 docs/pl/reference/templates/USER.dev.md create mode 100644 docs/pl/reference/templates/USER.md create mode 100644 docs/pl/reference/test.md create mode 100644 docs/pl/reference/token-use.md create mode 100644 docs/pl/reference/transcript-hygiene.md create mode 100644 docs/pl/reference/wizard.md create mode 100644 docs/pl/security/CONTRIBUTING-THREAT-MODEL.md create mode 100644 docs/pl/security/THREAT-MODEL-ATLAS.md create mode 100644 docs/pl/security/formal-verification.md create mode 100644 docs/pl/start/bootstrapping.md create mode 100644 docs/pl/start/docs-directory.md create mode 100644 docs/pl/start/getting-started.md create mode 100644 docs/pl/start/hubs.md create mode 100644 docs/pl/start/lore.md create mode 100644 docs/pl/start/onboarding-overview.md create mode 100644 docs/pl/start/onboarding.md create mode 100644 docs/pl/start/openclaw.md create mode 100644 docs/pl/start/quickstart.md create mode 100644 docs/pl/start/setup.md create mode 100644 docs/pl/start/showcase.md create mode 100644 docs/pl/start/wizard-cli-automation.md create mode 100644 docs/pl/start/wizard-cli-reference.md create mode 100644 docs/pl/start/wizard.md create mode 100644 docs/pl/tools/acp-agents.md create mode 100644 docs/pl/tools/agent-send.md create mode 100644 docs/pl/tools/apply-patch.md create mode 100644 docs/pl/tools/brave-search.md create mode 100644 docs/pl/tools/browser-linux-troubleshooting.md create mode 100644 docs/pl/tools/browser-login.md create mode 100644 docs/pl/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md create mode 100644 docs/pl/tools/browser.md create mode 100644 docs/pl/tools/btw.md create mode 100644 docs/pl/tools/capability-cookbook.md create mode 100644 docs/pl/tools/clawhub.md create mode 100644 docs/pl/tools/code-execution.md create mode 100644 docs/pl/tools/creating-skills.md create mode 100644 docs/pl/tools/diffs.md create mode 100644 docs/pl/tools/duckduckgo-search.md create mode 100644 docs/pl/tools/elevated.md create mode 100644 docs/pl/tools/exa-search.md create mode 100644 docs/pl/tools/exec-approvals.md create mode 100644 docs/pl/tools/exec.md create mode 100644 docs/pl/tools/firecrawl.md create mode 100644 docs/pl/tools/gemini-search.md create mode 100644 docs/pl/tools/grok-search.md create mode 100644 docs/pl/tools/image-generation.md create mode 100644 docs/pl/tools/index.md create mode 100644 docs/pl/tools/kimi-search.md create mode 100644 docs/pl/tools/llm-task.md create mode 100644 docs/pl/tools/lobster.md create mode 100644 docs/pl/tools/loop-detection.md create mode 100644 docs/pl/tools/minimax-search.md create mode 100644 docs/pl/tools/multi-agent-sandbox-tools.md create mode 100644 docs/pl/tools/ollama-search.md create mode 100644 docs/pl/tools/pdf.md create mode 100644 docs/pl/tools/perplexity-search.md create mode 100644 docs/pl/tools/plugin.md create mode 100644 docs/pl/tools/reactions.md create mode 100644 docs/pl/tools/searxng-search.md create mode 100644 docs/pl/tools/skills-config.md create mode 100644 docs/pl/tools/skills.md create mode 100644 docs/pl/tools/slash-commands.md create mode 100644 docs/pl/tools/subagents.md create mode 100644 docs/pl/tools/tavily.md create mode 100644 docs/pl/tools/thinking.md create mode 100644 docs/pl/tools/tts.md create mode 100644 docs/pl/tools/web-fetch.md create mode 100644 docs/pl/tools/web.md create mode 100644 docs/pl/tts.md create mode 100644 docs/pl/vps.md create mode 100644 docs/pl/web/control-ui.md create mode 100644 docs/pl/web/dashboard.md create mode 100644 docs/pl/web/index.md create mode 100644 docs/pl/web/tui.md create mode 100644 docs/pl/web/webchat.md create mode 100644 docs/tr/.i18n/README.md create mode 100644 docs/tr/auth-credential-semantics.md create mode 100644 docs/tr/automation/auth-monitoring.md create mode 100644 docs/tr/automation/clawflow.md create mode 100644 docs/tr/automation/cron-jobs.md create mode 100644 docs/tr/automation/cron-vs-heartbeat.md create mode 100644 docs/tr/automation/gmail-pubsub.md create mode 100644 docs/tr/automation/hooks.md create mode 100644 docs/tr/automation/index.md create mode 100644 docs/tr/automation/poll.md create mode 100644 docs/tr/automation/standing-orders.md create mode 100644 docs/tr/automation/taskflow.md create mode 100644 docs/tr/automation/tasks.md create mode 100644 docs/tr/automation/troubleshooting.md create mode 100644 docs/tr/automation/webhook.md create mode 100644 docs/tr/brave-search.md create mode 100644 docs/tr/channels/bluebubbles.md create mode 100644 docs/tr/channels/broadcast-groups.md create mode 100644 docs/tr/channels/channel-routing.md create mode 100644 docs/tr/channels/discord.md create mode 100644 docs/tr/channels/feishu.md create mode 100644 docs/tr/channels/googlechat.md create mode 100644 docs/tr/channels/group-messages.md create mode 100644 docs/tr/channels/groups.md create mode 100644 docs/tr/channels/imessage.md create mode 100644 docs/tr/channels/index.md create mode 100644 docs/tr/channels/irc.md create mode 100644 docs/tr/channels/line.md create mode 100644 docs/tr/channels/location.md create mode 100644 docs/tr/channels/matrix.md create mode 100644 docs/tr/channels/mattermost.md create mode 100644 docs/tr/channels/msteams.md create mode 100644 docs/tr/channels/nextcloud-talk.md create mode 100644 docs/tr/channels/nostr.md create mode 100644 docs/tr/channels/pairing.md create mode 100644 docs/tr/channels/qqbot.md create mode 100644 docs/tr/channels/signal.md create mode 100644 docs/tr/channels/slack.md create mode 100644 docs/tr/channels/synology-chat.md create mode 100644 docs/tr/channels/telegram.md create mode 100644 docs/tr/channels/tlon.md create mode 100644 docs/tr/channels/troubleshooting.md create mode 100644 docs/tr/channels/twitch.md create mode 100644 docs/tr/channels/whatsapp.md create mode 100644 docs/tr/channels/zalo.md create mode 100644 docs/tr/channels/zalouser.md create mode 100644 docs/tr/ci.md create mode 100644 docs/tr/cli/acp.md create mode 100644 docs/tr/cli/agent.md create mode 100644 docs/tr/cli/agents.md create mode 100644 docs/tr/cli/approvals.md create mode 100644 docs/tr/cli/backup.md create mode 100644 docs/tr/cli/browser.md create mode 100644 docs/tr/cli/channels.md create mode 100644 docs/tr/cli/clawbot.md create mode 100644 docs/tr/cli/completion.md create mode 100644 docs/tr/cli/config.md create mode 100644 docs/tr/cli/configure.md create mode 100644 docs/tr/cli/cron.md create mode 100644 docs/tr/cli/daemon.md create mode 100644 docs/tr/cli/dashboard.md create mode 100644 docs/tr/cli/devices.md create mode 100644 docs/tr/cli/directory.md create mode 100644 docs/tr/cli/dns.md create mode 100644 docs/tr/cli/docs.md create mode 100644 docs/tr/cli/doctor.md create mode 100644 docs/tr/cli/flows.md create mode 100644 docs/tr/cli/gateway.md create mode 100644 docs/tr/cli/health.md create mode 100644 docs/tr/cli/hooks.md create mode 100644 docs/tr/cli/index.md create mode 100644 docs/tr/cli/logs.md create mode 100644 docs/tr/cli/mcp.md create mode 100644 docs/tr/cli/memory.md create mode 100644 docs/tr/cli/message.md create mode 100644 docs/tr/cli/models.md create mode 100644 docs/tr/cli/node.md create mode 100644 docs/tr/cli/nodes.md create mode 100644 docs/tr/cli/onboard.md create mode 100644 docs/tr/cli/pairing.md create mode 100644 docs/tr/cli/plugins.md create mode 100644 docs/tr/cli/qr.md create mode 100644 docs/tr/cli/reset.md create mode 100644 docs/tr/cli/sandbox.md create mode 100644 docs/tr/cli/secrets.md create mode 100644 docs/tr/cli/security.md create mode 100644 docs/tr/cli/sessions.md create mode 100644 docs/tr/cli/setup.md create mode 100644 docs/tr/cli/skills.md create mode 100644 docs/tr/cli/status.md create mode 100644 docs/tr/cli/system.md create mode 100644 docs/tr/cli/tui.md create mode 100644 docs/tr/cli/uninstall.md create mode 100644 docs/tr/cli/update.md create mode 100644 docs/tr/cli/voicecall.md create mode 100644 docs/tr/cli/webhooks.md create mode 100644 docs/tr/concepts/agent-loop.md create mode 100644 docs/tr/concepts/agent-workspace.md create mode 100644 docs/tr/concepts/agent.md create mode 100644 docs/tr/concepts/architecture.md create mode 100644 docs/tr/concepts/compaction.md create mode 100644 docs/tr/concepts/context-engine.md create mode 100644 docs/tr/concepts/context.md create mode 100644 docs/tr/concepts/delegate-architecture.md create mode 100644 docs/tr/concepts/features.md create mode 100644 docs/tr/concepts/markdown-formatting.md create mode 100644 docs/tr/concepts/memory-builtin.md create mode 100644 docs/tr/concepts/memory-dreaming.md create mode 100644 docs/tr/concepts/memory-honcho.md create mode 100644 docs/tr/concepts/memory-qmd.md create mode 100644 docs/tr/concepts/memory-search.md create mode 100644 docs/tr/concepts/memory.md create mode 100644 docs/tr/concepts/messages.md create mode 100644 docs/tr/concepts/model-failover.md create mode 100644 docs/tr/concepts/model-providers.md create mode 100644 docs/tr/concepts/models.md create mode 100644 docs/tr/concepts/multi-agent.md create mode 100644 docs/tr/concepts/oauth.md create mode 100644 docs/tr/concepts/presence.md create mode 100644 docs/tr/concepts/queue.md create mode 100644 docs/tr/concepts/retry.md create mode 100644 docs/tr/concepts/session-pruning.md create mode 100644 docs/tr/concepts/session-tool.md create mode 100644 docs/tr/concepts/session.md create mode 100644 docs/tr/concepts/soul.md create mode 100644 docs/tr/concepts/streaming.md create mode 100644 docs/tr/concepts/system-prompt.md create mode 100644 docs/tr/concepts/timezone.md create mode 100644 docs/tr/concepts/typebox.md create mode 100644 docs/tr/concepts/typing-indicators.md create mode 100644 docs/tr/concepts/usage-tracking.md create mode 100644 docs/tr/date-time.md create mode 100644 docs/tr/debug/node-issue.md create mode 100644 docs/tr/diagnostics/flags.md create mode 100644 docs/tr/gateway/authentication.md create mode 100644 docs/tr/gateway/background-process.md create mode 100644 docs/tr/gateway/bonjour.md create mode 100644 docs/tr/gateway/bridge-protocol.md create mode 100644 docs/tr/gateway/cli-backends.md create mode 100644 docs/tr/gateway/configuration-examples.md create mode 100644 docs/tr/gateway/configuration-reference.md create mode 100644 docs/tr/gateway/configuration.md create mode 100644 docs/tr/gateway/discovery.md create mode 100644 docs/tr/gateway/doctor.md create mode 100644 docs/tr/gateway/gateway-lock.md create mode 100644 docs/tr/gateway/health.md create mode 100644 docs/tr/gateway/heartbeat.md create mode 100644 docs/tr/gateway/index.md create mode 100644 docs/tr/gateway/local-models.md create mode 100644 docs/tr/gateway/logging.md create mode 100644 docs/tr/gateway/multiple-gateways.md create mode 100644 docs/tr/gateway/network-model.md create mode 100644 docs/tr/gateway/openai-http-api.md create mode 100644 docs/tr/gateway/openresponses-http-api.md create mode 100644 docs/tr/gateway/openshell.md create mode 100644 docs/tr/gateway/pairing.md create mode 100644 docs/tr/gateway/protocol.md create mode 100644 docs/tr/gateway/remote-gateway-readme.md create mode 100644 docs/tr/gateway/remote.md create mode 100644 docs/tr/gateway/sandbox-vs-tool-policy-vs-elevated.md create mode 100644 docs/tr/gateway/sandboxing.md create mode 100644 docs/tr/gateway/secrets-plan-contract.md create mode 100644 docs/tr/gateway/secrets.md create mode 100644 docs/tr/gateway/security/index.md create mode 100644 docs/tr/gateway/tailscale.md create mode 100644 docs/tr/gateway/tools-invoke-http-api.md create mode 100644 docs/tr/gateway/troubleshooting.md create mode 100644 docs/tr/gateway/trusted-proxy-auth.md create mode 100644 docs/tr/help/debugging.md create mode 100644 docs/tr/help/environment.md create mode 100644 docs/tr/help/faq.md create mode 100644 docs/tr/help/index.md create mode 100644 docs/tr/help/scripts.md create mode 100644 docs/tr/help/testing.md create mode 100644 docs/tr/help/troubleshooting.md create mode 100644 docs/tr/index.md create mode 100644 docs/tr/install/ansible.md create mode 100644 docs/tr/install/azure.md create mode 100644 docs/tr/install/bun.md create mode 100644 docs/tr/install/clawdock.md create mode 100644 docs/tr/install/development-channels.md create mode 100644 docs/tr/install/digitalocean.md create mode 100644 docs/tr/install/docker-vm-runtime.md create mode 100644 docs/tr/install/docker.md create mode 100644 docs/tr/install/exe-dev.md create mode 100644 docs/tr/install/fly.md create mode 100644 docs/tr/install/gcp.md create mode 100644 docs/tr/install/hetzner.md create mode 100644 docs/tr/install/index.md create mode 100644 docs/tr/install/installer.md create mode 100644 docs/tr/install/kubernetes.md create mode 100644 docs/tr/install/macos-vm.md create mode 100644 docs/tr/install/migrating-matrix.md create mode 100644 docs/tr/install/migrating.md create mode 100644 docs/tr/install/nix.md create mode 100644 docs/tr/install/node.md create mode 100644 docs/tr/install/northflank.mdx create mode 100644 docs/tr/install/oracle.md create mode 100644 docs/tr/install/podman.md create mode 100644 docs/tr/install/railway.mdx create mode 100644 docs/tr/install/raspberry-pi.md create mode 100644 docs/tr/install/render.mdx create mode 100644 docs/tr/install/uninstall.md create mode 100644 docs/tr/install/updating.md create mode 100644 docs/tr/logging.md create mode 100644 docs/tr/network.md create mode 100644 docs/tr/nodes/audio.md create mode 100644 docs/tr/nodes/camera.md create mode 100644 docs/tr/nodes/images.md create mode 100644 docs/tr/nodes/index.md create mode 100644 docs/tr/nodes/location-command.md create mode 100644 docs/tr/nodes/media-understanding.md create mode 100644 docs/tr/nodes/talk.md create mode 100644 docs/tr/nodes/troubleshooting.md create mode 100644 docs/tr/nodes/voicewake.md create mode 100644 docs/tr/perplexity.md create mode 100644 docs/tr/pi-dev.md create mode 100644 docs/tr/pi.md create mode 100644 docs/tr/platforms/android.md create mode 100644 docs/tr/platforms/digitalocean.md create mode 100644 docs/tr/platforms/index.md create mode 100644 docs/tr/platforms/ios.md create mode 100644 docs/tr/platforms/linux.md create mode 100644 docs/tr/platforms/mac/bundled-gateway.md create mode 100644 docs/tr/platforms/mac/canvas.md create mode 100644 docs/tr/platforms/mac/child-process.md create mode 100644 docs/tr/platforms/mac/dev-setup.md create mode 100644 docs/tr/platforms/mac/health.md create mode 100644 docs/tr/platforms/mac/icon.md create mode 100644 docs/tr/platforms/mac/logging.md create mode 100644 docs/tr/platforms/mac/menu-bar.md create mode 100644 docs/tr/platforms/mac/peekaboo.md create mode 100644 docs/tr/platforms/mac/permissions.md create mode 100644 docs/tr/platforms/mac/remote.md create mode 100644 docs/tr/platforms/mac/signing.md create mode 100644 docs/tr/platforms/mac/skills.md create mode 100644 docs/tr/platforms/mac/voice-overlay.md create mode 100644 docs/tr/platforms/mac/voicewake.md create mode 100644 docs/tr/platforms/mac/webchat.md create mode 100644 docs/tr/platforms/mac/xpc.md create mode 100644 docs/tr/platforms/macos.md create mode 100644 docs/tr/platforms/oracle.md create mode 100644 docs/tr/platforms/raspberry-pi.md create mode 100644 docs/tr/platforms/windows.md create mode 100644 docs/tr/plugins/agent-tools.md create mode 100644 docs/tr/plugins/architecture.md create mode 100644 docs/tr/plugins/building-extensions.md create mode 100644 docs/tr/plugins/building-plugins.md create mode 100644 docs/tr/plugins/bundles.md create mode 100644 docs/tr/plugins/community.md create mode 100644 docs/tr/plugins/manifest.md create mode 100644 docs/tr/plugins/sdk-channel-plugins.md create mode 100644 docs/tr/plugins/sdk-entrypoints.md create mode 100644 docs/tr/plugins/sdk-migration.md create mode 100644 docs/tr/plugins/sdk-overview.md create mode 100644 docs/tr/plugins/sdk-provider-plugins.md create mode 100644 docs/tr/plugins/sdk-runtime.md create mode 100644 docs/tr/plugins/sdk-setup.md create mode 100644 docs/tr/plugins/sdk-testing.md create mode 100644 docs/tr/plugins/voice-call.md create mode 100644 docs/tr/plugins/zalouser.md create mode 100644 docs/tr/prose.md create mode 100644 docs/tr/providers/anthropic.md create mode 100644 docs/tr/providers/bedrock-mantle.md create mode 100644 docs/tr/providers/bedrock.md create mode 100644 docs/tr/providers/chutes.md create mode 100644 docs/tr/providers/claude-max-api-proxy.md create mode 100644 docs/tr/providers/cloudflare-ai-gateway.md create mode 100644 docs/tr/providers/deepgram.md create mode 100644 docs/tr/providers/deepseek.md create mode 100644 docs/tr/providers/fireworks.md create mode 100644 docs/tr/providers/github-copilot.md create mode 100644 docs/tr/providers/glm.md create mode 100644 docs/tr/providers/google.md create mode 100644 docs/tr/providers/groq.md create mode 100644 docs/tr/providers/huggingface.md create mode 100644 docs/tr/providers/index.md create mode 100644 docs/tr/providers/kilocode.md create mode 100644 docs/tr/providers/litellm.md create mode 100644 docs/tr/providers/minimax.md create mode 100644 docs/tr/providers/mistral.md create mode 100644 docs/tr/providers/models.md create mode 100644 docs/tr/providers/moonshot.md create mode 100644 docs/tr/providers/nvidia.md create mode 100644 docs/tr/providers/ollama.md create mode 100644 docs/tr/providers/openai.md create mode 100644 docs/tr/providers/opencode-go.md create mode 100644 docs/tr/providers/opencode.md create mode 100644 docs/tr/providers/openrouter.md create mode 100644 docs/tr/providers/perplexity-provider.md create mode 100644 docs/tr/providers/qianfan.md create mode 100644 docs/tr/providers/qwen.md create mode 100644 docs/tr/providers/qwen_modelstudio.md create mode 100644 docs/tr/providers/sglang.md create mode 100644 docs/tr/providers/stepfun.md create mode 100644 docs/tr/providers/synthetic.md create mode 100644 docs/tr/providers/together.md create mode 100644 docs/tr/providers/venice.md create mode 100644 docs/tr/providers/vercel-ai-gateway.md create mode 100644 docs/tr/providers/vllm.md create mode 100644 docs/tr/providers/volcengine.md create mode 100644 docs/tr/providers/xai.md create mode 100644 docs/tr/providers/xiaomi.md create mode 100644 docs/tr/providers/zai.md create mode 100644 docs/tr/reference/AGENTS.default.md create mode 100644 docs/tr/reference/RELEASING.md create mode 100644 docs/tr/reference/api-usage-costs.md create mode 100644 docs/tr/reference/credits.md create mode 100644 docs/tr/reference/device-models.md create mode 100644 docs/tr/reference/memory-config.md create mode 100644 docs/tr/reference/prompt-caching.md create mode 100644 docs/tr/reference/rpc.md create mode 100644 docs/tr/reference/secretref-credential-surface.md create mode 100644 docs/tr/reference/session-management-compaction.md create mode 100644 docs/tr/reference/templates/AGENTS.dev.md create mode 100644 docs/tr/reference/templates/AGENTS.md create mode 100644 docs/tr/reference/templates/BOOT.md create mode 100644 docs/tr/reference/templates/BOOTSTRAP.md create mode 100644 docs/tr/reference/templates/CLAUDE.md create mode 100644 docs/tr/reference/templates/HEARTBEAT.md create mode 100644 docs/tr/reference/templates/IDENTITY.dev.md create mode 100644 docs/tr/reference/templates/IDENTITY.md create mode 100644 docs/tr/reference/templates/SOUL.dev.md create mode 100644 docs/tr/reference/templates/SOUL.md create mode 100644 docs/tr/reference/templates/TOOLS.dev.md create mode 100644 docs/tr/reference/templates/TOOLS.md create mode 100644 docs/tr/reference/templates/USER.dev.md create mode 100644 docs/tr/reference/templates/USER.md create mode 100644 docs/tr/reference/test.md create mode 100644 docs/tr/reference/token-use.md create mode 100644 docs/tr/reference/transcript-hygiene.md create mode 100644 docs/tr/reference/wizard.md create mode 100644 docs/tr/security/CONTRIBUTING-THREAT-MODEL.md create mode 100644 docs/tr/security/THREAT-MODEL-ATLAS.md create mode 100644 docs/tr/security/formal-verification.md create mode 100644 docs/tr/start/bootstrapping.md create mode 100644 docs/tr/start/docs-directory.md create mode 100644 docs/tr/start/getting-started.md create mode 100644 docs/tr/start/hubs.md create mode 100644 docs/tr/start/lore.md create mode 100644 docs/tr/start/onboarding-overview.md create mode 100644 docs/tr/start/onboarding.md create mode 100644 docs/tr/start/openclaw.md create mode 100644 docs/tr/start/quickstart.md create mode 100644 docs/tr/start/setup.md create mode 100644 docs/tr/start/showcase.md create mode 100644 docs/tr/start/wizard-cli-automation.md create mode 100644 docs/tr/start/wizard-cli-reference.md create mode 100644 docs/tr/start/wizard.md create mode 100644 docs/tr/tools/acp-agents.md create mode 100644 docs/tr/tools/agent-send.md create mode 100644 docs/tr/tools/apply-patch.md create mode 100644 docs/tr/tools/brave-search.md create mode 100644 docs/tr/tools/browser-linux-troubleshooting.md create mode 100644 docs/tr/tools/browser-login.md create mode 100644 docs/tr/tools/browser-wsl2-windows-remote-cdp-troubleshooting.md create mode 100644 docs/tr/tools/browser.md create mode 100644 docs/tr/tools/btw.md create mode 100644 docs/tr/tools/capability-cookbook.md create mode 100644 docs/tr/tools/clawhub.md create mode 100644 docs/tr/tools/code-execution.md create mode 100644 docs/tr/tools/creating-skills.md create mode 100644 docs/tr/tools/diffs.md create mode 100644 docs/tr/tools/duckduckgo-search.md create mode 100644 docs/tr/tools/elevated.md create mode 100644 docs/tr/tools/exa-search.md create mode 100644 docs/tr/tools/exec-approvals.md create mode 100644 docs/tr/tools/exec.md create mode 100644 docs/tr/tools/firecrawl.md create mode 100644 docs/tr/tools/gemini-search.md create mode 100644 docs/tr/tools/grok-search.md create mode 100644 docs/tr/tools/image-generation.md create mode 100644 docs/tr/tools/index.md create mode 100644 docs/tr/tools/kimi-search.md create mode 100644 docs/tr/tools/llm-task.md create mode 100644 docs/tr/tools/lobster.md create mode 100644 docs/tr/tools/loop-detection.md create mode 100644 docs/tr/tools/minimax-search.md create mode 100644 docs/tr/tools/multi-agent-sandbox-tools.md create mode 100644 docs/tr/tools/ollama-search.md create mode 100644 docs/tr/tools/pdf.md create mode 100644 docs/tr/tools/perplexity-search.md create mode 100644 docs/tr/tools/plugin.md create mode 100644 docs/tr/tools/reactions.md create mode 100644 docs/tr/tools/searxng-search.md create mode 100644 docs/tr/tools/skills-config.md create mode 100644 docs/tr/tools/skills.md create mode 100644 docs/tr/tools/slash-commands.md create mode 100644 docs/tr/tools/subagents.md create mode 100644 docs/tr/tools/tavily.md create mode 100644 docs/tr/tools/thinking.md create mode 100644 docs/tr/tools/tts.md create mode 100644 docs/tr/tools/web-fetch.md create mode 100644 docs/tr/tools/web.md create mode 100644 docs/tr/tts.md create mode 100644 docs/tr/vps.md create mode 100644 docs/tr/web/control-ui.md create mode 100644 docs/tr/web/dashboard.md create mode 100644 docs/tr/web/index.md create mode 100644 docs/tr/web/tui.md create mode 100644 docs/tr/web/webchat.md diff --git a/docs/.i18n/id.tm.jsonl b/docs/.i18n/id.tm.jsonl index 8b1378917..e69de29bb 100644 --- a/docs/.i18n/id.tm.jsonl +++ b/docs/.i18n/id.tm.jsonl @@ -1 +0,0 @@ - diff --git a/docs/.i18n/it.tm.jsonl b/docs/.i18n/it.tm.jsonl index 8b1378917..e69de29bb 100644 --- a/docs/.i18n/it.tm.jsonl +++ b/docs/.i18n/it.tm.jsonl @@ -1 +0,0 @@ - diff --git a/docs/.i18n/pl.tm.jsonl b/docs/.i18n/pl.tm.jsonl index 8b1378917..e69de29bb 100644 --- a/docs/.i18n/pl.tm.jsonl +++ b/docs/.i18n/pl.tm.jsonl @@ -1 +0,0 @@ - diff --git a/docs/.i18n/tr.tm.jsonl b/docs/.i18n/tr.tm.jsonl index 8b1378917..e69de29bb 100644 --- a/docs/.i18n/tr.tm.jsonl +++ b/docs/.i18n/tr.tm.jsonl @@ -1 +0,0 @@ - diff --git a/docs/id/.i18n/README.md b/docs/id/.i18n/README.md new file mode 100644 index 000000000..1acfddbab --- /dev/null +++ b/docs/id/.i18n/README.md @@ -0,0 +1,81 @@ +--- +x-i18n: + generated_at: "2026-04-05T13:42:11Z" + model: gpt-5.4 + provider: openai + source_hash: f07671afbba2efa77f5fb43ebed242d0fdca835f7810fdd60998e537b73d1efc + source_path: .i18n/README.md + workflow: 15 +--- + +# Aset i18n dokumen OpenClaw + +Folder ini menyimpan konfigurasi terjemahan untuk repo dokumen sumber. + +Pohon lokal yang dihasilkan dan memori terjemahan langsung kini berada di repo publikasi: + +- repo: `openclaw/docs` +- checkout lokal: `~/Projects/openclaw-docs` + +## Sumber kebenaran + +- Dokumen bahasa Inggris ditulis di `openclaw/openclaw`. +- Pohon dokumen sumber berada di bawah `docs/`. +- Repo sumber tidak lagi menyimpan pohon lokal yang dihasilkan dan dikomit seperti `docs/zh-CN/**`, `docs/ja-JP/**`, `docs/es/**`, `docs/pt-BR/**`, `docs/ko/**`, `docs/de/**`, `docs/fr/**`, `docs/ar/**`, `docs/it/**`, `docs/tr/**`, `docs/id/**`, atau `docs/pl/**`. + +## Alur end-to-end + +1. Edit dokumen bahasa Inggris di `openclaw/openclaw`. +2. Push ke `main`. +3. `openclaw/openclaw/.github/workflows/docs-sync-publish.yml` mencerminkan pohon dokumen ke `openclaw/docs`. +4. Skrip sinkronisasi menulis ulang `docs/docs.json` publikasi agar blok pemilih lokal yang dihasilkan ada di sana meskipun tidak lagi dikomit di repo sumber. +5. `openclaw/docs/.github/workflows/translate-zh-cn.yml` menyegarkan `docs/zh-CN/**` sekali sehari, sesuai permintaan, dan setelah dispatch rilis repo sumber. +6. `openclaw/docs/.github/workflows/translate-ja-jp.yml` melakukan hal yang sama untuk `docs/ja-JP/**`. +7. `openclaw/docs/.github/workflows/translate-es.yml`, `translate-pt-br.yml`, `translate-ko.yml`, `translate-de.yml`, `translate-fr.yml`, `translate-ar.yml`, `translate-it.yml`, `translate-tr.yml`, `translate-id.yml`, dan `translate-pl.yml` melakukan hal yang sama untuk `docs/es/**`, `docs/pt-BR/**`, `docs/ko/**`, `docs/de/**`, `docs/fr/**`, `docs/ar/**`, `docs/it/**`, `docs/tr/**`, `docs/id/**`, dan `docs/pl/**`. + +## Mengapa pemisahan ini ada + +- Menjaga output lokal yang dihasilkan tetap berada di luar repo produk utama. +- Menjaga Mintlify tetap pada satu pohon dokumen yang dipublikasikan. +- Mempertahankan pengalih bahasa bawaan dengan membiarkan repo publikasi memiliki pohon lokal yang dihasilkan. + +## File di folder ini + +- `glossary..json` — pemetaan istilah pilihan yang digunakan sebagai panduan prompt. +- `ar-navigation.json`, `de-navigation.json`, `es-navigation.json`, `fr-navigation.json`, `id-navigation.json`, `it-navigation.json`, `ja-navigation.json`, `ko-navigation.json`, `pl-navigation.json`, `pt-BR-navigation.json`, `tr-navigation.json`, `zh-Hans-navigation.json` — blok pemilih lokal Mintlify yang disisipkan kembali ke repo publikasi selama sinkronisasi. +- `.tm.jsonl` — memori terjemahan yang dikunci oleh workflow + model + hash teks. + +Di repo ini, file TM lokal yang dihasilkan seperti `docs/.i18n/zh-CN.tm.jsonl`, `docs/.i18n/ja-JP.tm.jsonl`, `docs/.i18n/es.tm.jsonl`, `docs/.i18n/pt-BR.tm.jsonl`, `docs/.i18n/ko.tm.jsonl`, `docs/.i18n/de.tm.jsonl`, `docs/.i18n/fr.tm.jsonl`, `docs/.i18n/ar.tm.jsonl`, `docs/.i18n/it.tm.jsonl`, `docs/.i18n/tr.tm.jsonl`, `docs/.i18n/id.tm.jsonl`, dan `docs/.i18n/pl.tm.jsonl` memang sengaja tidak lagi dikomit. + +## Format glosarium + +`glossary..json` adalah array entri: + +```json +{ + "source": "troubleshooting", + "target": "故障排除" +} +``` + +Kolom: + +- `source`: frasa bahasa Inggris (atau sumber) yang diprioritaskan. +- `target`: output terjemahan pilihan. + +## Mekanisme terjemahan + +- `scripts/docs-i18n` masih memiliki tanggung jawab atas pembuatan terjemahan. +- Mode dokumen menulis `x-i18n.source_hash` ke setiap halaman yang diterjemahkan. +- Setiap workflow publikasi menghitung lebih dulu daftar file tertunda dengan membandingkan hash sumber bahasa Inggris saat ini dengan `x-i18n.source_hash` lokal yang tersimpan. +- Jika jumlah tertunda adalah `0`, langkah terjemahan yang mahal dilewati sepenuhnya. +- Jika ada file tertunda, workflow hanya menerjemahkan file-file tersebut. +- Workflow publikasi mencoba ulang kegagalan format model yang bersifat sementara, tetapi file yang tidak berubah tetap dilewati karena pemeriksaan hash yang sama dijalankan pada setiap percobaan ulang. +- Repo sumber juga melakukan dispatch penyegaran zh-CN, ja-JP, es, pt-BR, ko, de, fr, ar, it, tr, id, dan pl setelah rilis GitHub dipublikasikan agar dokumen rilis dapat menyusul tanpa menunggu cron harian. + +## Catatan operasional + +- Metadata sinkronisasi ditulis ke `.openclaw-sync/source.json` di repo publikasi. +- Secret repo sumber: `OPENCLAW_DOCS_SYNC_TOKEN` +- Secret repo publikasi: `OPENCLAW_DOCS_I18N_OPENAI_API_KEY` +- Jika output lokal terlihat usang, periksa workflow `Translate ` yang sesuai di `openclaw/docs` terlebih dahulu. diff --git a/docs/id/auth-credential-semantics.md b/docs/id/auth-credential-semantics.md new file mode 100644 index 000000000..186e41ee6 --- /dev/null +++ b/docs/id/auth-credential-semantics.md @@ -0,0 +1,87 @@ +--- +read_when: + - Saat mengerjakan resolusi profil auth atau perutean kredensial + - Saat men-debug kegagalan auth model atau urutan profil +summary: Semantik kanonis kelayakan kredensial dan resolusi untuk profil auth +title: Semantik Kredensial Auth +x-i18n: + generated_at: "2026-04-05T13:42:07Z" + model: gpt-5.4 + provider: openai + source_hash: a4cd3e16cd25eb22c5e707311d06a19df1a59747ee3261c2d32c534a245fd7fb + source_path: auth-credential-semantics.md + workflow: 15 +--- + +# Semantik Kredensial Auth + +Dokumen ini mendefinisikan semantik kanonis kelayakan kredensial dan resolusi yang digunakan di seluruh: + +- `resolveAuthProfileOrder` +- `resolveApiKeyForProfile` +- `models status --probe` +- `doctor-auth` + +Tujuannya adalah menjaga perilaku saat pemilihan dan saat runtime tetap selaras. + +## Kode Alasan Probe yang Stabil + +- `ok` +- `excluded_by_auth_order` +- `missing_credential` +- `invalid_expires` +- `expired` +- `unresolved_ref` +- `no_model` + +## Kredensial Token + +Kredensial token (`type: "token"`) mendukung `token` inline dan/atau `tokenRef`. + +### Aturan kelayakan + +1. Profil token tidak memenuhi syarat ketika `token` dan `tokenRef` sama-sama tidak ada. +2. `expires` bersifat opsional. +3. Jika `expires` ada, nilainya harus berupa angka hingga yang lebih besar dari `0`. +4. Jika `expires` tidak valid (`NaN`, `0`, negatif, tidak hingga, atau tipe yang salah), profil tidak memenuhi syarat dengan `invalid_expires`. +5. Jika `expires` berada di masa lalu, profil tidak memenuhi syarat dengan `expired`. +6. `tokenRef` tidak melewati validasi `expires`. + +### Aturan resolusi + +1. Semantik resolver cocok dengan semantik kelayakan untuk `expires`. +2. Untuk profil yang memenuhi syarat, materi token dapat diresolusikan dari nilai inline atau `tokenRef`. +3. Ref yang tidak dapat diresolusikan menghasilkan `unresolved_ref` dalam output `models status --probe`. + +## Pemfilteran Urutan Auth Eksplisit + +- Ketika `auth.order.` atau override urutan auth-store ditetapkan untuk suatu + provider, `models status --probe` hanya mem-probe id profil yang tetap berada dalam + urutan auth yang telah diresolusikan untuk provider tersebut. +- Profil tersimpan untuk provider tersebut yang dihilangkan dari urutan eksplisit + tidak akan dicoba secara diam-diam nanti. Output probe melaporkannya dengan + `reasonCode: excluded_by_auth_order` dan detail + `Dikecualikan oleh auth.order untuk provider ini.` + +## Resolusi Target Probe + +- Target probe dapat berasal dari profil auth, kredensial environment, atau + `models.json`. +- Jika suatu provider memiliki kredensial tetapi OpenClaw tidak dapat meresolusikan kandidat + model yang dapat di-probe untuknya, `models status --probe` melaporkan `status: no_model` dengan + `reasonCode: no_model`. + +## Guard Kebijakan OAuth SecretRef + +- Input SecretRef hanya untuk kredensial statis. +- Jika kredensial profil adalah `type: "oauth"`, objek SecretRef tidak didukung untuk materi kredensial profil tersebut. +- Jika `auth.profiles..mode` adalah `"oauth"`, input `keyRef`/`tokenRef` berbasis SecretRef untuk profil tersebut ditolak. +- Pelanggaran merupakan kegagalan keras dalam jalur resolusi auth saat startup/reload. + +## Pesan yang Kompatibel dengan Versi Lama + +Untuk kompatibilitas skrip, error probe mempertahankan baris pertama ini tanpa perubahan: + +`Auth profile credentials are missing or expired.` + +Detail yang ramah bagi manusia dan kode alasan yang stabil dapat ditambahkan pada baris berikutnya. diff --git a/docs/id/automation/auth-monitoring.md b/docs/id/automation/auth-monitoring.md new file mode 100644 index 000000000..66e2dddf5 --- /dev/null +++ b/docs/id/automation/auth-monitoring.md @@ -0,0 +1,15 @@ +--- +summary: Alihkan ke /gateway/authentication +title: Pemantauan Auth +x-i18n: + generated_at: "2026-04-05T13:41:58Z" + model: gpt-5.4 + provider: openai + source_hash: 42aa1b4aa76201b20e07d8ad77231607855e7e7421fa032830055144ccd8819a + source_path: automation/auth-monitoring.md + workflow: 15 +--- + +# Pemantauan Auth + +Halaman ini dipindahkan ke [Authentication](/gateway/authentication). Lihat [Authentication](/gateway/authentication) untuk dokumentasi pemantauan auth. diff --git a/docs/id/automation/clawflow.md b/docs/id/automation/clawflow.md new file mode 100644 index 000000000..72f7afe21 --- /dev/null +++ b/docs/id/automation/clawflow.md @@ -0,0 +1,15 @@ +--- +summary: Alihkan ke Task Flow +title: ClawFlow +x-i18n: + generated_at: "2026-04-05T13:41:58Z" + model: gpt-5.4 + provider: openai + source_hash: e644237e0812f25b46a06ff125c8858dbc69a499aa43cfd73cf7cb37572e78e6 + source_path: automation/clawflow.md + workflow: 15 +--- + +# ClawFlow + +ClawFlow diubah namanya menjadi [Task Flow](/automation/taskflow). Lihat [Task Flow](/automation/taskflow) untuk dokumentasi terbaru. diff --git a/docs/id/automation/cron-jobs.md b/docs/id/automation/cron-jobs.md new file mode 100644 index 000000000..ab460972a --- /dev/null +++ b/docs/id/automation/cron-jobs.md @@ -0,0 +1,414 @@ +--- +read_when: + - Menjadwalkan pekerjaan latar belakang atau wakeup + - Menghubungkan pemicu eksternal (webhook, Gmail) ke OpenClaw + - Memutuskan antara heartbeat dan cron untuk tugas terjadwal +summary: Pekerjaan terjadwal, webhook, dan pemicu Gmail PubSub untuk scheduler Gateway +title: Tugas Terjadwal +x-i18n: + generated_at: "2026-04-05T13:42:42Z" + model: gpt-5.4 + provider: openai + source_hash: 43b906914461aba9af327e7e8c22aa856f65802ec2da37ed0c4f872d229cfde6 + source_path: automation/cron-jobs.md + workflow: 15 +--- + +# Tugas Terjadwal (Cron) + +Cron adalah scheduler bawaan Gateway. Ini menyimpan pekerjaan, membangunkan agen pada waktu yang tepat, dan dapat mengirimkan output kembali ke channel chat atau endpoint webhook. + +## Mulai cepat + +```bash +# Tambahkan pengingat sekali jalan +openclaw cron add \ + --name "Reminder" \ + --at "2026-02-01T16:00:00Z" \ + --session main \ + --system-event "Reminder: check the cron docs draft" \ + --wake now \ + --delete-after-run + +# Periksa pekerjaan Anda +openclaw cron list + +# Lihat riwayat eksekusi +openclaw cron runs --id +``` + +## Cara kerja cron + +- Cron berjalan **di dalam** proses Gateway (bukan di dalam model). +- Pekerjaan disimpan di `~/.openclaw/cron/jobs.json` sehingga restart tidak menghilangkan jadwal. +- Semua eksekusi cron membuat catatan [tugas latar belakang](/automation/tasks). +- Pekerjaan sekali jalan (`--at`) otomatis dihapus setelah berhasil secara default. +- Eksekusi cron terisolasi akan menutup tab/proses browser yang terlacak untuk sesi `cron:` mereka secara best-effort saat eksekusi selesai, sehingga otomasi browser yang terlepas tidak meninggalkan proses yatim. +- Eksekusi cron terisolasi juga melindungi dari balasan pengakuan yang kedaluwarsa. Jika + hasil pertama hanya berupa pembaruan status sementara (`on it`, `pulling everything +together`, dan petunjuk serupa) dan tidak ada eksekusi subagen turunan yang masih + bertanggung jawab atas jawaban akhir, OpenClaw akan meminta ulang sekali untuk hasil yang sebenarnya + sebelum pengiriman. + +Rekonsiliasi tugas untuk cron dimiliki oleh runtime: tugas cron aktif tetap hidup selama +runtime cron masih melacak pekerjaan tersebut sebagai sedang berjalan, meskipun baris sesi anak lama masih ada. +Setelah runtime berhenti memiliki pekerjaan itu dan jendela tenggang 5 menit berakhir, maintenance dapat +menandai tugas sebagai `lost`. + +## Jenis jadwal + +| Jenis | Flag CLI | Deskripsi | +| ------- | --------- | ------------------------------------------------------------- | +| `at` | `--at` | Stempel waktu sekali jalan (ISO 8601 atau relatif seperti `20m`) | +| `every` | `--every` | Interval tetap | +| `cron` | `--cron` | Ekspresi cron 5-field atau 6-field dengan `--tz` opsional | + +Stempel waktu tanpa zona waktu diperlakukan sebagai UTC. Tambahkan `--tz America/New_York` untuk penjadwalan waktu lokal. + +Ekspresi rekuren tepat di awal jam otomatis di-stagger hingga 5 menit untuk mengurangi lonjakan beban. Gunakan `--exact` untuk memaksa waktu yang presisi atau `--stagger 30s` untuk jendela eksplisit. + +## Gaya eksekusi + +| Gaya | Nilai `--session` | Berjalan di | Paling cocok untuk | +| --------------- | ------------------- | ------------------------- | --------------------------------- | +| Sesi utama | `main` | Giliran heartbeat berikutnya | Pengingat, peristiwa sistem | +| Terisolasi | `isolated` | `cron:` khusus | Laporan, pekerjaan latar belakang | +| Sesi saat ini | `current` | Terikat saat pembuatan | Pekerjaan rekuren yang sadar konteks | +| Sesi kustom | `session:custom-id` | Sesi bernama persisten | Workflow yang dibangun di atas riwayat | + +Pekerjaan **sesi utama** mengantrikan peristiwa sistem dan secara opsional membangunkan heartbeat (`--wake now` atau `--wake next-heartbeat`). Pekerjaan **terisolasi** menjalankan giliran agen khusus dengan sesi baru. **Sesi kustom** (`session:xxx`) mempertahankan konteks antar eksekusi, memungkinkan workflow seperti standup harian yang dibangun dari ringkasan sebelumnya. + +Untuk pekerjaan terisolasi, teardown runtime sekarang mencakup pembersihan browser secara best-effort untuk sesi cron tersebut. Kegagalan pembersihan diabaikan sehingga hasil cron yang sebenarnya tetap menjadi prioritas. + +Saat eksekusi cron terisolasi mengorkestrasi subagen, pengiriman juga lebih mengutamakan +output turunan akhir daripada teks sementara induk yang sudah kedaluwarsa. Jika turunan masih +berjalan, OpenClaw menekan pembaruan induk parsial tersebut alih-alih mengumumkannya. + +### Opsi payload untuk pekerjaan terisolasi + +- `--message`: teks prompt (wajib untuk terisolasi) +- `--model` / `--thinking`: override model dan tingkat pemikiran +- `--light-context`: lewati injeksi file bootstrap workspace +- `--tools exec,read`: batasi alat mana yang dapat digunakan pekerjaan + +`--model` menggunakan model yang dipilih dan diizinkan untuk pekerjaan tersebut. Jika model yang diminta +tidak diizinkan, cron mencatat peringatan dan kembali ke pemilihan model agen/default +untuk pekerjaan itu. Rantai fallback yang dikonfigurasi tetap berlaku, tetapi override model biasa +tanpa daftar fallback per pekerjaan yang eksplisit tidak lagi menambahkan model utama agen sebagai target retry tambahan yang tersembunyi. + +Urutan prioritas pemilihan model untuk pekerjaan terisolasi adalah: + +1. Override model hook Gmail (saat eksekusi berasal dari Gmail dan override itu diizinkan) +2. `model` payload per pekerjaan +3. Override model sesi cron yang tersimpan +4. Pemilihan model agen/default + +Mode cepat juga mengikuti pemilihan live yang telah diselesaikan. Jika konfigurasi model terpilih +memiliki `params.fastMode`, cron terisolasi akan menggunakannya secara default. Override `fastMode` +sesi yang tersimpan tetap lebih diutamakan daripada config dalam kedua arah. + +Jika eksekusi terisolasi mencapai handoff perpindahan model live, cron akan mencoba ulang dengan +penyedia/model yang telah dialihkan dan menyimpan pemilihan live tersebut sebelum mencoba ulang. Saat +perpindahan itu juga membawa profil auth baru, cron juga menyimpan override profil auth +tersebut. Retry dibatasi: setelah percobaan awal ditambah 2 retry perpindahan +, cron akan membatalkan alih-alih berulang tanpa akhir. + +## Pengiriman dan output + +| Mode | Yang terjadi | +| --------- | ---------------------------------------------------------- | +| `announce` | Kirim ringkasan ke channel target (default untuk terisolasi) | +| `webhook` | POST payload peristiwa selesai ke URL | +| `none` | Internal saja, tanpa pengiriman | + +Gunakan `--announce --channel telegram --to "-1001234567890"` untuk pengiriman ke channel. Untuk topik forum Telegram, gunakan `-1001234567890:topic:123`. Target Slack/Discord/Mattermost harus menggunakan prefiks eksplisit (`channel:`, `user:`). + +Untuk pekerjaan terisolasi yang dimiliki cron, runner memiliki jalur pengiriman akhir. Agen +diprompt untuk mengembalikan ringkasan teks biasa, lalu ringkasan itu dikirim +melalui `announce`, `webhook`, atau tetap internal untuk `none`. `--no-deliver` +tidak mengembalikan pengiriman ke agen; ini membuat eksekusi tetap internal. + +Jika tugas asli secara eksplisit mengatakan untuk mengirim pesan ke penerima eksternal tertentu, agen +harus mencatat kepada siapa/ke mana pesan itu harus dikirim dalam outputnya alih-alih +mencoba mengirimkannya langsung. + +Notifikasi kegagalan mengikuti jalur tujuan terpisah: + +- `cron.failureDestination` menetapkan default global untuk notifikasi kegagalan. +- `job.delivery.failureDestination` menimpa itu per pekerjaan. +- Jika keduanya tidak disetel dan pekerjaan sudah mengirim melalui `announce`, notifikasi kegagalan kini akan fallback ke target announce utama tersebut. +- `delivery.failureDestination` hanya didukung pada pekerjaan `sessionTarget="isolated"` kecuali mode pengiriman utama adalah `webhook`. + +## Contoh CLI + +Pengingat sekali jalan (sesi utama): + +```bash +openclaw cron add \ + --name "Calendar check" \ + --at "20m" \ + --session main \ + --system-event "Next heartbeat: check calendar." \ + --wake now +``` + +Pekerjaan terisolasi rekuren dengan pengiriman: + +```bash +openclaw cron add \ + --name "Morning brief" \ + --cron "0 7 * * *" \ + --tz "America/Los_Angeles" \ + --session isolated \ + --message "Summarize overnight updates." \ + --announce \ + --channel slack \ + --to "channel:C1234567890" +``` + +Pekerjaan terisolasi dengan override model dan thinking: + +```bash +openclaw cron add \ + --name "Deep analysis" \ + --cron "0 6 * * 1" \ + --tz "America/Los_Angeles" \ + --session isolated \ + --message "Weekly deep analysis of project progress." \ + --model "opus" \ + --thinking high \ + --announce +``` + +## Webhook + +Gateway dapat mengekspos endpoint webhook HTTP untuk pemicu eksternal. Aktifkan di config: + +```json5 +{ + hooks: { + enabled: true, + token: "shared-secret", + path: "/hooks", + }, +} +``` + +### Autentikasi + +Setiap permintaan harus menyertakan token hook melalui header: + +- `Authorization: Bearer ` (disarankan) +- `x-openclaw-token: ` + +Token query-string ditolak. + +### POST /hooks/wake + +Antrikan peristiwa sistem untuk sesi utama: + +```bash +curl -X POST http://127.0.0.1:18789/hooks/wake \ + -H 'Authorization: Bearer SECRET' \ + -H 'Content-Type: application/json' \ + -d '{"text":"New email received","mode":"now"}' +``` + +- `text` (wajib): deskripsi peristiwa +- `mode` (opsional): `now` (default) atau `next-heartbeat` + +### POST /hooks/agent + +Jalankan giliran agen terisolasi: + +```bash +curl -X POST http://127.0.0.1:18789/hooks/agent \ + -H 'Authorization: Bearer SECRET' \ + -H 'Content-Type: application/json' \ + -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}' +``` + +Field: `message` (wajib), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `thinking`, `timeoutSeconds`. + +### Hook yang dipetakan (POST /hooks/\) + +Nama hook kustom diselesaikan melalui `hooks.mappings` di config. Mapping dapat mentransformasi payload arbitrer menjadi aksi `wake` atau `agent` dengan template atau transformasi kode. + +### Keamanan + +- Simpan endpoint hook di balik loopback, tailnet, atau reverse proxy tepercaya. +- Gunakan token hook khusus; jangan gunakan ulang token auth gateway. +- Simpan `hooks.path` pada subpath khusus; `/` ditolak. +- Set `hooks.allowedAgentIds` untuk membatasi routing `agentId` eksplisit. +- Biarkan `hooks.allowRequestSessionKey=false` kecuali Anda memerlukan sesi yang dipilih pemanggil. +- Jika Anda mengaktifkan `hooks.allowRequestSessionKey`, set juga `hooks.allowedSessionKeyPrefixes` untuk membatasi bentuk session key yang diizinkan. +- Payload hook dibungkus dengan batas keamanan secara default. + +## Integrasi Gmail PubSub + +Hubungkan pemicu inbox Gmail ke OpenClaw melalui Google PubSub. + +**Prasyarat**: `gcloud` CLI, `gog` (gogcli), hook OpenClaw diaktifkan, Tailscale untuk endpoint HTTPS publik. + +### Setup wizard (disarankan) + +```bash +openclaw webhooks gmail setup --account openclaw@gmail.com +``` + +Ini menulis config `hooks.gmail`, mengaktifkan preset Gmail, dan menggunakan Tailscale Funnel untuk endpoint push. + +### Gateway auto-start + +Saat `hooks.enabled=true` dan `hooks.gmail.account` disetel, Gateway memulai `gog gmail watch serve` saat boot dan memperbarui watch secara otomatis. Set `OPENCLAW_SKIP_GMAIL_WATCHER=1` untuk menonaktifkannya. + +### Setup manual sekali saja + +1. Pilih project GCP yang memiliki klien OAuth yang digunakan oleh `gog`: + +```bash +gcloud auth login +gcloud config set project +gcloud services enable gmail.googleapis.com pubsub.googleapis.com +``` + +2. Buat topic dan berikan akses push Gmail: + +```bash +gcloud pubsub topics create gog-gmail-watch +gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \ + --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \ + --role=roles/pubsub.publisher +``` + +3. Mulai watch: + +```bash +gog gmail watch start \ + --account openclaw@gmail.com \ + --label INBOX \ + --topic projects//topics/gog-gmail-watch +``` + +### Override model Gmail + +```json5 +{ + hooks: { + gmail: { + model: "openrouter/meta-llama/llama-3.3-70b-instruct:free", + thinking: "off", + }, + }, +} +``` + +## Mengelola pekerjaan + +```bash +# Daftar semua pekerjaan +openclaw cron list + +# Edit pekerjaan +openclaw cron edit --message "Updated prompt" --model "opus" + +# Paksa jalankan pekerjaan sekarang +openclaw cron run + +# Jalankan hanya jika sudah jatuh tempo +openclaw cron run --due + +# Lihat riwayat eksekusi +openclaw cron runs --id --limit 50 + +# Hapus pekerjaan +openclaw cron remove + +# Pemilihan agen (setup multi-agen) +openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops +openclaw cron edit --clear-agent +``` + +Catatan override model: + +- `openclaw cron add|edit --model ...` mengubah model yang dipilih untuk pekerjaan. +- Jika model diizinkan, penyedia/model yang tepat itu akan mencapai eksekusi agen terisolasi. +- Jika tidak diizinkan, cron memberi peringatan dan kembali ke pemilihan model agen/default pekerjaan tersebut. +- Rantai fallback yang dikonfigurasi tetap berlaku, tetapi override `--model` biasa + tanpa daftar fallback per pekerjaan yang eksplisit tidak lagi diteruskan ke model utama agen + sebagai target retry tambahan diam-diam. + +## Konfigurasi + +```json5 +{ + cron: { + enabled: true, + store: "~/.openclaw/cron/jobs.json", + maxConcurrentRuns: 1, + retry: { + maxAttempts: 3, + backoffMs: [60000, 120000, 300000], + retryOn: ["rate_limit", "overloaded", "network", "server_error"], + }, + webhookToken: "replace-with-dedicated-webhook-token", + sessionRetention: "24h", + runLog: { maxBytes: "2mb", keepLines: 2000 }, + }, +} +``` + +Nonaktifkan cron: `cron.enabled: false` atau `OPENCLAW_SKIP_CRON=1`. + +**Retry sekali jalan**: error sementara (rate limit, overload, network, server error) akan dicoba ulang hingga 3 kali dengan exponential backoff. Error permanen langsung dinonaktifkan. + +**Retry rekuren**: exponential backoff (30 detik hingga 60 menit) di antara retry. Backoff direset setelah eksekusi berhasil berikutnya. + +**Maintenance**: `cron.sessionRetention` (default `24h`) memangkas entri sesi eksekusi terisolasi. `cron.runLog.maxBytes` / `cron.runLog.keepLines` memangkas file log eksekusi secara otomatis. + +## Pemecahan masalah + +### Urutan perintah + +```bash +openclaw status +openclaw gateway status +openclaw cron status +openclaw cron list +openclaw cron runs --id --limit 20 +openclaw system heartbeat last +openclaw logs --follow +openclaw doctor +``` + +### Cron tidak berjalan + +- Periksa `cron.enabled` dan variabel env `OPENCLAW_SKIP_CRON`. +- Pastikan Gateway berjalan terus-menerus. +- Untuk jadwal `cron`, verifikasi zona waktu (`--tz`) dibandingkan zona waktu host. +- `reason: not-due` di output eksekusi berarti eksekusi manual diperiksa dengan `openclaw cron run --due` dan pekerjaan belum jatuh tempo. + +### Cron berjalan tetapi tidak ada pengiriman + +- Mode pengiriman `none` berarti tidak ada pesan eksternal yang diharapkan. +- Target pengiriman hilang/tidak valid (`channel`/`to`) berarti pengiriman keluar dilewati. +- Error auth channel (`unauthorized`, `Forbidden`) berarti pengiriman diblokir oleh kredensial. +- Jika eksekusi terisolasi hanya mengembalikan token senyap (`NO_REPLY` / `no_reply`), + OpenClaw menekan pengiriman keluar langsung dan juga menekan jalur fallback + ringkasan antrean, sehingga tidak ada yang diposting kembali ke chat. +- Untuk pekerjaan terisolasi yang dimiliki cron, jangan mengharapkan agen menggunakan message tool + sebagai fallback. Runner memiliki pengiriman akhir; `--no-deliver` membuatnya + tetap internal alih-alih mengizinkan pengiriman langsung. + +### Jebakan zona waktu + +- Cron tanpa `--tz` menggunakan zona waktu host gateway. +- Jadwal `at` tanpa zona waktu diperlakukan sebagai UTC. +- `activeHours` heartbeat menggunakan resolusi zona waktu yang dikonfigurasi. + +## Terkait + +- [Otomasi & Tugas](/automation) — semua mekanisme otomasi secara ringkas +- [Tugas Latar Belakang](/automation/tasks) — ledger tugas untuk eksekusi cron +- [Heartbeat](/gateway/heartbeat) — giliran sesi utama periodik +- [Zona Waktu](/concepts/timezone) — konfigurasi zona waktu diff --git a/docs/id/automation/cron-vs-heartbeat.md b/docs/id/automation/cron-vs-heartbeat.md new file mode 100644 index 000000000..56e2fa745 --- /dev/null +++ b/docs/id/automation/cron-vs-heartbeat.md @@ -0,0 +1,15 @@ +--- +summary: Alihkan ke /automation +title: Cron vs Heartbeat +x-i18n: + generated_at: "2026-04-05T13:41:58Z" + model: gpt-5.4 + provider: openai + source_hash: 579c6618108ad7e2a71f53d5d6aa6550956fa0fdb2fe64ecdb7e8a0ce1366e33 + source_path: automation/cron-vs-heartbeat.md + workflow: 15 +--- + +# Cron vs Heartbeat + +Halaman ini telah dipindahkan ke [Automation & Tasks](/automation). Lihat [Automation & Tasks](/automation) untuk panduan keputusan yang membandingkan cron dan heartbeat. diff --git a/docs/id/automation/gmail-pubsub.md b/docs/id/automation/gmail-pubsub.md new file mode 100644 index 000000000..2f6e49274 --- /dev/null +++ b/docs/id/automation/gmail-pubsub.md @@ -0,0 +1,15 @@ +--- +summary: Alihkan ke /automation/cron-jobs +title: Gmail PubSub +x-i18n: + generated_at: "2026-04-05T13:41:58Z" + model: gpt-5.4 + provider: openai + source_hash: c2e17fdc8c09d52b6dc9fb6c44053446f07d02c65a0ab725d4ea038bd035d889 + source_path: automation/gmail-pubsub.md + workflow: 15 +--- + +# Gmail PubSub + +Halaman ini dipindahkan ke [Tugas Terjadwal](/automation/cron-jobs#gmail-pubsub-integration). Lihat [Tugas Terjadwal](/automation/cron-jobs#gmail-pubsub-integration) untuk dokumentasi Gmail PubSub. diff --git a/docs/id/automation/hooks.md b/docs/id/automation/hooks.md new file mode 100644 index 000000000..f457ec8e2 --- /dev/null +++ b/docs/id/automation/hooks.md @@ -0,0 +1,310 @@ +--- +read_when: + - Anda ingin otomatisasi berbasis peristiwa untuk /new, /reset, /stop, dan peristiwa siklus hidup agen + - Anda ingin membangun, menginstal, atau men-debug hook +summary: 'Hooks: otomatisasi berbasis peristiwa untuk perintah dan peristiwa siklus hidup' +title: Hooks +x-i18n: + generated_at: "2026-04-05T13:42:29Z" + model: gpt-5.4 + provider: openai + source_hash: 66eb75bb2b3b2ad229bf3da24fdb0fe021ed08f812fd1d13c69b3bd9df0218e5 + source_path: automation/hooks.md + workflow: 15 +--- + +# Hooks + +Hooks adalah skrip kecil yang berjalan saat sesuatu terjadi di dalam Gateway. Hooks ditemukan secara otomatis dari direktori dan dapat diperiksa dengan `openclaw hooks`. + +Ada dua jenis hook di OpenClaw: + +- **Hook internal** (halaman ini): berjalan di dalam Gateway saat peristiwa agen dipicu, seperti `/new`, `/reset`, `/stop`, atau peristiwa siklus hidup. +- **Webhook**: endpoint HTTP eksternal yang memungkinkan sistem lain memicu pekerjaan di OpenClaw. Lihat [Webhooks](/automation/cron-jobs#webhooks). + +Hooks juga dapat dibundel di dalam plugin. `openclaw hooks list` menampilkan hook mandiri dan hook yang dikelola plugin. + +## Mulai cepat + +```bash +# Daftar hook yang tersedia +openclaw hooks list + +# Aktifkan hook +openclaw hooks enable session-memory + +# Periksa status hook +openclaw hooks check + +# Dapatkan informasi terperinci +openclaw hooks info session-memory +``` + +## Jenis peristiwa + +| Peristiwa | Kapan dipicu | +| ----------------------- | ------------------------------------------------ | +| `command:new` | Perintah `/new` dijalankan | +| `command:reset` | Perintah `/reset` dijalankan | +| `command:stop` | Perintah `/stop` dijalankan | +| `command` | Peristiwa perintah apa pun (listener umum) | +| `session:compact:before`| Sebelum pemadatan merangkum riwayat | +| `session:compact:after` | Setelah pemadatan selesai | +| `session:patch` | Saat properti sesi diubah | +| `agent:bootstrap` | Sebelum file bootstrap workspace disisipkan | +| `gateway:startup` | Setelah channel dimulai dan hook dimuat | +| `message:received` | Pesan masuk dari channel mana pun | +| `message:transcribed` | Setelah transkripsi audio selesai | +| `message:preprocessed` | Setelah semua pemahaman media dan tautan selesai | +| `message:sent` | Pesan keluar terkirim | + +## Menulis hook + +### Struktur hook + +Setiap hook adalah direktori yang berisi dua file: + +``` +my-hook/ +├── HOOK.md # Metadata + dokumentasi +└── handler.ts # Implementasi handler +``` + +### Format HOOK.md + +```markdown +--- +name: my-hook +description: "Deskripsi singkat tentang apa yang dilakukan hook ini" +metadata: + { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } +--- + +# My Hook + +Dokumentasi terperinci ada di sini. +``` + +**Bidang metadata** (`metadata.openclaw`): + +| Bidang | Deskripsi | +| --------- | ---------------------------------------------------- | +| `emoji` | Emoji tampilan untuk CLI | +| `events` | Array peristiwa yang akan didengarkan | +| `export` | Named export yang akan digunakan (default `"default"`) | +| `os` | Platform yang diperlukan (misalnya `["darwin", "linux"]`) | +| `requires`| `bins`, `anyBins`, `env`, atau jalur `config` yang diperlukan | +| `always` | Lewati pemeriksaan kelayakan (boolean) | +| `install` | Metode instalasi | + +### Implementasi handler + +```typescript +const handler = async (event) => { + if (event.type !== "command" || event.action !== "new") { + return; + } + + console.log(`[my-hook] New command triggered`); + // Your logic here + + // Optionally send message to user + event.messages.push("Hook executed!"); +}; + +export default handler; +``` + +Setiap peristiwa mencakup: `type`, `action`, `sessionKey`, `timestamp`, `messages` (push untuk mengirim ke pengguna), dan `context` (data spesifik peristiwa). + +### Sorotan konteks peristiwa + +**Peristiwa perintah** (`command:new`, `command:reset`): `context.sessionEntry`, `context.previousSessionEntry`, `context.commandSource`, `context.workspaceDir`, `context.cfg`. + +**Peristiwa pesan** (`message:received`): `context.from`, `context.content`, `context.channelId`, `context.metadata` (data spesifik provider termasuk `senderId`, `senderName`, `guildId`). + +**Peristiwa pesan** (`message:sent`): `context.to`, `context.content`, `context.success`, `context.channelId`. + +**Peristiwa pesan** (`message:transcribed`): `context.transcript`, `context.from`, `context.channelId`, `context.mediaPath`. + +**Peristiwa pesan** (`message:preprocessed`): `context.bodyForAgent` (isi akhir yang telah diperkaya), `context.from`, `context.channelId`. + +**Peristiwa bootstrap** (`agent:bootstrap`): `context.bootstrapFiles` (array yang dapat diubah), `context.agentId`. + +**Peristiwa patch sesi** (`session:patch`): `context.sessionEntry`, `context.patch` (hanya bidang yang berubah), `context.cfg`. Hanya klien dengan hak istimewa yang dapat memicu peristiwa patch. + +**Peristiwa pemadatan**: `session:compact:before` mencakup `messageCount`, `tokenCount`. `session:compact:after` menambahkan `compactedCount`, `summaryLength`, `tokensBefore`, `tokensAfter`. + +## Penemuan hook + +Hooks ditemukan dari direktori berikut, dalam urutan prioritas override yang meningkat: + +1. **Hook bawaan**: dikirim bersama OpenClaw +2. **Hook plugin**: hook yang dibundel di dalam plugin yang terinstal +3. **Hook terkelola**: `~/.openclaw/hooks/` (diinstal pengguna, dibagikan di seluruh workspace). Direktori tambahan dari `hooks.internal.load.extraDirs` berbagi prioritas ini. +4. **Hook workspace**: `/hooks/` (per agen, dinonaktifkan secara default sampai diaktifkan secara eksplisit) + +Hook workspace dapat menambahkan nama hook baru tetapi tidak dapat mengganti hook bawaan, terkelola, atau yang disediakan plugin dengan nama yang sama. + +### Paket hook + +Paket hook adalah paket npm yang mengekspor hook melalui `openclaw.hooks` di `package.json`. Instal dengan: + +```bash +openclaw plugins install +``` + +Spesifikasi npm hanya untuk registry (nama paket + versi tepat opsional atau dist-tag). Spesifikasi Git/URL/file dan rentang semver ditolak. + +## Hook bawaan + +| Hook | Peristiwa | Fungsinya | +| --------------------- | ------------------------------ | ----------------------------------------------------- | +| session-memory | `command:new`, `command:reset` | Menyimpan konteks sesi ke `/memory/` | +| bootstrap-extra-files | `agent:bootstrap` | Menyisipkan file bootstrap tambahan dari pola glob | +| command-logger | `command` | Mencatat semua perintah ke `~/.openclaw/logs/commands.log` | +| boot-md | `gateway:startup` | Menjalankan `BOOT.md` saat gateway dimulai | + +Aktifkan hook bawaan apa pun: + +```bash +openclaw hooks enable +``` + +### Detail session-memory + +Mengekstrak 15 pesan pengguna/asisten terakhir, menghasilkan slug nama file deskriptif melalui LLM, dan menyimpannya ke `/memory/YYYY-MM-DD-slug.md`. Memerlukan `workspace.dir` dikonfigurasi. + +### Konfigurasi bootstrap-extra-files + +```json +{ + "hooks": { + "internal": { + "entries": { + "bootstrap-extra-files": { + "enabled": true, + "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"] + } + } + } + } +} +``` + +Path diselesaikan relatif terhadap workspace. Hanya basename bootstrap yang dikenali yang dimuat (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, `MEMORY.md`). + +## Hook plugin + +Plugin dapat mendaftarkan hook melalui Plugin SDK untuk integrasi yang lebih dalam: mencegat panggilan alat, memodifikasi prompt, mengontrol alur pesan, dan banyak lagi. Plugin SDK menyediakan 28 hook yang mencakup resolusi model, siklus hidup agen, alur pesan, eksekusi alat, koordinasi subagen, dan siklus hidup gateway. + +Untuk referensi hook plugin lengkap termasuk `before_tool_call`, `before_agent_reply`, `before_install`, dan semua hook plugin lainnya, lihat [Plugin Architecture](/plugins/architecture#provider-runtime-hooks). + +## Konfigurasi + +```json +{ + "hooks": { + "internal": { + "enabled": true, + "entries": { + "session-memory": { "enabled": true }, + "command-logger": { "enabled": false } + } + } + } +} +``` + +Variabel lingkungan per hook: + +```json +{ + "hooks": { + "internal": { + "entries": { + "my-hook": { + "enabled": true, + "env": { "MY_CUSTOM_VAR": "value" } + } + } + } + } +} +``` + +Direktori hook tambahan: + +```json +{ + "hooks": { + "internal": { + "load": { + "extraDirs": ["/path/to/more/hooks"] + } + } + } +} +``` + + +Format konfigurasi array legacy `hooks.internal.handlers` masih didukung untuk kompatibilitas mundur, tetapi hook baru sebaiknya menggunakan sistem berbasis penemuan. + + +## Referensi CLI + +```bash +# Daftar semua hook (tambahkan --eligible, --verbose, atau --json) +openclaw hooks list + +# Tampilkan info terperinci tentang sebuah hook +openclaw hooks info + +# Tampilkan ringkasan kelayakan +openclaw hooks check + +# Aktifkan/nonaktifkan +openclaw hooks enable +openclaw hooks disable +``` + +## Praktik terbaik + +- **Jaga handler tetap cepat.** Hooks berjalan selama pemrosesan perintah. Jalankan pekerjaan berat secara fire-and-forget dengan `void processInBackground(event)`. +- **Tangani error dengan baik.** Bungkus operasi berisiko dalam try/catch; jangan throw agar handler lain tetap dapat berjalan. +- **Filter peristiwa lebih awal.** Segera return jika tipe/aksi peristiwa tidak relevan. +- **Gunakan kunci peristiwa spesifik.** Pilih `"events": ["command:new"]` daripada `"events": ["command"]` untuk mengurangi overhead. + +## Pemecahan masalah + +### Hook tidak ditemukan + +```bash +# Verifikasi struktur direktori +ls -la ~/.openclaw/hooks/my-hook/ +# Seharusnya menampilkan: HOOK.md, handler.ts + +# Daftar semua hook yang ditemukan +openclaw hooks list +``` + +### Hook tidak memenuhi syarat + +```bash +openclaw hooks info my-hook +``` + +Periksa biner yang hilang (PATH), variabel lingkungan, nilai konfigurasi, atau kompatibilitas OS. + +### Hook tidak berjalan + +1. Verifikasi hook diaktifkan: `openclaw hooks list` +2. Mulai ulang proses gateway Anda agar hook dimuat ulang. +3. Periksa log gateway: `./scripts/clawlog.sh | grep hook` + +## Terkait + +- [Referensi CLI: hooks](/cli/hooks) +- [Webhooks](/automation/cron-jobs#webhooks) +- [Plugin Architecture](/plugins/architecture#provider-runtime-hooks) — referensi hook plugin lengkap +- [Configuration](/gateway/configuration-reference#hooks) diff --git a/docs/id/automation/index.md b/docs/id/automation/index.md new file mode 100644 index 000000000..f256504e4 --- /dev/null +++ b/docs/id/automation/index.md @@ -0,0 +1,122 @@ +--- +read_when: + - Menentukan cara mengotomatisasi pekerjaan dengan OpenClaw + - Memilih antara heartbeat, cron, hooks, dan standing orders + - Mencari titik masuk otomatisasi yang tepat +summary: 'Gambaran umum mekanisme otomatisasi: tugas, cron, hooks, standing orders, dan Task Flow' +title: Otomatisasi & Tugas +x-i18n: + generated_at: "2026-04-05T13:42:19Z" + model: gpt-5.4 + provider: openai + source_hash: 13cd05dcd2f38737f7bb19243ad1136978bfd727006fd65226daa3590f823afe + source_path: automation/index.md + workflow: 15 +--- + +# Otomatisasi & Tugas + +OpenClaw menjalankan pekerjaan di latar belakang melalui tugas, pekerjaan terjadwal, event hook, dan instruksi tetap. Halaman ini membantu Anda memilih mekanisme yang tepat dan memahami bagaimana semuanya saling terkait. + +## Panduan keputusan cepat + +```mermaid +flowchart TD + START([Apa yang Anda butuhkan?]) --> Q1{Menjadwalkan pekerjaan?} + START --> Q2{Melacak pekerjaan yang dilepas?} + START --> Q3{Mengorkestrasi alur multi-langkah?} + START --> Q4{Bereaksi terhadap peristiwa siklus hidup?} + START --> Q5{Memberi agen instruksi persisten?} + + Q1 -->|Ya| Q1a{Waktu tepat atau fleksibel?} + Q1a -->|Tepat| CRON["Tugas Terjadwal (Cron)"] + Q1a -->|Fleksibel| HEARTBEAT[Heartbeat] + + Q2 -->|Ya| TASKS[Tugas Latar Belakang] + Q3 -->|Ya| FLOW[Task Flow] + Q4 -->|Ya| HOOKS[Hooks] + Q5 -->|Ya| SO[Standing Orders] +``` + +| Kasus penggunaan | Rekomendasi | Alasan | +| --------------------------------------- | --------------------- | ----------------------------------------------- | +| Kirim laporan harian tepat pukul 9 pagi | Tugas Terjadwal (Cron) | Waktu tepat, eksekusi terisolasi | +| Ingatkan saya dalam 20 menit | Tugas Terjadwal (Cron) | Sekali jalan dengan waktu yang presisi (`--at`) | +| Jalankan analisis mendalam mingguan | Tugas Terjadwal (Cron) | Tugas mandiri, dapat menggunakan model berbeda | +| Periksa inbox setiap 30 menit | Heartbeat | Digabungkan dengan pemeriksaan lain, sadar konteks | +| Pantau kalender untuk acara mendatang | Heartbeat | Cocok secara alami untuk kesadaran berkala | +| Periksa status subagent atau eksekusi ACP | Tugas Latar Belakang | Buku besar tugas melacak semua pekerjaan yang dilepas | +| Audit apa yang dijalankan dan kapan | Tugas Latar Belakang | `openclaw tasks list` dan `openclaw tasks audit` | +| Riset multi-langkah lalu rangkum | Task Flow | Orkestrasi tahan lama dengan pelacakan revisi | +| Jalankan skrip saat reset sesi | Hooks | Berbasis peristiwa, dipicu pada peristiwa siklus hidup | +| Jalankan kode pada setiap pemanggilan tool | Hooks | Hooks dapat memfilter berdasarkan jenis peristiwa | +| Selalu periksa kepatuhan sebelum membalas | Standing Orders | Disuntikkan ke setiap sesi secara otomatis | + +### Tugas Terjadwal (Cron) vs Heartbeat + +| Dimensi | Tugas Terjadwal (Cron) | Heartbeat | +| --------------- | ----------------------------------- | ------------------------------------ | +| Waktu | Tepat (ekspresi cron, sekali jalan) | Perkiraan (default setiap 30 menit) | +| Konteks sesi | Baru (terisolasi) atau bersama | Konteks sesi utama penuh | +| Catatan tugas | Selalu dibuat | Tidak pernah dibuat | +| Penyampaian | Channel, webhook, atau senyap | Inline di sesi utama | +| Paling cocok untuk | Laporan, pengingat, pekerjaan latar belakang | Pemeriksaan inbox, kalender, notifikasi | + +Gunakan Tugas Terjadwal (Cron) saat Anda membutuhkan waktu yang presisi atau eksekusi terisolasi. Gunakan Heartbeat saat pekerjaan mendapat manfaat dari konteks sesi penuh dan waktu perkiraan sudah memadai. + +## Konsep inti + +### Tugas terjadwal (cron) + +Cron adalah penjadwal bawaan Gateway untuk waktu yang presisi. Cron menyimpan pekerjaan, membangunkan agen pada waktu yang tepat, dan dapat mengirimkan output ke channel obrolan atau endpoint webhook. Mendukung pengingat sekali jalan, ekspresi berulang, dan pemicu webhook masuk. + +Lihat [Tugas Terjadwal](/automation/cron-jobs). + +### Tugas + +Buku besar tugas latar belakang melacak semua pekerjaan yang dilepas: eksekusi ACP, spawn subagent, eksekusi cron terisolasi, dan operasi CLI. Tugas adalah catatan, bukan penjadwal. Gunakan `openclaw tasks list` dan `openclaw tasks audit` untuk memeriksanya. + +Lihat [Tugas Latar Belakang](/automation/tasks). + +### Task Flow + +Task Flow adalah substrat orkestrasi alur di atas tugas latar belakang. Task Flow mengelola alur multi-langkah yang tahan lama dengan mode sinkronisasi terkelola dan tercermin, pelacakan revisi, serta `openclaw tasks flow list|show|cancel` untuk inspeksi. + +Lihat [Task Flow](/automation/taskflow). + +### Standing orders + +Standing orders memberi agen wewenang operasional permanen untuk program yang ditentukan. Standing orders disimpan dalam file workspace (biasanya `AGENTS.md`) dan disuntikkan ke setiap sesi. Gabungkan dengan cron untuk penegakan berbasis waktu. + +Lihat [Standing Orders](/automation/standing-orders). + +### Hooks + +Hooks adalah skrip berbasis peristiwa yang dipicu oleh peristiwa siklus hidup agen (`/new`, `/reset`, `/stop`), pemadatan sesi, startup gateway, alur pesan, dan pemanggilan tool. Hooks ditemukan secara otomatis dari direktori dan dapat dikelola dengan `openclaw hooks`. + +Lihat [Hooks](/automation/hooks). + +### Heartbeat + +Heartbeat adalah giliran sesi utama berkala (default setiap 30 menit). Heartbeat menggabungkan beberapa pemeriksaan (inbox, kalender, notifikasi) dalam satu giliran agen dengan konteks sesi penuh. Giliran heartbeat tidak membuat catatan tugas. Gunakan `HEARTBEAT.md` untuk daftar periksa kecil, atau blok `tasks:` saat Anda menginginkan pemeriksaan berkala hanya-saat-jatuh-tempo di dalam heartbeat itu sendiri. File heartbeat kosong dilewati sebagai `empty-heartbeat-file`; mode tugas hanya-saat-jatuh-tempo dilewati sebagai `no-tasks-due`. + +Lihat [Heartbeat](/gateway/heartbeat). + +## Cara kerjanya bersama-sama + +- **Cron** menangani jadwal presisi (laporan harian, tinjauan mingguan) dan pengingat sekali jalan. Semua eksekusi cron membuat catatan tugas. +- **Heartbeat** menangani pemantauan rutin (inbox, kalender, notifikasi) dalam satu giliran gabungan setiap 30 menit. +- **Hooks** bereaksi terhadap peristiwa tertentu (pemanggilan tool, reset sesi, pemadatan) dengan skrip kustom. +- **Standing orders** memberi agen konteks persisten dan batas wewenang. +- **Task Flow** mengoordinasikan alur multi-langkah di atas tugas individual. +- **Tugas** secara otomatis melacak semua pekerjaan yang dilepas sehingga Anda dapat memeriksa dan mengauditnya. + +## Terkait + +- [Tugas Terjadwal](/automation/cron-jobs) — penjadwalan presisi dan pengingat sekali jalan +- [Tugas Latar Belakang](/automation/tasks) — buku besar tugas untuk semua pekerjaan yang dilepas +- [Task Flow](/automation/taskflow) — orkestrasi alur multi-langkah yang tahan lama +- [Hooks](/automation/hooks) — skrip siklus hidup berbasis peristiwa +- [Standing Orders](/automation/standing-orders) — instruksi agen persisten +- [Heartbeat](/gateway/heartbeat) — giliran sesi utama berkala +- [Referensi Konfigurasi](/gateway/configuration-reference) — semua kunci konfigurasi diff --git a/docs/id/automation/poll.md b/docs/id/automation/poll.md new file mode 100644 index 000000000..4a4d21491 --- /dev/null +++ b/docs/id/automation/poll.md @@ -0,0 +1,15 @@ +--- +summary: Alihkan ke /tools/message +title: Polling +x-i18n: + generated_at: "2026-04-05T13:42:01Z" + model: gpt-5.4 + provider: openai + source_hash: 8d69432ad8ba5fd80b59f8df779a1105ce0a2ff767d7dd5dc9d8e3ac1cb1ff1f + source_path: automation/poll.md + workflow: 15 +--- + +# Polling + +Halaman ini telah dipindahkan ke [alat Message](/cli/message). Lihat [alat Message](/cli/message) untuk dokumentasi polling. diff --git a/docs/id/automation/standing-orders.md b/docs/id/automation/standing-orders.md new file mode 100644 index 000000000..a7d48f71a --- /dev/null +++ b/docs/id/automation/standing-orders.md @@ -0,0 +1,261 @@ +--- +read_when: + - Menyiapkan alur kerja agen otonom yang berjalan tanpa prompt per tugas + - Menentukan apa yang dapat dilakukan agen secara mandiri vs. apa yang memerlukan persetujuan manusia + - Menyusun agen multi-program dengan batasan yang jelas dan aturan eskalasi +summary: Tentukan otoritas operasional permanen untuk program agen otonom +title: Standing Orders +x-i18n: + generated_at: "2026-04-05T13:42:29Z" + model: gpt-5.4 + provider: openai + source_hash: 81347d7a51a6ce20e6493277afee92073770f69a91a2e6b3bf87b99bb586d038 + source_path: automation/standing-orders.md + workflow: 15 +--- + +# Standing Orders + +Standing orders memberi agen Anda **otoritas operasional permanen** untuk program yang ditentukan. Alih-alih memberikan instruksi tugas satu per satu setiap kali, Anda menentukan program dengan cakupan, pemicu, dan aturan eskalasi yang jelas — lalu agen mengeksekusi secara otonom di dalam batasan tersebut. + +Inilah perbedaan antara memberi tahu asisten Anda "kirim laporan mingguan" setiap hari Jumat vs. memberikan otoritas tetap: "Anda bertanggung jawab atas laporan mingguan. Susun setiap hari Jumat, kirim, dan eskalasikan hanya jika ada sesuatu yang terlihat salah." + +## Mengapa Standing Orders? + +**Tanpa standing orders:** + +- Anda harus memicu agen untuk setiap tugas +- Agen diam tidak aktif di antara permintaan +- Pekerjaan rutin terlupakan atau tertunda +- Anda menjadi bottleneck + +**Dengan standing orders:** + +- Agen mengeksekusi secara otonom dalam batasan yang ditentukan +- Pekerjaan rutin berjalan sesuai jadwal tanpa prompt +- Anda hanya terlibat untuk pengecualian dan persetujuan +- Agen mengisi waktu senggang secara produktif + +## Cara Kerjanya + +Standing orders ditentukan dalam file [agent workspace](/concepts/agent-workspace) Anda. Pendekatan yang direkomendasikan adalah menyertakannya langsung di `AGENTS.md` (yang otomatis disuntikkan di setiap sesi) agar agen selalu memilikinya dalam konteks. Untuk konfigurasi yang lebih besar, Anda juga dapat menaruhnya di file khusus seperti `standing-orders.md` dan mereferensikannya dari `AGENTS.md`. + +Setiap program menentukan: + +1. **Cakupan** — apa yang berwenang dilakukan agen +2. **Pemicu** — kapan harus mengeksekusi (jadwal, peristiwa, atau kondisi) +3. **Gerbang persetujuan** — apa yang memerlukan persetujuan manusia sebelum bertindak +4. **Aturan eskalasi** — kapan harus berhenti dan meminta bantuan + +Agen memuat instruksi ini di setiap sesi melalui file bootstrap workspace (lihat [Agent Workspace](/concepts/agent-workspace) untuk daftar lengkap file yang disuntikkan otomatis) dan mengeksekusi berdasarkan instruksi tersebut, dikombinasikan dengan [cron jobs](/automation/cron-jobs) untuk penegakan berbasis waktu. + + +Letakkan standing orders di `AGENTS.md` untuk memastikan semuanya dimuat di setiap sesi. Bootstrap workspace otomatis menyuntikkan `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`, dan `MEMORY.md` — tetapi tidak file sembarang di subdirektori. + + +## Anatomi Standing Order + +```markdown +## Program: Weekly Status Report + +**Authority:** Compile data, generate report, deliver to stakeholders +**Trigger:** Every Friday at 4 PM (enforced via cron job) +**Approval gate:** None for standard reports. Flag anomalies for human review. +**Escalation:** If data source is unavailable or metrics look unusual (>2σ from norm) + +### Execution Steps + +1. Pull metrics from configured sources +2. Compare to prior week and targets +3. Generate report in Reports/weekly/YYYY-MM-DD.md +4. Deliver summary via configured channel +5. Log completion to Agent/Logs/ + +### What NOT to Do + +- Do not send reports to external parties +- Do not modify source data +- Do not skip delivery if metrics look bad — report accurately +``` + +## Standing Orders + Cron Jobs + +Standing orders menentukan **apa** yang berwenang dilakukan agen. [Cron jobs](/automation/cron-jobs) menentukan **kapan** hal itu terjadi. Keduanya bekerja bersama: + +``` +Standing Order: "Anda bertanggung jawab atas triase inbox harian" + ↓ +Cron Job (setiap hari pukul 8 pagi): "Jalankan triase inbox sesuai standing orders" + ↓ +Agen: Membaca standing orders → mengeksekusi langkah-langkah → melaporkan hasil +``` + +Prompt cron job seharusnya mereferensikan standing order, bukan menduplikasinya: + +```bash +openclaw cron add \ + --name daily-inbox-triage \ + --cron "0 8 * * 1-5" \ + --tz America/New_York \ + --timeout-seconds 300 \ + --announce \ + --channel bluebubbles \ + --to "+1XXXXXXXXXX" \ + --message "Execute daily inbox triage per standing orders. Check mail for new alerts. Parse, categorize, and persist each item. Report summary to owner. Escalate unknowns." +``` + +## Contoh + +### Contoh 1: Konten & Media Sosial (Siklus Mingguan) + +```markdown +## Program: Content & Social Media + +**Authority:** Draft content, schedule posts, compile engagement reports +**Approval gate:** All posts require owner review for first 30 days, then standing approval +**Trigger:** Weekly cycle (Monday review → mid-week drafts → Friday brief) + +### Weekly Cycle + +- **Monday:** Review platform metrics and audience engagement +- **Tuesday–Thursday:** Draft social posts, create blog content +- **Friday:** Compile weekly marketing brief → deliver to owner + +### Content Rules + +- Voice must match the brand (see SOUL.md or brand voice guide) +- Never identify as AI in public-facing content +- Include metrics when available +- Focus on value to audience, not self-promotion +``` + +### Contoh 2: Operasi Keuangan (Dipicu Peristiwa) + +```markdown +## Program: Financial Processing + +**Authority:** Process transaction data, generate reports, send summaries +**Approval gate:** None for analysis. Recommendations require owner approval. +**Trigger:** New data file detected OR scheduled monthly cycle + +### When New Data Arrives + +1. Detect new file in designated input directory +2. Parse and categorize all transactions +3. Compare against budget targets +4. Flag: unusual items, threshold breaches, new recurring charges +5. Generate report in designated output directory +6. Deliver summary to owner via configured channel + +### Escalation Rules + +- Single item > $500: immediate alert +- Category > budget by 20%: flag in report +- Unrecognizable transaction: ask owner for categorization +- Failed processing after 2 retries: report failure, do not guess +``` + +### Contoh 3: Pemantauan & Peringatan (Berkelanjutan) + +```markdown +## Program: System Monitoring + +**Authority:** Check system health, restart services, send alerts +**Approval gate:** Restart services automatically. Escalate if restart fails twice. +**Trigger:** Every heartbeat cycle + +### Checks + +- Service health endpoints responding +- Disk space above threshold +- Pending tasks not stale (>24 hours) +- Delivery channels operational + +### Response Matrix + +| Condition | Action | Escalate? | +| ---------------- | ------------------------ | ------------------------ | +| Service down | Restart automatically | Only if restart fails 2x | +| Disk space < 10% | Alert owner | Yes | +| Stale task > 24h | Remind owner | No | +| Channel offline | Log and retry next cycle | If offline > 2 hours | +``` + +## Pola Execute-Verify-Report + +Standing orders bekerja paling baik jika digabungkan dengan disiplin eksekusi yang ketat. Setiap tugas dalam standing order harus mengikuti loop ini: + +1. **Execute** — Lakukan pekerjaan yang sebenarnya (jangan hanya mengakui instruksinya) +2. **Verify** — Konfirmasi bahwa hasilnya benar (file ada, pesan terkirim, data berhasil diparse) +3. **Report** — Beri tahu pemilik apa yang telah dilakukan dan apa yang telah diverifikasi + +```markdown +### Execution Rules + +- Every task follows Execute-Verify-Report. No exceptions. +- "I'll do that" is not execution. Do it, then report. +- "Done" without verification is not acceptable. Prove it. +- If execution fails: retry once with adjusted approach. +- If still fails: report failure with diagnosis. Never silently fail. +- Never retry indefinitely — 3 attempts max, then escalate. +``` + +Pola ini mencegah mode kegagalan agen yang paling umum: mengakui sebuah tugas tanpa menyelesaikannya. + +## Arsitektur Multi-Program + +Untuk agen yang mengelola banyak area, susun standing orders sebagai program terpisah dengan batasan yang jelas: + +```markdown +# Standing Orders + +## Program 1: [Domain A] (Weekly) + +... + +## Program 2: [Domain B] (Monthly + On-Demand) + +... + +## Program 3: [Domain C] (As-Needed) + +... + +## Escalation Rules (All Programs) + +- [Common escalation criteria] +- [Approval gates that apply across programs] +``` + +Setiap program seharusnya memiliki: + +- **Kadensi pemicu** sendiri (mingguan, bulanan, berbasis peristiwa, berkelanjutan) +- **Gerbang persetujuan** sendiri (beberapa program memerlukan pengawasan lebih banyak daripada yang lain) +- **Batasan** yang jelas (agen harus mengetahui di mana satu program berakhir dan program lain dimulai) + +## Praktik Terbaik + +### Lakukan + +- Mulailah dengan otoritas yang sempit dan perluas seiring tumbuhnya kepercayaan +- Tentukan gerbang persetujuan yang eksplisit untuk tindakan berisiko tinggi +- Sertakan bagian "Apa yang TIDAK boleh dilakukan" — batasan sama pentingnya dengan izin +- Gabungkan dengan cron jobs untuk eksekusi berbasis waktu yang andal +- Tinjau log agen setiap minggu untuk memverifikasi bahwa standing orders diikuti +- Perbarui standing orders seiring kebutuhan Anda berkembang — ini adalah dokumen hidup + +### Hindari + +- Memberikan otoritas yang luas sejak hari pertama ("lakukan apa pun yang menurut Anda terbaik") +- Melewatkan aturan eskalasi — setiap program membutuhkan klausul "kapan harus berhenti dan bertanya" +- Menganggap agen akan mengingat instruksi lisan — tuliskan semuanya di file +- Mencampur banyak area dalam satu program — program terpisah untuk domain yang terpisah +- Lupa menegakkan dengan cron jobs — standing orders tanpa pemicu akan menjadi saran saja + +## Terkait + +- [Automation & Tasks](/automation) — semua mekanisme otomasi secara ringkas +- [Cron Jobs](/automation/cron-jobs) — penegakan jadwal untuk standing orders +- [Hooks](/automation/hooks) — skrip berbasis peristiwa untuk peristiwa siklus hidup agen +- [Webhooks](/automation/cron-jobs#webhooks) — pemicu peristiwa HTTP masuk +- [Agent Workspace](/concepts/agent-workspace) — tempat standing orders berada, termasuk daftar lengkap file bootstrap yang disuntikkan otomatis (AGENTS.md, SOUL.md, dll.) diff --git a/docs/id/automation/taskflow.md b/docs/id/automation/taskflow.md new file mode 100644 index 000000000..ff017c920 --- /dev/null +++ b/docs/id/automation/taskflow.md @@ -0,0 +1,89 @@ +--- +read_when: + - Anda ingin memahami bagaimana Task Flow berhubungan dengan background tasks + - Anda menemukan Task Flow atau openclaw tasks flow di catatan rilis atau dokumentasi + - Anda ingin memeriksa atau mengelola status flow yang tahan lama +summary: Lapisan orkestrasi flow Task Flow di atas background tasks +title: Task Flow +x-i18n: + generated_at: "2026-04-05T13:42:14Z" + model: gpt-5.4 + provider: openai + source_hash: 172871206b839845db807d9c627015890f7733b862e276853d5dbfbe29e03883 + source_path: automation/taskflow.md + workflow: 15 +--- + +# Task Flow + +Task Flow adalah substrat orkestrasi flow yang berada di atas [background tasks](/automation/tasks). Fitur ini mengelola flow multi-langkah yang tahan lama dengan status, pelacakan revisi, dan semantik sinkronisasinya sendiri, sementara task individual tetap menjadi unit kerja terlepas. + +## Kapan menggunakan Task Flow + +Gunakan Task Flow saat pekerjaan mencakup beberapa langkah berurutan atau bercabang dan Anda memerlukan pelacakan progres yang tahan lama di seluruh restart gateway. Untuk operasi latar belakang tunggal, [task](/automation/tasks) biasa sudah memadai. + +| Skenario | Penggunaan | +| ------------------------------------ | --------------------- | +| Job latar belakang tunggal | Task biasa | +| Pipeline multi-langkah (A lalu B lalu C) | Task Flow (dikelola) | +| Mengamati task yang dibuat secara eksternal | Task Flow (dicerminkan) | +| Pengingat sekali jalan | Cron job | + +## Mode sinkronisasi + +### Mode dikelola + +Task Flow memiliki siklus hidup end-to-end. Fitur ini membuat task sebagai langkah flow, menjalankannya hingga selesai, dan memajukan status flow secara otomatis. + +Contoh: flow laporan mingguan yang (1) mengumpulkan data, (2) membuat laporan, dan (3) mengirimkannya. Task Flow membuat setiap langkah sebagai background task, menunggu hingga selesai, lalu berpindah ke langkah berikutnya. + +``` +Flow: weekly-report + Step 1: gather-data → task created → succeeded + Step 2: generate-report → task created → succeeded + Step 3: deliver → task created → running +``` + +### Mode dicerminkan + +Task Flow mengamati task yang dibuat secara eksternal dan menjaga agar status flow tetap sinkron tanpa mengambil alih kepemilikan pembuatan task. Ini berguna ketika task berasal dari cron job, perintah CLI, atau sumber lain dan Anda menginginkan tampilan progresnya yang terpadu sebagai sebuah flow. + +Contoh: tiga cron job independen yang bersama-sama membentuk rutinitas "operasi pagi". Flow yang dicerminkan melacak progres kolektifnya tanpa mengendalikan kapan atau bagaimana pekerjaan tersebut berjalan. + +## Status tahan lama dan pelacakan revisi + +Setiap flow menyimpan statusnya sendiri dan melacak revisi sehingga progres tetap bertahan setelah gateway direstart. Pelacakan revisi memungkinkan deteksi konflik saat beberapa sumber mencoba memajukan flow yang sama secara bersamaan. + +## Perilaku pembatalan + +`openclaw tasks flow cancel` menetapkan intent pembatalan lekat pada flow. Task aktif di dalam flow dibatalkan, dan tidak ada langkah baru yang dimulai. Intent pembatalan tetap bertahan setelah restart, sehingga flow yang dibatalkan tetap dibatalkan meskipun gateway direstart sebelum semua task turunan dihentikan. + +## Perintah CLI + +```bash +# List active and recent flows +openclaw tasks flow list + +# Show details for a specific flow +openclaw tasks flow show + +# Cancel a running flow and its active tasks +openclaw tasks flow cancel +``` + +| Perintah | Deskripsi | +| -------------------------------- | ------------------------------------------------- | +| `openclaw tasks flow list` | Menampilkan flow yang dilacak beserta status dan mode sinkronisasi | +| `openclaw tasks flow show ` | Periksa satu flow berdasarkan id flow atau kunci lookup | +| `openclaw tasks flow cancel ` | Batalkan flow yang sedang berjalan dan task aktifnya | + +## Bagaimana flow berhubungan dengan task + +Flow mengoordinasikan task, bukan menggantikannya. Satu flow dapat menjalankan beberapa background task selama masa berlakunya. Gunakan `openclaw tasks` untuk memeriksa catatan task individual dan `openclaw tasks flow` untuk memeriksa flow yang mengatur orkestrasi. + +## Terkait + +- [Background Tasks](/automation/tasks) — ledger pekerjaan terlepas yang dikoordinasikan oleh flow +- [CLI: tasks](/cli/index#tasks) — referensi perintah CLI untuk `openclaw tasks flow` +- [Ikhtisar Otomasi](/automation) — semua mekanisme otomasi secara sekilas +- [Cron Jobs](/automation/cron-jobs) — job terjadwal yang dapat menjadi masukan ke flow diff --git a/docs/id/automation/tasks.md b/docs/id/automation/tasks.md new file mode 100644 index 000000000..207769ff4 --- /dev/null +++ b/docs/id/automation/tasks.md @@ -0,0 +1,317 @@ +--- +read_when: + - Memeriksa pekerjaan latar belakang yang sedang berlangsung atau baru saja selesai + - Men-debug kegagalan pengiriman untuk proses agen terlepas + - Memahami bagaimana proses latar belakang berkaitan dengan sesi, cron, dan heartbeat +summary: Pelacakan tugas latar belakang untuk proses ACP, subagen, job cron terisolasi, dan operasi CLI +title: Tugas Latar Belakang +x-i18n: + generated_at: "2026-04-05T13:42:46Z" + model: gpt-5.4 + provider: openai + source_hash: 6c95ccf4388d07e60a7bb68746b161793f4bb5ff2ba3d5ce9e51f2225dab2c4d + source_path: automation/tasks.md + workflow: 15 +--- + +# Tugas Latar Belakang + +> **Mencari penjadwalan?** Lihat [Otomasi & Tugas](/automation) untuk memilih mekanisme yang tepat. Halaman ini membahas **pelacakan** pekerjaan latar belakang, bukan penjadwalannya. + +Tugas latar belakang melacak pekerjaan yang berjalan **di luar sesi percakapan utama Anda**: +proses ACP, pemunculan subagen, eksekusi job cron terisolasi, dan operasi yang dimulai dari CLI. + +Tugas **tidak** menggantikan sesi, job cron, atau heartbeat — tugas adalah **buku besar aktivitas** yang mencatat pekerjaan terlepas apa yang terjadi, kapan terjadi, dan apakah berhasil. + + +Tidak setiap proses agen membuat tugas. Giliran heartbeat dan chat interaktif normal tidak membuat tugas. Semua eksekusi cron, pemunculan ACP, pemunculan subagen, dan perintah agen CLI membuat tugas. + + +## Ringkasan + +- Tugas adalah **catatan**, bukan penjadwal — cron dan heartbeat menentukan _kapan_ pekerjaan berjalan, tugas melacak _apa yang terjadi_. +- ACP, subagen, semua job cron, dan operasi CLI membuat tugas. Giliran heartbeat tidak membuat tugas. +- Setiap tugas berpindah melalui `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled`, atau `lost`). +- Tugas cron tetap aktif selama runtime cron masih memiliki job tersebut; tugas CLI berbasis chat tetap aktif hanya selama konteks proses pemiliknya masih aktif. +- Penyelesaian didorong oleh push: pekerjaan terlepas dapat memberi tahu secara langsung atau membangunkan sesi/heartbeat peminta saat selesai, jadi loop polling status biasanya bukan pola yang tepat. +- Proses cron terisolasi dan penyelesaian subagen sebisa mungkin membersihkan tab/proses browser yang dilacak untuk sesi anaknya sebelum pembukuan pembersihan akhir. +- Pengiriman cron terisolasi menekan balasan perantara induk yang sudah usang saat pekerjaan subagen turunan masih dikuras, dan memprioritaskan output akhir turunan jika output itu tiba sebelum pengiriman. +- Notifikasi penyelesaian dikirim langsung ke channel atau diantrikan untuk heartbeat berikutnya. +- `openclaw tasks list` menampilkan semua tugas; `openclaw tasks audit` menampilkan masalah. +- Rekaman terminal disimpan selama 7 hari, lalu dipangkas secara otomatis. + +## Mulai cepat + +```bash +# Daftar semua tugas (terbaru terlebih dahulu) +openclaw tasks list + +# Filter berdasarkan runtime atau status +openclaw tasks list --runtime acp +openclaw tasks list --status running + +# Tampilkan detail untuk tugas tertentu (berdasarkan ID, ID proses, atau kunci sesi) +openclaw tasks show + +# Batalkan tugas yang sedang berjalan (menghentikan sesi anak) +openclaw tasks cancel + +# Ubah kebijakan notifikasi untuk suatu tugas +openclaw tasks notify state_changes + +# Jalankan audit kesehatan +openclaw tasks audit + +# Pratinjau atau terapkan pemeliharaan +openclaw tasks maintenance +openclaw tasks maintenance --apply + +# Periksa status Task Flow +openclaw tasks flow list +openclaw tasks flow show +openclaw tasks flow cancel +``` + +## Apa yang membuat tugas + +| Sumber | Jenis runtime | Kapan rekaman tugas dibuat | Kebijakan notifikasi default | +| ---------------------- | ------------- | ---------------------------------------------------- | ---------------------------- | +| Proses latar belakang ACP | `acp` | Memunculkan sesi anak ACP | `done_only` | +| Orkestrasi subagen | `subagent` | Memunculkan subagen melalui `sessions_spawn` | `done_only` | +| Job cron (semua jenis) | `cron` | Setiap eksekusi cron (sesi utama dan terisolasi) | `silent` | +| Operasi CLI | `cli` | Perintah `openclaw agent` yang berjalan melalui gateway | `silent` | + +Tugas cron sesi utama menggunakan kebijakan notifikasi `silent` secara default — tugas ini membuat rekaman untuk pelacakan tetapi tidak menghasilkan notifikasi. Tugas cron terisolasi juga default ke `silent` tetapi lebih terlihat karena berjalan dalam sesinya sendiri. + +**Yang tidak membuat tugas:** + +- Giliran heartbeat — sesi utama; lihat [Heartbeat](/gateway/heartbeat) +- Giliran chat interaktif normal +- Respons `/command` langsung + +## Siklus hidup tugas + +```mermaid +stateDiagram-v2 + [*] --> queued + queued --> running : agent starts + running --> succeeded : completes ok + running --> failed : error + running --> timed_out : timeout exceeded + running --> cancelled : operator cancels + queued --> lost : session gone > 5 min + running --> lost : session gone > 5 min +``` + +| Status | Artinya | +| ----------- | ---------------------------------------------------------------------------- | +| `queued` | Dibuat, menunggu agen memulai | +| `running` | Giliran agen sedang dieksekusi secara aktif | +| `succeeded` | Selesai dengan sukses | +| `failed` | Selesai dengan error | +| `timed_out` | Melebihi batas waktu yang dikonfigurasi | +| `cancelled` | Dihentikan oleh operator melalui `openclaw tasks cancel` | +| `lost` | Runtime kehilangan status dukungan yang otoritatif setelah masa tenggang 5 menit | + +Transisi terjadi secara otomatis — saat proses agen terkait berakhir, status tugas diperbarui agar sesuai. + +`lost` bergantung pada runtime: + +- Tugas ACP: metadata sesi anak ACP pendukung menghilang. +- Tugas subagen: sesi anak pendukung menghilang dari penyimpanan agen target. +- Tugas cron: runtime cron tidak lagi melacak job tersebut sebagai aktif. +- Tugas CLI: tugas sesi anak terisolasi menggunakan sesi anak; tugas CLI berbasis chat menggunakan konteks proses langsung, sehingga baris sesi channel/grup/langsung yang tersisa tidak membuatnya tetap aktif. + +## Pengiriman dan notifikasi + +Saat sebuah tugas mencapai status terminal, OpenClaw memberi tahu Anda. Ada dua jalur pengiriman: + +**Pengiriman langsung** — jika tugas memiliki target channel (`requesterOrigin`), pesan penyelesaian langsung dikirim ke channel tersebut (Telegram, Discord, Slack, dll.). Untuk penyelesaian subagen, OpenClaw juga mempertahankan perutean thread/topik yang terikat saat tersedia dan dapat mengisi `to` / akun yang hilang dari rute tersimpan sesi peminta (`lastChannel` / `lastTo` / `lastAccountId`) sebelum menyerah pada pengiriman langsung. + +**Pengiriman melalui antrean sesi** — jika pengiriman langsung gagal atau tidak ada origin yang ditetapkan, pembaruan diantrikan sebagai peristiwa sistem dalam sesi peminta dan akan muncul pada heartbeat berikutnya. + + +Penyelesaian tugas memicu kebangkitan heartbeat segera sehingga Anda dapat melihat hasilnya dengan cepat — Anda tidak perlu menunggu tick heartbeat terjadwal berikutnya. + + +Artinya, alur kerja yang umum bersifat berbasis push: mulai pekerjaan terlepas sekali, lalu biarkan runtime membangunkan atau memberi tahu Anda saat selesai. Poll status tugas hanya saat Anda memerlukan debugging, intervensi, atau audit eksplisit. + +### Kebijakan notifikasi + +Kendalikan seberapa banyak Anda menerima kabar tentang setiap tugas: + +| Kebijakan | Yang dikirim | +| ---------------------- | ---------------------------------------------------------------------- | +| `done_only` (default) | Hanya status terminal (`succeeded`, `failed`, dll.) — **ini adalah default** | +| `state_changes` | Setiap transisi status dan pembaruan progres | +| `silent` | Tidak ada sama sekali | + +Ubah kebijakan saat tugas sedang berjalan: + +```bash +openclaw tasks notify state_changes +``` + +## Referensi CLI + +### `tasks list` + +```bash +openclaw tasks list [--runtime ] [--status ] [--json] +``` + +Kolom output: ID Tugas, Jenis, Status, Pengiriman, ID Proses, Sesi Anak, Ringkasan. + +### `tasks show` + +```bash +openclaw tasks show +``` + +Token lookup menerima ID tugas, ID proses, atau kunci sesi. Menampilkan rekaman lengkap termasuk waktu, status pengiriman, error, dan ringkasan terminal. + +### `tasks cancel` + +```bash +openclaw tasks cancel +``` + +Untuk tugas ACP dan subagen, ini menghentikan sesi anak. Status bertransisi ke `cancelled` dan notifikasi pengiriman dikirim. + +### `tasks notify` + +```bash +openclaw tasks notify +``` + +### `tasks audit` + +```bash +openclaw tasks audit [--json] +``` + +Menampilkan masalah operasional. Temuan juga muncul di `openclaw status` saat masalah terdeteksi. + +| Temuan | Tingkat keparahan | Pemicu | +| ------------------------- | ----------------- | ----------------------------------------------------- | +| `stale_queued` | peringatan | Berada di antrean lebih dari 10 menit | +| `stale_running` | error | Berjalan lebih dari 30 menit | +| `lost` | error | Kepemilikan tugas berbasis runtime menghilang | +| `delivery_failed` | peringatan | Pengiriman gagal dan kebijakan notifikasi bukan `silent` | +| `missing_cleanup` | peringatan | Tugas terminal tanpa stempel waktu pembersihan | +| `inconsistent_timestamps` | peringatan | Pelanggaran linimasa (misalnya berakhir sebelum dimulai) | + +### `tasks maintenance` + +```bash +openclaw tasks maintenance [--json] +openclaw tasks maintenance --apply [--json] +``` + +Gunakan ini untuk mempratinjau atau menerapkan rekonsiliasi, penandaan pembersihan, dan pemangkasan untuk tugas dan status Task Flow. + +Rekonsiliasi bergantung pada runtime: + +- Tugas ACP/subagen memeriksa sesi anak pendukungnya. +- Tugas cron memeriksa apakah runtime cron masih memiliki job tersebut. +- Tugas CLI berbasis chat memeriksa konteks proses langsung milik pemiliknya, bukan hanya baris sesi chat. + +Pembersihan penyelesaian juga bergantung pada runtime: + +- Penyelesaian subagen sebisa mungkin menutup tab/proses browser yang dilacak untuk sesi anak sebelum pembersihan pengumuman dilanjutkan. +- Penyelesaian cron terisolasi sebisa mungkin menutup tab/proses browser yang dilacak untuk sesi cron sebelum proses sepenuhnya dibongkar. +- Pengiriman cron terisolasi menunggu tindak lanjut subagen turunan bila perlu dan menekan teks pengakuan induk yang sudah usang alih-alih mengumumkannya. +- Pengiriman penyelesaian subagen memprioritaskan teks asisten terbaru yang terlihat; jika kosong, pengiriman akan menggunakan cadangan berupa teks tool/toolResult terbaru yang telah disanitasi, dan proses panggilan tool yang hanya timeout dapat diringkas menjadi ringkasan progres parsial yang singkat. +- Kegagalan pembersihan tidak menutupi hasil tugas yang sebenarnya. + +### `tasks flow list|show|cancel` + +```bash +openclaw tasks flow list [--status ] [--json] +openclaw tasks flow show [--json] +openclaw tasks flow cancel +``` + +Gunakan ini saat Task Flow pengorkestrasi adalah hal yang Anda pedulikan, bukan satu rekaman tugas latar belakang individual. + +## Papan tugas chat (`/tasks`) + +Gunakan `/tasks` di sesi chat mana pun untuk melihat tugas latar belakang yang ditautkan ke sesi tersebut. Papan ini menampilkan tugas aktif dan yang baru saja selesai beserta runtime, status, waktu, dan detail progres atau error. + +Saat sesi saat ini tidak memiliki tugas tertaut yang terlihat, `/tasks` akan menggunakan cadangan berupa jumlah tugas lokal agen sehingga Anda tetap mendapatkan gambaran umum tanpa membocorkan detail sesi lain. + +Untuk buku besar operator lengkap, gunakan CLI: `openclaw tasks list`. + +## Integrasi status (tekanan tugas) + +`openclaw status` menyertakan ringkasan tugas sekilas: + +``` +Tasks: 3 queued · 2 running · 1 issues +``` + +Ringkasan ini melaporkan: + +- **active** — jumlah `queued` + `running` +- **failures** — jumlah `failed` + `timed_out` + `lost` +- **byRuntime** — perincian berdasarkan `acp`, `subagent`, `cron`, `cli` + +Baik `/status` maupun tool `session_status` menggunakan snapshot tugas yang sadar pembersihan: tugas aktif diprioritaskan, baris selesai yang basi disembunyikan, dan kegagalan terbaru hanya muncul saat tidak ada pekerjaan aktif yang tersisa. Ini menjaga kartu status tetap fokus pada hal yang penting saat ini. + +## Penyimpanan dan pemeliharaan + +### Tempat tugas disimpan + +Rekaman tugas disimpan secara persisten di SQLite pada: + +``` +$OPENCLAW_STATE_DIR/tasks/runs.sqlite +``` + +Registri dimuat ke memori saat gateway dimulai dan menyinkronkan penulisan ke SQLite untuk ketahanan di seluruh restart. + +### Pemeliharaan otomatis + +Sebuah sweeper berjalan setiap **60 detik** dan menangani tiga hal: + +1. **Rekonsiliasi** — memeriksa apakah tugas aktif masih memiliki dukungan runtime otoritatif. Tugas ACP/subagen menggunakan status sesi anak, tugas cron menggunakan kepemilikan job aktif, dan tugas CLI berbasis chat menggunakan konteks proses milik pemiliknya. Jika status dukungan itu hilang selama lebih dari 5 menit, tugas ditandai sebagai `lost`. +2. **Penandaan pembersihan** — menetapkan stempel waktu `cleanupAfter` pada tugas terminal (`endedAt + 7 days`). +3. **Pemangkasan** — menghapus rekaman yang telah melewati tanggal `cleanupAfter`. + +**Retensi**: rekaman tugas terminal disimpan selama **7 hari**, lalu dipangkas secara otomatis. Tidak perlu konfigurasi. + +## Bagaimana tugas terkait dengan sistem lain + +### Tugas dan Task Flow + +[Task Flow](/automation/taskflow) adalah lapisan orkestrasi alur di atas tugas latar belakang. Satu alur dapat mengoordinasikan beberapa tugas selama masa hidupnya menggunakan mode sinkronisasi terkelola atau tercermin. Gunakan `openclaw tasks` untuk memeriksa rekaman tugas individual dan `openclaw tasks flow` untuk memeriksa alur pengorkestrasi. + +Lihat [Task Flow](/automation/taskflow) untuk detailnya. + +### Tugas dan cron + +Sebuah **definisi** job cron disimpan di `~/.openclaw/cron/jobs.json`. **Setiap** eksekusi cron membuat rekaman tugas — baik sesi utama maupun terisolasi. Tugas cron sesi utama default ke kebijakan notifikasi `silent` sehingga tetap terlacak tanpa menghasilkan notifikasi. + +Lihat [Job Cron](/automation/cron-jobs). + +### Tugas dan heartbeat + +Proses heartbeat adalah giliran sesi utama — proses ini tidak membuat rekaman tugas. Saat sebuah tugas selesai, tugas itu dapat memicu kebangkitan heartbeat agar Anda segera melihat hasilnya. + +Lihat [Heartbeat](/gateway/heartbeat). + +### Tugas dan sesi + +Sebuah tugas dapat merujuk ke `childSessionKey` (tempat pekerjaan berjalan) dan `requesterSessionKey` (siapa yang memulainya). Sesi adalah konteks percakapan; tugas adalah pelacakan aktivitas di atas konteks itu. + +### Tugas dan proses agen + +`runId` sebuah tugas terhubung ke proses agen yang melakukan pekerjaan. Peristiwa siklus hidup agen (mulai, selesai, error) secara otomatis memperbarui status tugas — Anda tidak perlu mengelola siklus hidupnya secara manual. + +## Terkait + +- [Otomasi & Tugas](/automation) — semua mekanisme otomasi secara sekilas +- [Task Flow](/automation/taskflow) — orkestrasi alur di atas tugas +- [Tugas Terjadwal](/automation/cron-jobs) — penjadwalan pekerjaan latar belakang +- [Heartbeat](/gateway/heartbeat) — giliran sesi utama berkala +- [CLI: Tasks](/cli/index#tasks) — referensi perintah CLI diff --git a/docs/id/automation/troubleshooting.md b/docs/id/automation/troubleshooting.md new file mode 100644 index 000000000..5ce28d6e9 --- /dev/null +++ b/docs/id/automation/troubleshooting.md @@ -0,0 +1,15 @@ +--- +summary: Alihkan ke /automation/cron-jobs +title: Pemecahan Masalah Otomasi +x-i18n: + generated_at: "2026-04-05T13:42:09Z" + model: gpt-5.4 + provider: openai + source_hash: 6621342754fb56234b89e71167f73bad6c070273ff0b8d12dbb20854e32e7980 + source_path: automation/troubleshooting.md + workflow: 15 +--- + +# Pemecahan Masalah Otomasi + +Halaman ini dipindahkan ke [Tugas Terjadwal](/automation/cron-jobs#troubleshooting). Lihat [Tugas Terjadwal](/automation/cron-jobs#troubleshooting) untuk dokumentasi pemecahan masalah. diff --git a/docs/id/automation/webhook.md b/docs/id/automation/webhook.md new file mode 100644 index 000000000..08483e3e1 --- /dev/null +++ b/docs/id/automation/webhook.md @@ -0,0 +1,15 @@ +--- +summary: Alihkan ke /automation/cron-jobs +title: Webhooks +x-i18n: + generated_at: "2026-04-05T13:42:11Z" + model: gpt-5.4 + provider: openai + source_hash: 7511f6bc28e7f13ee1d9313bb5551825afb5706019068079603a44668c4dda34 + source_path: automation/webhook.md + workflow: 15 +--- + +# Webhooks + +Halaman ini dipindahkan ke [Tugas Terjadwal](/automation/cron-jobs#webhooks). Lihat [Tugas Terjadwal](/automation/cron-jobs#webhooks) untuk dokumentasi webhook. diff --git a/docs/id/brave-search.md b/docs/id/brave-search.md new file mode 100644 index 000000000..b079191fd --- /dev/null +++ b/docs/id/brave-search.md @@ -0,0 +1,110 @@ +--- +read_when: + - Anda ingin menggunakan Brave Search untuk web_search + - Anda memerlukan BRAVE_API_KEY atau detail paket +summary: Penyiapan Brave Search API untuk web_search +title: Brave Search (jalur lama) +x-i18n: + generated_at: "2026-04-05T13:42:25Z" + model: gpt-5.4 + provider: openai + source_hash: 7788e4cee7dc460819e55095c87df8cea29ba3a8bd3cef4c0e98ac601b45b651 + source_path: brave-search.md + workflow: 15 +--- + +# Brave Search API + +OpenClaw mendukung Brave Search API sebagai penyedia `web_search`. + +## Dapatkan kunci API + +1. Buat akun Brave Search API di [https://brave.com/search/api/](https://brave.com/search/api/) +2. Di dasbor, pilih paket **Search** dan buat kunci API. +3. Simpan kunci tersebut di konfigurasi atau tetapkan `BRAVE_API_KEY` di environment Gateway. + +## Contoh konfigurasi + +```json5 +{ + plugins: { + entries: { + brave: { + config: { + webSearch: { + apiKey: "BRAVE_API_KEY_HERE", + mode: "web", // or "llm-context" + }, + }, + }, + }, + }, + tools: { + web: { + search: { + provider: "brave", + maxResults: 5, + timeoutSeconds: 30, + }, + }, + }, +} +``` + +Pengaturan pencarian Brave yang khusus penyedia kini berada di bawah `plugins.entries.brave.config.webSearch.*`. +`tools.web.search.apiKey` lama masih dimuat melalui shim kompatibilitas, tetapi itu bukan lagi jalur konfigurasi kanonis. + +`webSearch.mode` mengontrol transport Brave: + +- `web` (default): pencarian web Brave normal dengan judul, URL, dan cuplikan +- `llm-context`: Brave LLM Context API dengan potongan teks dan sumber yang sudah diekstrak sebelumnya untuk grounding + +## Parameter alat + +| Parameter | Deskripsi | +| ------------- | ------------------------------------------------------------------- | +| `query` | Kueri pencarian (wajib) | +| `count` | Jumlah hasil yang dikembalikan (1-10, default: 5) | +| `country` | Kode negara ISO 2 huruf (misalnya, "US", "DE") | +| `language` | Kode bahasa ISO 639-1 untuk hasil pencarian (misalnya, "en", "de", "fr") | +| `search_lang` | Kode bahasa pencarian Brave (misalnya, `en`, `en-gb`, `zh-hans`) | +| `ui_lang` | Kode bahasa ISO untuk elemen UI | +| `freshness` | Filter waktu: `day` (24 jam), `week`, `month`, atau `year` | +| `date_after` | Hanya hasil yang dipublikasikan setelah tanggal ini (YYYY-MM-DD) | +| `date_before` | Hanya hasil yang dipublikasikan sebelum tanggal ini (YYYY-MM-DD) | + +**Contoh:** + +```javascript +// Country and language-specific search +await web_search({ + query: "renewable energy", + country: "DE", + language: "de", +}); + +// Recent results (past week) +await web_search({ + query: "AI news", + freshness: "week", +}); + +// Date range search +await web_search({ + query: "AI developments", + date_after: "2024-01-01", + date_before: "2024-06-30", +}); +``` + +## Catatan + +- OpenClaw menggunakan paket Brave **Search**. Jika Anda memiliki langganan lama (misalnya paket Free asli dengan 2.000 kueri/bulan), langganan itu tetap valid tetapi tidak mencakup fitur yang lebih baru seperti LLM Context atau batas laju yang lebih tinggi. +- Setiap paket Brave menyertakan **\$5/bulan dalam kredit gratis** (diperbarui). Paket Search berbiaya \$5 per 1.000 permintaan, jadi kredit tersebut mencakup 1.000 kueri/bulan. Tetapkan batas penggunaan Anda di dasbor Brave untuk menghindari biaya tak terduga. Lihat [portal Brave API](https://brave.com/search/api/) untuk paket saat ini. +- Paket Search mencakup endpoint LLM Context dan hak inferensi AI. Menyimpan hasil untuk melatih atau menyetel model memerlukan paket dengan hak penyimpanan eksplisit. Lihat Brave [Ketentuan Layanan](https://api-dashboard.search.brave.com/terms-of-service). +- Mode `llm-context` mengembalikan entri sumber yang digrounded alih-alih bentuk cuplikan pencarian web normal. +- Mode `llm-context` tidak mendukung `ui_lang`, `freshness`, `date_after`, atau `date_before`. +- `ui_lang` harus menyertakan subtag wilayah seperti `en-US`. +- Hasil di-cache selama 15 menit secara default (dapat dikonfigurasi melalui `cacheTtlMinutes`). + +Lihat [Alat web](/tools/web) untuk konfigurasi lengkap `web_search`. diff --git a/docs/id/channels/bluebubbles.md b/docs/id/channels/bluebubbles.md new file mode 100644 index 000000000..fa736fbf1 --- /dev/null +++ b/docs/id/channels/bluebubbles.md @@ -0,0 +1,442 @@ +--- +read_when: + - Menyiapkan channel BlueBubbles + - Memecahkan masalah pairing webhook + - Mengonfigurasi iMessage di macOS +summary: iMessage melalui server macOS BlueBubbles (REST kirim/terima, mengetik, reaksi, pairing, tindakan lanjutan). +title: BlueBubbles +x-i18n: + generated_at: "2026-04-05T13:43:04Z" + model: gpt-5.4 + provider: openai + source_hash: ed8e59a165bdfb8fd794ee2ad6e4dacd44aa02d512312c5f2fd7d15f863380bb + source_path: channels/bluebubbles.md + workflow: 15 +--- + +# BlueBubbles (REST macOS) + +Status: plugin bawaan yang berkomunikasi dengan server macOS BlueBubbles melalui HTTP. **Direkomendasikan untuk integrasi iMessage** karena API-nya lebih kaya dan penyiapannya lebih mudah dibandingkan channel imsg lama. + +## Plugin bawaan + +Rilis OpenClaw saat ini menyertakan BlueBubbles, jadi build paket normal tidak +memerlukan langkah `openclaw plugins install` terpisah. + +## Gambaran umum + +- Berjalan di macOS melalui aplikasi helper BlueBubbles ([bluebubbles.app](https://bluebubbles.app)). +- Direkomendasikan/teruji: macOS Sequoia (15). macOS Tahoe (26) berfungsi; edit saat ini rusak di Tahoe, dan pembaruan ikon grup dapat dilaporkan berhasil tetapi tidak tersinkron. +- OpenClaw berkomunikasi dengannya melalui API REST-nya (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`). +- Pesan masuk tiba melalui webhook; balasan keluar, indikator mengetik, tanda baca, dan tapback adalah panggilan REST. +- Lampiran dan stiker diingest sebagai media masuk (dan ditampilkan ke agen jika memungkinkan). +- Pairing/allowlist berfungsi sama seperti channel lain (`/channels/pairing` dan seterusnya) dengan `channels.bluebubbles.allowFrom` + kode pairing. +- Reaksi ditampilkan sebagai event sistem seperti Slack/Telegram sehingga agen dapat "menyebutkannya" sebelum membalas. +- Fitur lanjutan: edit, batalkan kirim, utas balasan, efek pesan, manajemen grup. + +## Mulai cepat + +1. Instal server BlueBubbles di Mac Anda (ikuti petunjuk di [bluebubbles.app/install](https://bluebubbles.app/install)). +2. Di konfigurasi BlueBubbles, aktifkan web API dan tetapkan kata sandi. +3. Jalankan `openclaw onboard` dan pilih BlueBubbles, atau konfigurasi secara manual: + + ```json5 + { + channels: { + bluebubbles: { + enabled: true, + serverUrl: "http://192.168.1.100:1234", + password: "example-password", + webhookPath: "/bluebubbles-webhook", + }, + }, + } + ``` + +4. Arahkan webhook BlueBubbles ke gateway Anda (contoh: `https://your-gateway-host:3000/bluebubbles-webhook?password=`). +5. Mulai gateway; gateway akan mendaftarkan handler webhook dan memulai pairing. + +Catatan keamanan: + +- Selalu tetapkan kata sandi webhook. +- Autentikasi webhook selalu wajib. OpenClaw menolak permintaan webhook BlueBubbles kecuali permintaan tersebut menyertakan password/guid yang cocok dengan `channels.bluebubbles.password` (misalnya `?password=` atau `x-password`), terlepas dari topologi loopback/proxy. +- Autentikasi kata sandi diperiksa sebelum membaca/mengurai body webhook secara penuh. + +## Menjaga Messages.app tetap aktif (VM / penyiapan headless) + +Beberapa penyiapan VM macOS / selalu aktif dapat membuat Messages.app menjadi “idle” (event masuk berhenti sampai aplikasi dibuka/dijadikan foreground). Solusi sederhananya adalah **menyentuh Messages setiap 5 menit** menggunakan AppleScript + LaunchAgent. + +### 1) Simpan AppleScript + +Simpan sebagai: + +- `~/Scripts/poke-messages.scpt` + +Contoh skrip (non-interaktif; tidak mencuri fokus): + +```applescript +try + tell application "Messages" + if not running then + launch + end if + + -- Touch the scripting interface to keep the process responsive. + set _chatCount to (count of chats) + end tell +on error + -- Ignore transient failures (first-run prompts, locked session, etc). +end try +``` + +### 2) Instal LaunchAgent + +Simpan sebagai: + +- `~/Library/LaunchAgents/com.user.poke-messages.plist` + +```xml + + + + + Label + com.user.poke-messages + + ProgramArguments + + /bin/bash + -lc + /usr/bin/osascript "$HOME/Scripts/poke-messages.scpt" + + + RunAtLoad + + + StartInterval + 300 + + StandardOutPath + /tmp/poke-messages.log + StandardErrorPath + /tmp/poke-messages.err + + +``` + +Catatan: + +- Ini berjalan **setiap 300 detik** dan **saat login**. +- Proses pertama kali berjalan dapat memicu prompt macOS **Automation** (`osascript` → Messages). Setujui prompt tersebut di sesi pengguna yang sama yang menjalankan LaunchAgent. + +Muat: + +```bash +launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true +launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist +``` + +## Onboarding + +BlueBubbles tersedia dalam onboarding interaktif: + +``` +openclaw onboard +``` + +Wizard akan meminta: + +- **URL Server** (wajib): alamat server BlueBubbles (misalnya, `http://192.168.1.100:1234`) +- **Password** (wajib): kata sandi API dari pengaturan BlueBubbles Server +- **Path webhook** (opsional): default ke `/bluebubbles-webhook` +- **Kebijakan DM**: pairing, allowlist, open, atau disabled +- **Daftar izinkan**: nomor telepon, email, atau target chat + +Anda juga dapat menambahkan BlueBubbles melalui CLI: + +``` +openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password +``` + +## Kontrol akses (DM + grup) + +DM: + +- Default: `channels.bluebubbles.dmPolicy = "pairing"`. +- Pengirim yang tidak dikenal menerima kode pairing; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam). +- Setujui melalui: + - `openclaw pairing list bluebubbles` + - `openclaw pairing approve bluebubbles ` +- Pairing adalah pertukaran token default. Detail: [Pairing](/channels/pairing) + +Grup: + +- `channels.bluebubbles.groupPolicy = open | allowlist | disabled` (default: `allowlist`). +- `channels.bluebubbles.groupAllowFrom` mengontrol siapa yang dapat memicu di grup ketika `allowlist` ditetapkan. + +### Pengayaan nama kontak (macOS, opsional) + +Webhook grup BlueBubbles sering kali hanya menyertakan alamat peserta mentah. Jika Anda ingin konteks `GroupMembers` menampilkan nama kontak lokal sebagai gantinya, Anda dapat memilih pengayaan Contacts lokal di macOS: + +- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` mengaktifkan lookup. Default: `false`. +- Lookup hanya dijalankan setelah akses grup, otorisasi perintah, dan penggatingan mention mengizinkan pesan lolos. +- Hanya peserta telepon tanpa nama yang diperkaya. +- Nomor telepon mentah tetap menjadi fallback saat tidak ditemukan kecocokan lokal. + +```json5 +{ + channels: { + bluebubbles: { + enrichGroupParticipantsFromContacts: true, + }, + }, +} +``` + +### Penggatingan mention (grup) + +BlueBubbles mendukung penggatingan mention untuk chat grup, selaras dengan perilaku iMessage/WhatsApp: + +- Menggunakan `agents.list[].groupChat.mentionPatterns` (atau `messages.groupChat.mentionPatterns`) untuk mendeteksi mention. +- Ketika `requireMention` diaktifkan untuk sebuah grup, agen hanya merespons saat disebut. +- Perintah kontrol dari pengirim yang berwenang melewati penggatingan mention. + +Konfigurasi per grup: + +```json5 +{ + channels: { + bluebubbles: { + groupPolicy: "allowlist", + groupAllowFrom: ["+15555550123"], + groups: { + "*": { requireMention: true }, // default untuk semua grup + "iMessage;-;chat123": { requireMention: false }, // override untuk grup tertentu + }, + }, + }, +} +``` + +### Penggatingan perintah + +- Perintah kontrol (misalnya, `/config`, `/model`) memerlukan otorisasi. +- Menggunakan `allowFrom` dan `groupAllowFrom` untuk menentukan otorisasi perintah. +- Pengirim yang berwenang dapat menjalankan perintah kontrol bahkan tanpa mention di grup. + +## Binding percakapan ACP + +Chat BlueBubbles dapat diubah menjadi workspace ACP yang persisten tanpa mengubah lapisan transport. + +Alur operator cepat: + +- Jalankan `/acp spawn codex --bind here` di dalam DM atau chat grup yang diizinkan. +- Pesan berikutnya dalam percakapan BlueBubbles yang sama akan dirutekan ke sesi ACP yang telah di-spawn. +- `/new` dan `/reset` mereset sesi ACP terikat yang sama di tempat. +- `/acp close` menutup sesi ACP dan menghapus binding. + +Binding persisten yang dikonfigurasi juga didukung melalui entri `bindings[]` tingkat atas dengan `type: "acp"` dan `match.channel: "bluebubbles"`. + +`match.peer.id` dapat menggunakan bentuk target BlueBubbles yang didukung: + +- handle DM yang dinormalisasi seperti `+15555550123` atau `user@example.com` +- `chat_id:` +- `chat_guid:` +- `chat_identifier:` + +Untuk binding grup yang stabil, utamakan `chat_id:*` atau `chat_identifier:*`. + +Contoh: + +```json5 +{ + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { agent: "codex", backend: "acpx", mode: "persistent" }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "bluebubbles", + accountId: "default", + peer: { kind: "dm", id: "+15555550123" }, + }, + acp: { label: "codex-imessage" }, + }, + ], +} +``` + +Lihat [Agen ACP](/tools/acp-agents) untuk perilaku binding ACP bersama. + +## Mengetik + tanda baca + +- **Indikator mengetik**: Dikirim secara otomatis sebelum dan selama pembuatan respons. +- **Tanda baca**: Dikontrol oleh `channels.bluebubbles.sendReadReceipts` (default: `true`). +- **Indikator mengetik**: OpenClaw mengirim event mulai mengetik; BlueBubbles menghapus status mengetik secara otomatis saat mengirim atau saat timeout (penghentian manual via DELETE tidak andal). + +```json5 +{ + channels: { + bluebubbles: { + sendReadReceipts: false, // nonaktifkan tanda baca + }, + }, +} +``` + +## Tindakan lanjutan + +BlueBubbles mendukung tindakan pesan lanjutan saat diaktifkan di konfigurasi: + +```json5 +{ + channels: { + bluebubbles: { + actions: { + reactions: true, // tapback (default: true) + edit: true, // edit pesan terkirim (macOS 13+, rusak di macOS 26 Tahoe) + unsend: true, // batalkan kirim pesan (macOS 13+) + reply: true, // utas balasan berdasarkan GUID pesan + sendWithEffect: true, // efek pesan (slam, loud, dll.) + renameGroup: true, // ganti nama chat grup + setGroupIcon: true, // setel ikon/foto chat grup (tidak stabil di macOS 26 Tahoe) + addParticipant: true, // tambahkan peserta ke grup + removeParticipant: true, // hapus peserta dari grup + leaveGroup: true, // keluar dari chat grup + sendAttachment: true, // kirim lampiran/media + }, + }, + }, +} +``` + +Tindakan yang tersedia: + +- **react**: Tambahkan/hapus reaksi tapback (`messageId`, `emoji`, `remove`) +- **edit**: Edit pesan yang telah dikirim (`messageId`, `text`) +- **unsend**: Batalkan kirim pesan (`messageId`) +- **reply**: Balas pesan tertentu (`messageId`, `text`, `to`) +- **sendWithEffect**: Kirim dengan efek iMessage (`text`, `to`, `effectId`) +- **renameGroup**: Ganti nama chat grup (`chatGuid`, `displayName`) +- **setGroupIcon**: Setel ikon/foto chat grup (`chatGuid`, `media`) — tidak stabil di macOS 26 Tahoe (API mungkin mengembalikan sukses tetapi ikon tidak tersinkron). +- **addParticipant**: Tambahkan seseorang ke grup (`chatGuid`, `address`) +- **removeParticipant**: Hapus seseorang dari grup (`chatGuid`, `address`) +- **leaveGroup**: Keluar dari chat grup (`chatGuid`) +- **upload-file**: Kirim media/file (`to`, `buffer`, `filename`, `asVoice`) + - Memo suara: setel `asVoice: true` dengan audio **MP3** atau **CAF** untuk mengirim sebagai pesan suara iMessage. BlueBubbles mengonversi MP3 → CAF saat mengirim memo suara. +- Alias lama: `sendAttachment` masih berfungsi, tetapi `upload-file` adalah nama tindakan kanonis. + +### ID pesan (singkat vs penuh) + +OpenClaw dapat menampilkan ID pesan _singkat_ (misalnya, `1`, `2`) untuk menghemat token. + +- `MessageSid` / `ReplyToId` dapat berupa ID singkat. +- `MessageSidFull` / `ReplyToIdFull` berisi ID penuh provider. +- ID singkat berada di memori; ID ini dapat kedaluwarsa saat restart atau pengusiran cache. +- Tindakan menerima `messageId` singkat atau penuh, tetapi ID singkat akan menghasilkan error jika sudah tidak tersedia. + +Gunakan ID penuh untuk otomasi dan penyimpanan yang persisten: + +- Template: `{{MessageSidFull}}`, `{{ReplyToIdFull}}` +- Konteks: `MessageSidFull` / `ReplyToIdFull` di payload masuk + +Lihat [Konfigurasi](/gateway/configuration) untuk variabel template. + +## Streaming blok + +Kontrol apakah respons dikirim sebagai satu pesan atau di-stream dalam blok: + +```json5 +{ + channels: { + bluebubbles: { + blockStreaming: true, // aktifkan streaming blok (nonaktif secara default) + }, + }, +} +``` + +## Media + batasan + +- Lampiran masuk diunduh dan disimpan di cache media. +- Batas media melalui `channels.bluebubbles.mediaMaxMb` untuk media masuk dan keluar (default: 8 MB). +- Teks keluar dipecah menjadi `channels.bluebubbles.textChunkLimit` (default: 4000 karakter). + +## Referensi konfigurasi + +Konfigurasi lengkap: [Konfigurasi](/gateway/configuration) + +Opsi provider: + +- `channels.bluebubbles.enabled`: Aktifkan/nonaktifkan channel. +- `channels.bluebubbles.serverUrl`: URL dasar API REST BlueBubbles. +- `channels.bluebubbles.password`: Kata sandi API. +- `channels.bluebubbles.webhookPath`: Path endpoint webhook (default: `/bluebubbles-webhook`). +- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (default: `pairing`). +- `channels.bluebubbles.allowFrom`: allowlist DM (handle, email, nomor E.164, `chat_id:*`, `chat_guid:*`). +- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (default: `allowlist`). +- `channels.bluebubbles.groupAllowFrom`: allowlist pengirim grup. +- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: Di macOS, secara opsional memperkaya peserta grup tanpa nama dari Contacts lokal setelah gating lolos. Default: `false`. +- `channels.bluebubbles.groups`: Konfigurasi per grup (`requireMention`, dll.). +- `channels.bluebubbles.sendReadReceipts`: Kirim tanda baca (default: `true`). +- `channels.bluebubbles.blockStreaming`: Aktifkan streaming blok (default: `false`; diperlukan untuk balasan streaming). +- `channels.bluebubbles.textChunkLimit`: Ukuran potongan keluar dalam karakter (default: 4000). +- `channels.bluebubbles.chunkMode`: `length` (default) membagi hanya saat melebihi `textChunkLimit`; `newline` membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang. +- `channels.bluebubbles.mediaMaxMb`: Batas media masuk/keluar dalam MB (default: 8). +- `channels.bluebubbles.mediaLocalRoots`: allowlist eksplisit direktori lokal absolut yang diizinkan untuk path media lokal keluar. Pengiriman path lokal ditolak secara default kecuali ini dikonfigurasi. Override per akun: `channels.bluebubbles.accounts..mediaLocalRoots`. +- `channels.bluebubbles.historyLimit`: Maks pesan grup untuk konteks (0 menonaktifkan). +- `channels.bluebubbles.dmHistoryLimit`: Batas riwayat DM. +- `channels.bluebubbles.actions`: Aktifkan/nonaktifkan tindakan tertentu. +- `channels.bluebubbles.accounts`: Konfigurasi multi-akun. + +Opsi global terkait: + +- `agents.list[].groupChat.mentionPatterns` (atau `messages.groupChat.mentionPatterns`). +- `messages.responsePrefix`. + +## Pengalamatan / target pengiriman + +Utamakan `chat_guid` untuk perutean yang stabil: + +- `chat_guid:iMessage;-;+15555550123` (disarankan untuk grup) +- `chat_id:123` +- `chat_identifier:...` +- Handle langsung: `+15555550123`, `user@example.com` + - Jika handle langsung tidak memiliki chat DM yang sudah ada, OpenClaw akan membuatnya melalui `POST /api/v1/chat/new`. Ini mengharuskan BlueBubbles Private API diaktifkan. + +## Keamanan + +- Permintaan webhook diautentikasi dengan membandingkan parameter query atau header `guid`/`password` dengan `channels.bluebubbles.password`. +- Jaga kerahasiaan kata sandi API dan endpoint webhook (perlakukan keduanya seperti kredensial). +- Tidak ada bypass localhost untuk autentikasi webhook BlueBubbles. Jika Anda mem-proxy lalu lintas webhook, pertahankan kata sandi BlueBubbles pada permintaan secara end-to-end. `gateway.trustedProxies` tidak menggantikan `channels.bluebubbles.password` di sini. Lihat [Keamanan gateway](/gateway/security#reverse-proxy-configuration). +- Aktifkan HTTPS + aturan firewall pada server BlueBubbles jika diekspos di luar LAN Anda. + +## Pemecahan masalah + +- Jika event mengetik/baca berhenti berfungsi, periksa log webhook BlueBubbles dan verifikasi path gateway cocok dengan `channels.bluebubbles.webhookPath`. +- Kode pairing kedaluwarsa setelah satu jam; gunakan `openclaw pairing list bluebubbles` dan `openclaw pairing approve bluebubbles `. +- Reaksi memerlukan BlueBubbles private API (`POST /api/v1/message/react`); pastikan versi server mengeksposnya. +- Edit/batalkan kirim memerlukan macOS 13+ dan versi server BlueBubbles yang kompatibel. Di macOS 26 (Tahoe), edit saat ini rusak karena perubahan private API. +- Pembaruan ikon grup bisa tidak stabil di macOS 26 (Tahoe): API mungkin mengembalikan sukses tetapi ikon baru tidak tersinkron. +- OpenClaw secara otomatis menyembunyikan tindakan yang diketahui rusak berdasarkan versi macOS server BlueBubbles. Jika edit masih muncul di macOS 26 (Tahoe), nonaktifkan secara manual dengan `channels.bluebubbles.actions.edit=false`. +- Untuk info status/kesehatan: `openclaw status --all` atau `openclaw status --deep`. + +Untuk referensi alur kerja channel umum, lihat [Channels](/channels) dan panduan [Plugins](/tools/plugin). + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku chat grup dan penggatingan mention +- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/broadcast-groups.md b/docs/id/channels/broadcast-groups.md new file mode 100644 index 000000000..c6c9439ba --- /dev/null +++ b/docs/id/channels/broadcast-groups.md @@ -0,0 +1,449 @@ +--- +read_when: + - Mengonfigurasi broadcast groups + - Men-debug balasan multi-agent di WhatsApp +status: experimental +summary: Siarkan pesan WhatsApp ke beberapa agent +title: Broadcast Groups +x-i18n: + generated_at: "2026-04-05T13:42:50Z" + model: gpt-5.4 + provider: openai + source_hash: 1d117ae65ec3b63c2bd4b3c215d96f32d7eafa0f99a9cd7378e502c15e56ca56 + source_path: channels/broadcast-groups.md + workflow: 15 +--- + +# Broadcast Groups + +**Status:** Eksperimental +**Versi:** Ditambahkan pada 2026.1.9 + +## Ikhtisar + +Broadcast Groups memungkinkan beberapa agent memproses dan merespons pesan yang sama secara bersamaan. Ini memungkinkan Anda membuat tim agent khusus yang bekerja bersama dalam satu grup atau DM WhatsApp — semuanya menggunakan satu nomor telepon. + +Cakupan saat ini: **WhatsApp saja** (channel web). + +Broadcast groups dievaluasi setelah allowlist channel dan aturan aktivasi grup. Di grup WhatsApp, ini berarti siaran terjadi saat OpenClaw biasanya akan membalas (misalnya: saat disebut, tergantung pada pengaturan grup Anda). + +## Kasus Penggunaan + +### 1. Tim Agent Khusus + +Terapkan beberapa agent dengan tanggung jawab atomik dan terfokus: + +``` +Group: "Development Team" +Agents: + - CodeReviewer (reviews code snippets) + - DocumentationBot (generates docs) + - SecurityAuditor (checks for vulnerabilities) + - TestGenerator (suggests test cases) +``` + +Setiap agent memproses pesan yang sama dan memberikan perspektif khususnya. + +### 2. Dukungan Multi-Bahasa + +``` +Group: "International Support" +Agents: + - Agent_EN (responds in English) + - Agent_DE (responds in German) + - Agent_ES (responds in Spanish) +``` + +### 3. Alur Kerja Jaminan Kualitas + +``` +Group: "Customer Support" +Agents: + - SupportAgent (provides answer) + - QAAgent (reviews quality, only responds if issues found) +``` + +### 4. Otomatisasi Tugas + +``` +Group: "Project Management" +Agents: + - TaskTracker (updates task database) + - TimeLogger (logs time spent) + - ReportGenerator (creates summaries) +``` + +## Konfigurasi + +### Pengaturan Dasar + +Tambahkan bagian `broadcast` tingkat atas (di samping `bindings`). Kuncinya adalah ID peer WhatsApp: + +- obrolan grup: JID grup (misalnya `120363403215116621@g.us`) +- DM: nomor telepon E.164 (misalnya `+15551234567`) + +```json +{ + "broadcast": { + "120363403215116621@g.us": ["alfred", "baerbel", "assistant3"] + } +} +``` + +**Hasil:** Saat OpenClaw akan membalas di obrolan ini, OpenClaw akan menjalankan ketiga agent tersebut. + +### Strategi Pemrosesan + +Kontrol bagaimana agent memproses pesan: + +#### Paralel (Default) + +Semua agent memproses secara bersamaan: + +```json +{ + "broadcast": { + "strategy": "parallel", + "120363403215116621@g.us": ["alfred", "baerbel"] + } +} +``` + +#### Berurutan + +Agent memproses secara berurutan (satu menunggu yang sebelumnya selesai): + +```json +{ + "broadcast": { + "strategy": "sequential", + "120363403215116621@g.us": ["alfred", "baerbel"] + } +} +``` + +### Contoh Lengkap + +```json +{ + "agents": { + "list": [ + { + "id": "code-reviewer", + "name": "Code Reviewer", + "workspace": "/path/to/code-reviewer", + "sandbox": { "mode": "all" } + }, + { + "id": "security-auditor", + "name": "Security Auditor", + "workspace": "/path/to/security-auditor", + "sandbox": { "mode": "all" } + }, + { + "id": "docs-generator", + "name": "Documentation Generator", + "workspace": "/path/to/docs-generator", + "sandbox": { "mode": "all" } + } + ] + }, + "broadcast": { + "strategy": "parallel", + "120363403215116621@g.us": ["code-reviewer", "security-auditor", "docs-generator"], + "120363424282127706@g.us": ["support-en", "support-de"], + "+15555550123": ["assistant", "logger"] + } +} +``` + +## Cara Kerjanya + +### Alur Pesan + +1. **Pesan masuk** tiba di grup WhatsApp +2. **Pemeriksaan broadcast**: Sistem memeriksa apakah ID peer ada di `broadcast` +3. **Jika ada dalam daftar broadcast**: + - Semua agent yang tercantum memproses pesan + - Setiap agent memiliki kunci sesi sendiri dan konteks yang terisolasi + - Agent memproses secara paralel (default) atau berurutan +4. **Jika tidak ada dalam daftar broadcast**: + - Routing normal berlaku (binding pertama yang cocok) + +Catatan: broadcast groups tidak mem-bypass allowlist channel atau aturan aktivasi grup (mention/perintah/dll). Fitur ini hanya mengubah _agent mana yang dijalankan_ saat sebuah pesan memenuhi syarat untuk diproses. + +### Isolasi Sesi + +Setiap agent dalam broadcast group mempertahankan hal-hal berikut secara sepenuhnya terpisah: + +- **Kunci sesi** (`agent:alfred:whatsapp:group:120363...` vs `agent:baerbel:whatsapp:group:120363...`) +- **Riwayat percakapan** (agent tidak melihat pesan agent lain) +- **Workspace** (sandbox terpisah jika dikonfigurasi) +- **Akses tool** (daftar allow/deny yang berbeda) +- **Memori/konteks** (`IDENTITY.md`, `SOUL.md`, dll. yang terpisah) +- **Buffer konteks grup** (pesan grup terbaru yang digunakan untuk konteks) dibagikan per peer, jadi semua agent broadcast melihat konteks yang sama saat dipicu + +Ini memungkinkan setiap agent memiliki: + +- Kepribadian yang berbeda +- Akses tool yang berbeda (misalnya, read-only vs. read-write) +- Model yang berbeda (misalnya, opus vs. sonnet) +- Skills berbeda yang terinstal + +### Contoh: Sesi Terisolasi + +Di grup `120363403215116621@g.us` dengan agent `["alfred", "baerbel"]`: + +**Konteks Alfred:** + +``` +Session: agent:alfred:whatsapp:group:120363403215116621@g.us +History: [user message, alfred's previous responses] +Workspace: /Users/user/openclaw-alfred/ +Tools: read, write, exec +``` + +**Konteks Bärbel:** + +``` +Session: agent:baerbel:whatsapp:group:120363403215116621@g.us +History: [user message, baerbel's previous responses] +Workspace: /Users/user/openclaw-baerbel/ +Tools: read only +``` + +## Praktik Terbaik + +### 1. Pertahankan Agent Tetap Terfokus + +Rancang setiap agent dengan satu tanggung jawab yang jelas: + +```json +{ + "broadcast": { + "DEV_GROUP": ["formatter", "linter", "tester"] + } +} +``` + +✅ **Baik:** Setiap agent memiliki satu tugas +❌ **Buruk:** Satu agent "dev-helper" generik + +### 2. Gunakan Nama yang Deskriptif + +Buat jelas apa yang dilakukan setiap agent: + +```json +{ + "agents": { + "security-scanner": { "name": "Security Scanner" }, + "code-formatter": { "name": "Code Formatter" }, + "test-generator": { "name": "Test Generator" } + } +} +``` + +### 3. Konfigurasikan Akses Tool yang Berbeda + +Berikan agent hanya tool yang mereka perlukan: + +```json +{ + "agents": { + "reviewer": { + "tools": { "allow": ["read", "exec"] } // Read-only + }, + "fixer": { + "tools": { "allow": ["read", "write", "edit", "exec"] } // Read-write + } + } +} +``` + +### 4. Pantau Performa + +Dengan banyak agent, pertimbangkan: + +- Menggunakan `"strategy": "parallel"` (default) untuk kecepatan +- Membatasi broadcast groups menjadi 5-10 agent +- Menggunakan model yang lebih cepat untuk agent yang lebih sederhana + +### 5. Tangani Kegagalan dengan Baik + +Agent gagal secara independen. Kesalahan pada satu agent tidak memblokir yang lain: + +``` +Message → [Agent A ✓, Agent B ✗ error, Agent C ✓] +Result: Agent A and C respond, Agent B logs error +``` + +## Kompatibilitas + +### Provider + +Broadcast groups saat ini berfungsi dengan: + +- ✅ WhatsApp (sudah diimplementasikan) +- 🚧 Telegram (direncanakan) +- 🚧 Discord (direncanakan) +- 🚧 Slack (direncanakan) + +### Routing + +Broadcast groups berfungsi bersama routing yang sudah ada: + +```json +{ + "bindings": [ + { + "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } }, + "agentId": "alfred" + } + ], + "broadcast": { + "GROUP_B": ["agent1", "agent2"] + } +} +``` + +- `GROUP_A`: Hanya alfred yang merespons (routing normal) +- `GROUP_B`: agent1 DAN agent2 merespons (broadcast) + +**Prioritas:** `broadcast` memiliki prioritas lebih tinggi daripada `bindings`. + +## Pemecahan Masalah + +### Agent Tidak Merespons + +**Periksa:** + +1. ID agent ada di `agents.list` +2. Format ID peer benar (misalnya, `120363403215116621@g.us`) +3. Agent tidak ada dalam deny list + +**Debug:** + +```bash +tail -f ~/.openclaw/logs/gateway.log | grep broadcast +``` + +### Hanya Satu Agent yang Merespons + +**Penyebab:** ID peer mungkin ada di `bindings` tetapi tidak ada di `broadcast`. + +**Perbaikan:** Tambahkan ke konfigurasi broadcast atau hapus dari bindings. + +### Masalah Performa + +**Jika lambat dengan banyak agent:** + +- Kurangi jumlah agent per grup +- Gunakan model yang lebih ringan (sonnet alih-alih opus) +- Periksa waktu startup sandbox + +## Contoh + +### Contoh 1: Tim Review Kode + +```json +{ + "broadcast": { + "strategy": "parallel", + "120363403215116621@g.us": [ + "code-formatter", + "security-scanner", + "test-coverage", + "docs-checker" + ] + }, + "agents": { + "list": [ + { + "id": "code-formatter", + "workspace": "~/agents/formatter", + "tools": { "allow": ["read", "write"] } + }, + { + "id": "security-scanner", + "workspace": "~/agents/security", + "tools": { "allow": ["read", "exec"] } + }, + { + "id": "test-coverage", + "workspace": "~/agents/testing", + "tools": { "allow": ["read", "exec"] } + }, + { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } } + ] + } +} +``` + +**Pengguna mengirim:** Potongan kode +**Respons:** + +- code-formatter: "Memperbaiki indentasi dan menambahkan type hint" +- security-scanner: "⚠️ Kerentanan SQL injection pada baris 12" +- test-coverage: "Cakupan 45%, tes untuk kasus kesalahan masih kurang" +- docs-checker: "Docstring untuk fungsi `process_data` tidak ada" + +### Contoh 2: Dukungan Multi-Bahasa + +```json +{ + "broadcast": { + "strategy": "sequential", + "+15555550123": ["detect-language", "translator-en", "translator-de"] + }, + "agents": { + "list": [ + { "id": "detect-language", "workspace": "~/agents/lang-detect" }, + { "id": "translator-en", "workspace": "~/agents/translate-en" }, + { "id": "translator-de", "workspace": "~/agents/translate-de" } + ] + } +} +``` + +## Referensi API + +### Skema Konfigurasi + +```typescript +interface OpenClawConfig { + broadcast?: { + strategy?: "parallel" | "sequential"; + [peerId: string]: string[]; + }; +} +``` + +### Field + +- `strategy` (opsional): Cara memproses agent + - `"parallel"` (default): Semua agent memproses secara bersamaan + - `"sequential"`: Agent memproses sesuai urutan array +- `[peerId]`: JID grup WhatsApp, nomor E.164, atau ID peer lainnya + - Nilai: Array ID agent yang harus memproses pesan + +## Keterbatasan + +1. **Maks agent:** Tidak ada batas keras, tetapi 10+ agent mungkin lambat +2. **Konteks bersama:** Agent tidak melihat respons satu sama lain (sesuai desain) +3. **Urutan pesan:** Respons paralel dapat tiba dalam urutan apa pun +4. **Batas laju:** Semua agent dihitung terhadap batas laju WhatsApp + +## Peningkatan di Masa Depan + +Fitur yang direncanakan: + +- [ ] Mode konteks bersama (agent melihat respons satu sama lain) +- [ ] Koordinasi agent (agent dapat saling memberi sinyal) +- [ ] Pemilihan agent dinamis (pilih agent berdasarkan isi pesan) +- [ ] Prioritas agent (beberapa agent merespons sebelum yang lain) + +## Lihat Juga + +- [Konfigurasi Multi-Agent](/tools/multi-agent-sandbox-tools) +- [Konfigurasi Routing](/channels/channel-routing) +- [Manajemen Sesi](/concepts/session) diff --git a/docs/id/channels/channel-routing.md b/docs/id/channels/channel-routing.md new file mode 100644 index 000000000..878c037a0 --- /dev/null +++ b/docs/id/channels/channel-routing.md @@ -0,0 +1,136 @@ +--- +read_when: + - Mengubah perutean channel atau perilaku inbox +summary: Aturan perutean per channel (WhatsApp, Telegram, Discord, Slack) dan konteks bersama +title: Perutean Channel +x-i18n: + generated_at: "2026-04-05T13:42:36Z" + model: gpt-5.4 + provider: openai + source_hash: 63916c4dd0af5fc9bbd12581a9eb15fea14a380c5ade09323ca0c237db61e537 + source_path: channels/channel-routing.md + workflow: 15 +--- + +# Channel & perutean + +OpenClaw merutekan balasan **kembali ke channel asal pesan**. Model tidak memilih channel; perutean bersifat deterministik dan dikendalikan oleh konfigurasi host. + +## Istilah utama + +- **Channel**: `telegram`, `whatsapp`, `discord`, `irc`, `googlechat`, `slack`, `signal`, `imessage`, `line`, ditambah extension channel. `webchat` adalah channel UI WebChat internal dan bukan channel outbound yang dapat dikonfigurasi. +- **AccountId**: instance akun per channel (jika didukung). +- Akun default channel opsional: `channels..defaultAccount` memilih akun mana yang digunakan saat jalur outbound tidak menentukan `accountId`. + - Dalam pengaturan multi-akun, tetapkan default eksplisit (`defaultAccount` atau `accounts.default`) saat dua atau lebih akun dikonfigurasi. Tanpanya, perutean fallback dapat memilih ID akun ternormalisasi pertama. +- **AgentId**: penyimpanan workspace + sesi yang terisolasi (“otak”). +- **SessionKey**: kunci bucket yang digunakan untuk menyimpan konteks dan mengendalikan konkurensi. + +## Bentuk kunci sesi (contoh) + +Pesan langsung disatukan ke sesi **utama** agen: + +- `agent::` (default: `agent:main:main`) + +Grup dan channel tetap terisolasi per channel: + +- Grup: `agent:::group:` +- Channel/room: `agent:::channel:` + +Thread: + +- Thread Slack/Discord menambahkan `:thread:` ke kunci dasar. +- Topik forum Telegram menyematkan `:topic:` dalam kunci grup. + +Contoh: + +- `agent:main:telegram:group:-1001234567890:topic:42` +- `agent:main:discord:channel:123456:thread:987654` + +## Penyematan rute DM utama + +Saat `session.dmScope` adalah `main`, pesan langsung dapat berbagi satu sesi utama. +Untuk mencegah `lastRoute` sesi ditimpa oleh DM non-pemilik, OpenClaw menyimpulkan pemilik yang disematkan dari `allowFrom` jika semua kondisi berikut benar: + +- `allowFrom` memiliki tepat satu entri non-wildcard. +- Entri tersebut dapat dinormalisasi menjadi ID pengirim konkret untuk channel itu. +- Pengirim DM masuk tidak cocok dengan pemilik yang disematkan itu. + +Dalam kasus ketidakcocokan tersebut, OpenClaw tetap merekam metadata sesi masuk, tetapi melewati pembaruan `lastRoute` sesi utama. + +## Aturan perutean (cara agen dipilih) + +Perutean memilih **satu agen** untuk setiap pesan masuk: + +1. **Kecocokan peer persis** (`bindings` dengan `peer.kind` + `peer.id`). +2. **Kecocokan peer induk** (pewarisan thread). +3. **Kecocokan guild + roles** (Discord) melalui `guildId` + `roles`. +4. **Kecocokan guild** (Discord) melalui `guildId`. +5. **Kecocokan team** (Slack) melalui `teamId`. +6. **Kecocokan akun** (`accountId` pada channel). +7. **Kecocokan channel** (akun apa pun pada channel tersebut, `accountId: "*"`). +8. **Agen default** (`agents.list[].default`, jika tidak maka entri daftar pertama, fallback ke `main`). + +Saat sebuah binding menyertakan beberapa field kecocokan (`peer`, `guildId`, `teamId`, `roles`), **semua field yang disediakan harus cocok** agar binding tersebut berlaku. + +Agen yang cocok menentukan workspace dan penyimpanan sesi mana yang digunakan. + +## Grup broadcast (menjalankan beberapa agen) + +Grup broadcast memungkinkan Anda menjalankan **beberapa agen** untuk peer yang sama **saat OpenClaw biasanya akan membalas** (misalnya: di grup WhatsApp, setelah penyebutan/activation gating). + +Konfigurasi: + +```json5 +{ + broadcast: { + strategy: "parallel", + "120363403215116621@g.us": ["alfred", "baerbel"], + "+15555550123": ["support", "logger"], + }, +} +``` + +Lihat: [Grup Broadcast](/channels/broadcast-groups). + +## Gambaran umum konfigurasi + +- `agents.list`: definisi agen bernama (workspace, model, dll.). +- `bindings`: memetakan channel/akun/peer masuk ke agen. + +Contoh: + +```json5 +{ + agents: { + list: [{ id: "support", name: "Support", workspace: "~/.openclaw/workspace-support" }], + }, + bindings: [ + { match: { channel: "slack", teamId: "T123" }, agentId: "support" }, + { match: { channel: "telegram", peer: { kind: "group", id: "-100123" } }, agentId: "support" }, + ], +} +``` + +## Penyimpanan sesi + +Penyimpanan sesi berada di bawah direktori state (default `~/.openclaw`): + +- `~/.openclaw/agents//sessions/sessions.json` +- Transkrip JSONL berada di lokasi yang sama dengan penyimpanan + +Anda dapat menimpa jalur penyimpanan melalui `session.store` dan templating `{agentId}`. + +Penemuan sesi Gateway dan ACP juga memindai penyimpanan agen berbasis disk di bawah root `agents/` default dan di bawah root `session.store` bertemplat. Penyimpanan yang ditemukan harus tetap berada di dalam root agen yang telah di-resolve tersebut dan menggunakan file `sessions.json` biasa. Symlink dan jalur di luar root diabaikan. + +## Perilaku WebChat + +WebChat terpasang ke **agen yang dipilih** dan default ke sesi utama agen. Karena itu, WebChat memungkinkan Anda melihat konteks lintas-channel untuk agen tersebut di satu tempat. + +## Konteks balasan + +Balasan masuk mencakup: + +- `ReplyToId`, `ReplyToBody`, dan `ReplyToSender` jika tersedia. +- Konteks kutipan ditambahkan ke `Body` sebagai blok `[Replying to ...]`. + +Ini konsisten di semua channel. diff --git a/docs/id/channels/discord.md b/docs/id/channels/discord.md new file mode 100644 index 000000000..afd4b85be --- /dev/null +++ b/docs/id/channels/discord.md @@ -0,0 +1,1261 @@ +--- +read_when: + - Mengerjakan fitur channel Discord +summary: Status dukungan bot Discord, kemampuan, dan konfigurasi +title: Discord +x-i18n: + generated_at: "2026-04-05T13:44:18Z" + model: gpt-5.4 + provider: openai + source_hash: e757d321d80d05642cd9e24b51fb47897bacaf8db19df83bd61a49a8ce51ed3a + source_path: channels/discord.md + workflow: 15 +--- + +# Discord (Bot API) + +Status: siap untuk DM dan channel guild melalui gateway Discord resmi. + + + + DM Discord secara default menggunakan mode pairing. + + + Perilaku perintah native dan katalog perintah. + + + Diagnostik lintas-channel dan alur perbaikan. + + + +## Penyiapan cepat + +Anda perlu membuat aplikasi baru dengan bot, menambahkan bot ke server Anda, dan memasangkannya ke OpenClaw. Kami merekomendasikan menambahkan bot Anda ke server privat Anda sendiri. Jika Anda belum memilikinya, [buat dulu](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (pilih **Create My Own > For me and my friends**). + + + + Buka [Discord Developer Portal](https://discord.com/developers/applications) dan klik **New Application**. Beri nama seperti "OpenClaw". + + Klik **Bot** di sidebar. Atur **Username** ke nama apa pun yang Anda gunakan untuk agen OpenClaw Anda. + + + + + Masih di halaman **Bot**, gulir ke bawah ke **Privileged Gateway Intents** lalu aktifkan: + + - **Message Content Intent** (wajib) + - **Server Members Intent** (disarankan; wajib untuk allowlist role dan pencocokan nama ke ID) + - **Presence Intent** (opsional; hanya diperlukan untuk pembaruan presence) + + + + + Gulir kembali ke atas pada halaman **Bot** lalu klik **Reset Token**. + + + Meski namanya begitu, ini membuat token pertama Anda — tidak ada yang sedang "di-reset." + + + Salin token tersebut dan simpan di suatu tempat. Ini adalah **Bot Token** Anda dan Anda akan segera membutuhkannya. + + + + + Klik **OAuth2** di sidebar. Anda akan membuat URL undangan dengan izin yang tepat untuk menambahkan bot ke server Anda. + + Gulir ke bawah ke **OAuth2 URL Generator** lalu aktifkan: + + - `bot` + - `applications.commands` + + Bagian **Bot Permissions** akan muncul di bawahnya. Aktifkan: + + - View Channels + - Send Messages + - Read Message History + - Embed Links + - Attach Files + - Add Reactions (opsional) + + Salin URL yang dihasilkan di bagian bawah, tempelkan ke browser Anda, pilih server Anda, lalu klik **Continue** untuk menghubungkan. Anda sekarang seharusnya melihat bot Anda di server Discord. + + + + + Kembali ke aplikasi Discord, Anda perlu mengaktifkan Developer Mode agar dapat menyalin ID internal. + + 1. Klik **User Settings** (ikon roda gigi di sebelah avatar Anda) → **Advanced** → aktifkan **Developer Mode** + 2. Klik kanan **ikon server** Anda di sidebar → **Copy Server ID** + 3. Klik kanan **avatar Anda sendiri** → **Copy User ID** + + Simpan **Server ID** dan **User ID** Anda bersama Bot Token — Anda akan mengirim ketiganya ke OpenClaw pada langkah berikutnya. + + + + + Agar pairing berfungsi, Discord perlu mengizinkan bot Anda mengirim DM kepada Anda. Klik kanan **ikon server** Anda → **Privacy Settings** → aktifkan **Direct Messages**. + + Ini memungkinkan anggota server (termasuk bot) mengirim DM kepada Anda. Biarkan ini tetap aktif jika Anda ingin menggunakan DM Discord dengan OpenClaw. Jika Anda hanya berencana menggunakan channel guild, Anda dapat menonaktifkan DM setelah pairing. + + + + + Token bot Discord Anda adalah rahasia (seperti kata sandi). Tetapkan token tersebut pada mesin yang menjalankan OpenClaw sebelum mengirim pesan ke agen Anda. + +```bash +export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" +openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run +openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN +openclaw config set channels.discord.enabled true --strict-json +openclaw gateway +``` + + Jika OpenClaw sudah berjalan sebagai layanan latar belakang, mulai ulang melalui aplikasi OpenClaw Mac atau dengan menghentikan dan menjalankan kembali proses `openclaw gateway run`. + + + + + + + + Chat dengan agen OpenClaw Anda di channel yang sudah ada (misalnya Telegram) dan beri tahu. Jika Discord adalah channel pertama Anda, gunakan tab CLI / config. + + > "Saya sudah menetapkan token bot Discord saya di config. Tolong selesaikan penyiapan Discord dengan User ID `` dan Server ID ``." + + + Jika Anda lebih suka konfigurasi berbasis file, tetapkan: + +```json5 +{ + channels: { + discord: { + enabled: true, + token: { + source: "env", + provider: "default", + id: "DISCORD_BOT_TOKEN", + }, + }, + }, +} +``` + + Fallback env untuk akun default: + +```bash +DISCORD_BOT_TOKEN=... +``` + + Nilai `token` plaintext didukung. Nilai SecretRef juga didukung untuk `channels.discord.token` pada provider env/file/exec. Lihat [Secrets Management](/gateway/secrets). + + + + + + + + Tunggu hingga gateway berjalan, lalu kirim DM ke bot Anda di Discord. Bot akan merespons dengan kode pairing. + + + + Kirim kode pairing ke agen Anda di channel yang sudah ada: + + > "Setujui kode pairing Discord ini: ``" + + + +```bash +openclaw pairing list discord +openclaw pairing approve discord +``` + + + + + Kode pairing kedaluwarsa setelah 1 jam. + + Anda sekarang seharusnya dapat chat dengan agen Anda di Discord melalui DM. + + + + + +Resolusi token memperhatikan akun. Nilai token di config lebih diutamakan daripada fallback env. `DISCORD_BOT_TOKEN` hanya digunakan untuk akun default. +Untuk panggilan keluar tingkat lanjut (aksi message tool/channel), `token` eksplisit per panggilan digunakan untuk panggilan tersebut. Ini berlaku untuk aksi gaya kirim dan baca/probe (misalnya read/search/fetch/thread/pins/permissions). Pengaturan kebijakan akun/retry tetap berasal dari akun yang dipilih dalam snapshot runtime aktif. + + +## Rekomendasi: Siapkan workspace guild + +Setelah DM berfungsi, Anda dapat menyiapkan server Discord Anda sebagai workspace penuh, di mana setiap channel mendapatkan sesi agen tersendiri dengan konteksnya sendiri. Ini direkomendasikan untuk server privat yang hanya berisi Anda dan bot Anda. + + + + Ini memungkinkan agen Anda merespons di channel mana pun pada server Anda, bukan hanya DM. + + + + > "Tambahkan Server ID Discord saya `` ke guild allowlist" + + + +```json5 +{ + channels: { + discord: { + groupPolicy: "allowlist", + guilds: { + YOUR_SERVER_ID: { + requireMention: true, + users: ["YOUR_USER_ID"], + }, + }, + }, + }, +} +``` + + + + + + + + Secara default, agen Anda hanya merespons di channel guild saat di-@mention. Untuk server privat, Anda kemungkinan ingin agen merespons setiap pesan. + + + + > "Izinkan agen saya merespons di server ini tanpa harus di-@mention" + + + Tetapkan `requireMention: false` di config guild Anda: + +```json5 +{ + channels: { + discord: { + guilds: { + YOUR_SERVER_ID: { + requireMention: false, + }, + }, + }, + }, +} +``` + + + + + + + + Secara default, memori jangka panjang (MEMORY.md) hanya dimuat dalam sesi DM. Channel guild tidak otomatis memuat MEMORY.md. + + + + > "Saat saya mengajukan pertanyaan di channel Discord, gunakan memory_search atau memory_get jika Anda memerlukan konteks jangka panjang dari MEMORY.md." + + + Jika Anda memerlukan konteks bersama di setiap channel, letakkan instruksi yang stabil di `AGENTS.md` atau `USER.md` (keduanya disuntikkan untuk setiap sesi). Simpan catatan jangka panjang di `MEMORY.md` dan akses sesuai kebutuhan dengan memory tools. + + + + + + +Sekarang buat beberapa channel di server Discord Anda dan mulailah chat. Agen Anda dapat melihat nama channel, dan setiap channel mendapatkan sesi terisolasi sendiri — jadi Anda dapat menyiapkan `#coding`, `#home`, `#research`, atau apa pun yang sesuai dengan alur kerja Anda. + +## Model runtime + +- Gateway memiliki koneksi Discord. +- Routing balasan bersifat deterministik: balasan masuk Discord kembali ke Discord. +- Secara default (`session.dmScope=main`), chat langsung berbagi sesi utama agen (`agent:main:main`). +- Channel guild menggunakan kunci sesi terisolasi (`agent::discord:channel:`). +- Group DM diabaikan secara default (`channels.discord.dm.groupEnabled=false`). +- Slash command native berjalan dalam sesi perintah terisolasi (`agent::discord:slash:`), sambil tetap membawa `CommandTargetSessionKey` ke sesi percakapan yang dirutekan. + +## Channel forum + +Channel forum dan media Discord hanya menerima posting thread. OpenClaw mendukung dua cara untuk membuatnya: + +- Kirim pesan ke induk forum (`channel:`) untuk membuat thread secara otomatis. Judul thread menggunakan baris pertama pesan Anda yang tidak kosong. +- Gunakan `openclaw message thread create` untuk membuat thread secara langsung. Jangan berikan `--message-id` untuk channel forum. + +Contoh: kirim ke induk forum untuk membuat thread + +```bash +openclaw message send --channel discord --target channel: \ + --message "Topic title\nBody of the post" +``` + +Contoh: buat thread forum secara eksplisit + +```bash +openclaw message thread create --channel discord --target channel: \ + --thread-name "Topic title" --message "Body of the post" +``` + +Induk forum tidak menerima komponen Discord. Jika Anda memerlukan komponen, kirim ke thread itu sendiri (`channel:`). + +## Komponen interaktif + +OpenClaw mendukung container Discord components v2 untuk pesan agen. Gunakan message tool dengan payload `components`. Hasil interaksi dirutekan kembali ke agen sebagai pesan masuk normal dan mengikuti pengaturan Discord `replyToMode` yang ada. + +Blok yang didukung: + +- `text`, `section`, `separator`, `actions`, `media-gallery`, `file` +- Baris aksi mengizinkan hingga 5 tombol atau satu menu pilih +- Jenis select: `string`, `user`, `role`, `mentionable`, `channel` + +Secara default, komponen hanya dapat digunakan satu kali. Tetapkan `components.reusable=true` agar tombol, select, dan form dapat digunakan beberapa kali sampai kedaluwarsa. + +Untuk membatasi siapa yang dapat mengklik tombol, tetapkan `allowedUsers` pada tombol tersebut (ID pengguna Discord, tag, atau `*`). Saat dikonfigurasi, pengguna yang tidak cocok akan menerima penolakan ephemeral. + +Slash command `/model` dan `/models` membuka pemilih model interaktif dengan dropdown penyedia dan model serta langkah Submit. Balasan pemilih bersifat ephemeral dan hanya pengguna yang memanggil yang dapat menggunakannya. + +Lampiran file: + +- blok `file` harus menunjuk ke referensi lampiran (`attachment://`) +- Berikan lampiran melalui `media`/`path`/`filePath` (satu file); gunakan `media-gallery` untuk beberapa file +- Gunakan `filename` untuk mengganti nama upload saat harus cocok dengan referensi lampiran + +Form modal: + +- Tambahkan `components.modal` dengan hingga 5 field +- Jenis field: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` +- OpenClaw menambahkan tombol pemicu secara otomatis + +Contoh: + +```json5 +{ + channel: "discord", + action: "send", + to: "channel:123456789012345678", + message: "Optional fallback text", + components: { + reusable: true, + text: "Choose a path", + blocks: [ + { + type: "actions", + buttons: [ + { + label: "Approve", + style: "success", + allowedUsers: ["123456789012345678"], + }, + { label: "Decline", style: "danger" }, + ], + }, + { + type: "actions", + select: { + type: "string", + placeholder: "Pick an option", + options: [ + { label: "Option A", value: "a" }, + { label: "Option B", value: "b" }, + ], + }, + }, + ], + modal: { + title: "Details", + triggerLabel: "Open form", + fields: [ + { type: "text", label: "Requester" }, + { + type: "select", + label: "Priority", + options: [ + { label: "Low", value: "low" }, + { label: "High", value: "high" }, + ], + }, + ], + }, + }, +} +``` + +## Kontrol akses dan routing + + + + `channels.discord.dmPolicy` mengontrol akses DM (lama: `channels.discord.dm.policy`): + + - `pairing` (default) + - `allowlist` + - `open` (memerlukan `channels.discord.allowFrom` menyertakan `"*"`; lama: `channels.discord.dm.allowFrom`) + - `disabled` + + Jika kebijakan DM tidak terbuka, pengguna yang tidak dikenal diblokir (atau diminta pairing dalam mode `pairing`). + + Prioritas multi-akun: + + - `channels.discord.accounts.default.allowFrom` hanya berlaku untuk akun `default`. + - Akun bernama mewarisi `channels.discord.allowFrom` ketika `allowFrom` milik mereka sendiri tidak ditetapkan. + - Akun bernama tidak mewarisi `channels.discord.accounts.default.allowFrom`. + + Format target DM untuk pengiriman: + + - `user:` + - mention `<@id>` + + ID numerik polos ambigu dan ditolak kecuali jenis target pengguna/channel yang eksplisit diberikan. + + + + + Penanganan guild dikontrol oleh `channels.discord.groupPolicy`: + + - `open` + - `allowlist` + - `disabled` + + Baseline aman saat `channels.discord` ada adalah `allowlist`. + + Perilaku `allowlist`: + + - guild harus cocok dengan `channels.discord.guilds` (`id` lebih disukai, slug diterima) + - allowlist pengirim opsional: `users` (ID stabil disarankan) dan `roles` (hanya ID role); jika salah satunya dikonfigurasi, pengirim diizinkan jika cocok dengan `users` ATAU `roles` + - pencocokan nama/tag langsung dinonaktifkan secara default; aktifkan `channels.discord.dangerouslyAllowNameMatching: true` hanya sebagai mode kompatibilitas darurat + - nama/tag didukung untuk `users`, tetapi ID lebih aman; `openclaw security audit` memperingatkan saat entri nama/tag digunakan + - jika guild memiliki `channels` yang dikonfigurasi, channel yang tidak terdaftar akan ditolak + - jika guild tidak memiliki blok `channels`, semua channel di guild yang di-allowlist diizinkan + + Contoh: + +```json5 +{ + channels: { + discord: { + groupPolicy: "allowlist", + guilds: { + "123456789012345678": { + requireMention: true, + ignoreOtherMentions: true, + users: ["987654321098765432"], + roles: ["123456789012345678"], + channels: { + general: { allow: true }, + help: { allow: true, requireMention: true }, + }, + }, + }, + }, + }, +} +``` + + Jika Anda hanya menetapkan `DISCORD_BOT_TOKEN` dan tidak membuat blok `channels.discord`, fallback runtime adalah `groupPolicy="allowlist"` (dengan peringatan di log), meskipun `channels.defaults.groupPolicy` adalah `open`. + + + + + Pesan guild dibatasi oleh mention secara default. + + Deteksi mention mencakup: + + - mention bot eksplisit + - pola mention yang dikonfigurasi (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) + - perilaku reply-to-bot implisit dalam kasus yang didukung + + `requireMention` dikonfigurasi per guild/channel (`channels.discord.guilds...`). + `ignoreOtherMentions` secara opsional menghapus pesan yang me-mention pengguna/role lain tetapi bukan bot (tidak termasuk @everyone/@here). + + Group DM: + + - default: diabaikan (`dm.groupEnabled=false`) + - allowlist opsional melalui `dm.groupChannels` (ID channel atau slug) + + + + +### Routing agen berbasis role + +Gunakan `bindings[].match.roles` untuk merutekan anggota guild Discord ke agen yang berbeda berdasarkan ID role. Binding berbasis role hanya menerima ID role dan dievaluasi setelah binding peer atau parent-peer dan sebelum binding khusus guild. Jika binding juga menetapkan field pencocokan lain (misalnya `peer` + `guildId` + `roles`), semua field yang dikonfigurasi harus cocok. + +```json5 +{ + bindings: [ + { + agentId: "opus", + match: { + channel: "discord", + guildId: "123456789012345678", + roles: ["111111111111111111"], + }, + }, + { + agentId: "sonnet", + match: { + channel: "discord", + guildId: "123456789012345678", + }, + }, + ], +} +``` + +## Penyiapan Developer Portal + + + + + 1. Discord Developer Portal -> **Applications** -> **New Application** + 2. **Bot** -> **Add Bot** + 3. Salin token bot + + + + + Di **Bot -> Privileged Gateway Intents**, aktifkan: + + - Message Content Intent + - Server Members Intent (disarankan) + + Presence intent bersifat opsional dan hanya diperlukan jika Anda ingin menerima pembaruan presence. Menetapkan presence bot (`setPresence`) tidak memerlukan pengaktifan pembaruan presence untuk anggota. + + + + + Generator URL OAuth: + + - cakupan: `bot`, `applications.commands` + + Izin baseline umum: + + - View Channels + - Send Messages + - Read Message History + - Embed Links + - Attach Files + - Add Reactions (opsional) + + Hindari `Administrator` kecuali benar-benar diperlukan. + + + + + Aktifkan Discord Developer Mode, lalu salin: + + - ID server + - ID channel + - ID pengguna + + Utamakan ID numerik di config OpenClaw untuk audit dan probe yang andal. + + + + +## Perintah native dan autentikasi perintah + +- `commands.native` default ke `"auto"` dan diaktifkan untuk Discord. +- Override per-channel: `channels.discord.commands.native`. +- `commands.native=false` secara eksplisit menghapus perintah native Discord yang sebelumnya terdaftar. +- Autentikasi perintah native menggunakan allowlist/kebijakan Discord yang sama seperti penanganan pesan normal. +- Perintah mungkin tetap terlihat di UI Discord untuk pengguna yang tidak berwenang; eksekusi tetap menegakkan autentikasi OpenClaw dan mengembalikan "not authorized". + +Lihat [Slash commands](/tools/slash-commands) untuk katalog dan perilaku perintah. + +Pengaturan default slash command: + +- `ephemeral: true` + +## Detail fitur + + + + Discord mendukung tag balasan dalam output agen: + + - `[[reply_to_current]]` + - `[[reply_to:]]` + + Dikontrol oleh `channels.discord.replyToMode`: + + - `off` (default) + - `first` + - `all` + + Catatan: `off` menonaktifkan threading balasan implisit. Tag `[[reply_to_*]]` eksplisit tetap dihormati. + + ID pesan dimunculkan dalam konteks/riwayat sehingga agen dapat menargetkan pesan tertentu. + + + + + OpenClaw dapat men-stream balasan draf dengan mengirim pesan sementara dan mengeditnya saat teks masuk. + + - `channels.discord.streaming` mengontrol streaming pratinjau (`off` | `partial` | `block` | `progress`, default: `off`). + - Default tetap `off` karena edit pratinjau Discord dapat dengan cepat mencapai batas laju, terutama ketika beberapa bot atau gateway berbagi akun atau lalu lintas guild yang sama. + - `progress` diterima untuk konsistensi lintas-channel dan dipetakan ke `partial` di Discord. + - `channels.discord.streamMode` adalah alias lama dan dimigrasikan otomatis. + - `partial` mengedit satu pesan pratinjau saat token masuk. + - `block` mengeluarkan potongan seukuran draf (gunakan `draftChunk` untuk menyetel ukuran dan titik pemisahan). + + Contoh: + +```json5 +{ + channels: { + discord: { + streaming: "partial", + }, + }, +} +``` + + Default pemotongan mode `block` (dibatasi ke `channels.discord.textChunkLimit`): + +```json5 +{ + channels: { + discord: { + streaming: "block", + draftChunk: { + minChars: 200, + maxChars: 800, + breakPreference: "paragraph", + }, + }, + }, +} +``` + + Streaming pratinjau hanya untuk teks; balasan media kembali ke pengiriman normal. + + Catatan: streaming pratinjau terpisah dari block streaming. Saat block streaming secara eksplisit + diaktifkan untuk Discord, OpenClaw melewati stream pratinjau untuk menghindari streaming ganda. + + + + + Konteks riwayat guild: + + - `channels.discord.historyLimit` default `20` + - fallback: `messages.groupChat.historyLimit` + - `0` menonaktifkan + + Kontrol riwayat DM: + + - `channels.discord.dmHistoryLimit` + - `channels.discord.dms[""].historyLimit` + + Perilaku thread: + + - thread Discord dirutekan sebagai sesi channel + - metadata thread induk dapat digunakan untuk penautan sesi induk + - config thread mewarisi config channel induk kecuali ada entri khusus thread + + Topik channel disuntikkan sebagai konteks **tidak tepercaya** (bukan sebagai system prompt). + Konteks balasan dan pesan kutipan saat ini tetap sebagaimana diterima. + Allowlist Discord terutama membatasi siapa yang dapat memicu agen, bukan batas redaksi konteks tambahan yang sepenuhnya lengkap. + + + + + Discord dapat mengikat thread ke target sesi sehingga pesan lanjutan di thread tersebut terus dirutekan ke sesi yang sama (termasuk sesi subagen). + + Perintah: + + - `/focus ` mengikat thread saat ini/baru ke target subagen/sesi + - `/unfocus` menghapus ikatan thread saat ini + - `/agents` menampilkan run aktif dan status binding + - `/session idle ` memeriksa/memperbarui auto-unfocus karena tidak aktif untuk binding yang difokuskan + - `/session max-age ` memeriksa/memperbarui usia maksimum keras untuk binding yang difokuskan + + Config: + +```json5 +{ + session: { + threadBindings: { + enabled: true, + idleHours: 24, + maxAgeHours: 0, + }, + }, + channels: { + discord: { + threadBindings: { + enabled: true, + idleHours: 24, + maxAgeHours: 0, + spawnSubagentSessions: false, // opt-in + }, + }, + }, +} +``` + + Catatan: + + - `session.threadBindings.*` menetapkan default global. + - `channels.discord.threadBindings.*` mengganti perilaku Discord. + - `spawnSubagentSessions` harus true untuk membuat/mengikat thread secara otomatis bagi `sessions_spawn({ thread: true })`. + - `spawnAcpSessions` harus true untuk membuat/mengikat thread secara otomatis bagi ACP (`/acp spawn ... --thread ...` atau `sessions_spawn({ runtime: "acp", thread: true })`). + - Jika thread binding dinonaktifkan untuk suatu akun, `/focus` dan operasi thread binding terkait tidak tersedia. + + Lihat [Sub-agents](/tools/subagents), [ACP Agents](/tools/acp-agents), dan [Configuration Reference](/gateway/configuration-reference). + + + + + Untuk workspace ACP stabil yang "selalu aktif", konfigurasikan binding ACP bertipe top-level yang menargetkan percakapan Discord. + + Jalur config: + + - `bindings[]` dengan `type: "acp"` dan `match.channel: "discord"` + + Contoh: + +```json5 +{ + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { + agent: "codex", + backend: "acpx", + mode: "persistent", + cwd: "/workspace/openclaw", + }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "discord", + accountId: "default", + peer: { kind: "channel", id: "222222222222222222" }, + }, + acp: { label: "codex-main" }, + }, + ], + channels: { + discord: { + guilds: { + "111111111111111111": { + channels: { + "222222222222222222": { + requireMention: false, + }, + }, + }, + }, + }, + }, +} +``` + + Catatan: + + - `/acp spawn codex --bind here` mengikat channel atau thread Discord saat ini di tempat dan menjaga pesan selanjutnya tetap dirutekan ke sesi ACP yang sama. + - Itu masih bisa berarti "memulai sesi ACP Codex baru", tetapi tidak membuat thread Discord baru dengan sendirinya. Channel yang ada tetap menjadi permukaan chat. + - Codex mungkin tetap berjalan di `cwd` atau workspace backend miliknya sendiri di disk. Workspace tersebut adalah status runtime, bukan thread Discord. + - Pesan thread dapat mewarisi binding ACP channel induk. + - Di channel atau thread yang terikat, `/new` dan `/reset` mereset sesi ACP yang sama di tempat. + - Thread binding sementara tetap berfungsi dan dapat mengganti resolusi target saat aktif. + - `spawnAcpSessions` hanya diperlukan saat OpenClaw perlu membuat/mengikat child thread melalui `--thread auto|here`. Ini tidak diperlukan untuk `/acp spawn ... --bind here` di channel saat ini. + + Lihat [ACP Agents](/tools/acp-agents) untuk detail perilaku binding. + + + + + Mode notifikasi reaction per-guild: + + - `off` + - `own` (default) + - `all` + - `allowlist` (menggunakan `guilds..users`) + + Event reaction diubah menjadi event sistem dan dilampirkan ke sesi Discord yang dirutekan. + + + + + `ackReaction` mengirim emoji pengakuan saat OpenClaw sedang memproses pesan masuk. + + Urutan resolusi: + + - `channels.discord.accounts..ackReaction` + - `channels.discord.ackReaction` + - `messages.ackReaction` + - fallback emoji identitas agen (`agents.list[].identity.emoji`, jika tidak "👀") + + Catatan: + + - Discord menerima emoji unicode atau nama emoji kustom. + - Gunakan `""` untuk menonaktifkan reaction bagi channel atau akun. + + + + + Penulisan config yang dimulai dari channel diaktifkan secara default. + + Ini memengaruhi alur `/config set|unset` (saat fitur perintah diaktifkan). + + Nonaktifkan: + +```json5 +{ + channels: { + discord: { + configWrites: false, + }, + }, +} +``` + + + + + Rutekan lalu lintas WebSocket gateway Discord dan lookup REST saat startup (ID aplikasi + resolusi allowlist) melalui proxy HTTP(S) dengan `channels.discord.proxy`. + +```json5 +{ + channels: { + discord: { + proxy: "http://proxy.example:8080", + }, + }, +} +``` + + Override per-akun: + +```json5 +{ + channels: { + discord: { + accounts: { + primary: { + proxy: "http://proxy.example:8080", + }, + }, + }, + }, +} +``` + + + + + Aktifkan resolusi PluralKit untuk memetakan pesan yang diproksikan ke identitas anggota sistem: + +```json5 +{ + channels: { + discord: { + pluralkit: { + enabled: true, + token: "pk_live_...", // optional; needed for private systems + }, + }, + }, +} +``` + + Catatan: + + - allowlist dapat menggunakan `pk:` + - nama tampilan anggota dicocokkan berdasarkan nama/slug hanya ketika `channels.discord.dangerouslyAllowNameMatching: true` + - lookup menggunakan ID pesan asli dan dibatasi oleh jendela waktu + - jika lookup gagal, pesan yang diproksikan diperlakukan sebagai pesan bot dan dihapus kecuali `allowBots=true` + + + + + Pembaruan presence diterapkan saat Anda menetapkan status atau field aktivitas, atau saat Anda mengaktifkan auto presence. + + Contoh hanya status: + +```json5 +{ + channels: { + discord: { + status: "idle", + }, + }, +} +``` + + Contoh aktivitas (status kustom adalah jenis aktivitas default): + +```json5 +{ + channels: { + discord: { + activity: "Focus time", + activityType: 4, + }, + }, +} +``` + + Contoh streaming: + +```json5 +{ + channels: { + discord: { + activity: "Live coding", + activityType: 1, + activityUrl: "https://twitch.tv/openclaw", + }, + }, +} +``` + + Peta jenis aktivitas: + + - 0: Playing + - 1: Streaming (memerlukan `activityUrl`) + - 2: Listening + - 3: Watching + - 4: Custom (menggunakan teks aktivitas sebagai status state; emoji opsional) + - 5: Competing + + Contoh auto presence (sinyal kesehatan runtime): + +```json5 +{ + channels: { + discord: { + autoPresence: { + enabled: true, + intervalMs: 30000, + minUpdateIntervalMs: 15000, + exhaustedText: "token exhausted", + }, + }, + }, +} +``` + + Auto presence memetakan ketersediaan runtime ke status Discord: healthy => online, degraded atau unknown => idle, exhausted atau unavailable => dnd. Override teks opsional: + + - `autoPresence.healthyText` + - `autoPresence.degradedText` + - `autoPresence.exhaustedText` (mendukung placeholder `{reason}`) + + + + + Discord mendukung penanganan approval berbasis tombol di DM dan secara opsional dapat memposting prompt approval di channel asal. + + Jalur config: + + - `channels.discord.execApprovals.enabled` + - `channels.discord.execApprovals.approvers` (opsional; fallback ke `commands.ownerAllowFrom` bila memungkinkan) + - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`) + - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` + + Discord mengaktifkan approval exec native secara otomatis ketika `enabled` tidak ditetapkan atau `"auto"` dan setidaknya satu approver dapat di-resolve, baik dari `execApprovals.approvers` maupun dari `commands.ownerAllowFrom`. Discord tidak menyimpulkan approver exec dari channel `allowFrom`, `dm.allowFrom` lama, atau `defaultTo` direct message. Tetapkan `enabled: false` untuk menonaktifkan Discord sebagai klien approval native secara eksplisit. + + Saat `target` adalah `channel` atau `both`, prompt approval terlihat di channel. Hanya approver yang berhasil di-resolve yang dapat menggunakan tombol; pengguna lain menerima penolakan ephemeral. Prompt approval menyertakan teks perintah, jadi aktifkan pengiriman channel hanya di channel tepercaya. Jika ID channel tidak dapat diturunkan dari kunci sesi, OpenClaw fallback ke pengiriman DM. + + Discord juga merender tombol approval bersama yang digunakan oleh channel chat lain. Adaptor Discord native terutama menambahkan routing DM approver dan fanout channel. + Saat tombol-tombol tersebut ada, itulah UX approval utama; OpenClaw + seharusnya hanya menyertakan perintah `/approve` manual saat hasil tool menyatakan + approval chat tidak tersedia atau approval manual adalah satu-satunya jalur. + + Autentikasi Gateway untuk handler ini menggunakan kontrak resolusi kredensial bersama yang sama seperti klien Gateway lain: + + - autentikasi lokal env-first (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` lalu `gateway.auth.*`) + - dalam mode lokal, `gateway.remote.*` dapat digunakan sebagai fallback hanya ketika `gateway.auth.*` tidak ditetapkan; SecretRef lokal yang dikonfigurasi tetapi tidak ter-resolve gagal tertutup + - dukungan mode remote melalui `gateway.remote.*` jika berlaku + - override URL aman terhadap override: override CLI tidak menggunakan ulang kredensial implisit, dan override env hanya menggunakan kredensial env + + Perilaku resolusi approval: + + - ID dengan prefiks `plugin:` di-resolve melalui `plugin.approval.resolve`. + - ID lain di-resolve melalui `exec.approval.resolve`. + - Discord tidak melakukan hop fallback exec-ke-plugin tambahan di sini; prefiks + id menentukan metode gateway yang dipanggil. + + Approval exec kedaluwarsa setelah 30 menit secara default. Jika approval gagal dengan + ID approval yang tidak dikenal, verifikasi resolusi approver, pengaktifan fitur, dan + bahwa jenis id approval yang dikirim cocok dengan permintaan yang tertunda. + + Dokumen terkait: [Exec approvals](/tools/exec-approvals) + + + + +## Tools dan action gates + +Aksi pesan Discord mencakup perpesanan, admin channel, moderasi, presence, dan aksi metadata. + +Contoh inti: + +- perpesanan: `sendMessage`, `readMessages`, `editMessage`, `deleteMessage`, `threadReply` +- reaction: `react`, `reactions`, `emojiList` +- moderasi: `timeout`, `kick`, `ban` +- presence: `setPresence` + +Action gate berada di bawah `channels.discord.actions.*`. + +Perilaku gate default: + +| Action group | Default | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | enabled | +| roles | disabled | +| moderation | disabled | +| presence | disabled | + +## UI Components v2 + +OpenClaw menggunakan Discord components v2 untuk approval exec dan penanda lintas-konteks. Aksi pesan Discord juga dapat menerima `components` untuk UI kustom (lanjutan; memerlukan pembuatan payload komponen melalui discord tool), sementara `embeds` lama tetap tersedia tetapi tidak direkomendasikan. + +- `channels.discord.ui.components.accentColor` menetapkan warna aksen yang digunakan oleh container komponen Discord (hex). +- Tetapkan per akun dengan `channels.discord.accounts..ui.components.accentColor`. +- `embeds` diabaikan saat components v2 ada. + +Contoh: + +```json5 +{ + channels: { + discord: { + ui: { + components: { + accentColor: "#5865F2", + }, + }, + }, + }, +} +``` + +## Channel suara + +OpenClaw dapat bergabung ke channel suara Discord untuk percakapan realtime yang berkelanjutan. Ini terpisah dari lampiran pesan suara. + +Persyaratan: + +- Aktifkan perintah native (`commands.native` atau `channels.discord.commands.native`). +- Konfigurasikan `channels.discord.voice`. +- Bot memerlukan izin Connect + Speak di channel suara target. + +Gunakan perintah native khusus Discord `/vc join|leave|status` untuk mengontrol sesi. Perintah ini menggunakan agen default akun dan mengikuti aturan allowlist serta group policy yang sama seperti perintah Discord lainnya. + +Contoh auto-join: + +```json5 +{ + channels: { + discord: { + voice: { + enabled: true, + autoJoin: [ + { + guildId: "123456789012345678", + channelId: "234567890123456789", + }, + ], + daveEncryption: true, + decryptionFailureTolerance: 24, + tts: { + provider: "openai", + openai: { voice: "alloy" }, + }, + }, + }, + }, +} +``` + +Catatan: + +- `voice.tts` menggantikan `messages.tts` hanya untuk pemutaran suara. +- Giliran transkrip suara menurunkan status owner dari Discord `allowFrom` (atau `dm.allowFrom`); pembicara non-owner tidak dapat mengakses tool khusus owner (misalnya `gateway` dan `cron`). +- Voice diaktifkan secara default; tetapkan `channels.discord.voice.enabled=false` untuk menonaktifkannya. +- `voice.daveEncryption` dan `voice.decryptionFailureTolerance` diteruskan ke opsi join `@discordjs/voice`. +- Default `@discordjs/voice` adalah `daveEncryption=true` dan `decryptionFailureTolerance=24` jika tidak ditetapkan. +- OpenClaw juga memantau kegagalan dekripsi penerimaan dan memulihkan secara otomatis dengan keluar/bergabung kembali ke channel suara setelah kegagalan berulang dalam jangka waktu singkat. +- Jika log penerimaan terus menunjukkan `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, ini mungkin bug receive upstream `@discordjs/voice` yang dilacak di [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). + +## Pesan suara + +Pesan suara Discord menampilkan pratinjau waveform dan memerlukan audio OGG/Opus serta metadata. OpenClaw menghasilkan waveform secara otomatis, tetapi membutuhkan `ffmpeg` dan `ffprobe` yang tersedia pada host gateway untuk memeriksa dan mengonversi file audio. + +Persyaratan dan batasan: + +- Berikan **jalur file lokal** (URL ditolak). +- Hilangkan konten teks (Discord tidak mengizinkan teks + pesan suara dalam payload yang sama). +- Format audio apa pun diterima; OpenClaw mengonversi ke OGG/Opus bila diperlukan. + +Contoh: + +```bash +message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) +``` + +## Troubleshooting + + + + + - aktifkan Message Content Intent + - aktifkan Server Members Intent saat Anda bergantung pada resolusi user/member + - mulai ulang gateway setelah mengubah intents + + + + + + - verifikasi `groupPolicy` + - verifikasi guild allowlist di bawah `channels.discord.guilds` + - jika peta `channels` guild ada, hanya channel yang terdaftar yang diizinkan + - verifikasi perilaku `requireMention` dan pola mention + + Pemeriksaan yang berguna: + +```bash +openclaw doctor +openclaw channels status --probe +openclaw logs --follow +``` + + + + + Penyebab umum: + + - `groupPolicy="allowlist"` tanpa guild/channel allowlist yang cocok + - `requireMention` dikonfigurasi di tempat yang salah (harus di bawah `channels.discord.guilds` atau entri channel) + - pengirim diblokir oleh allowlist `users` guild/channel + + + + + + Log umum: + + - `Listener DiscordMessageListener timed out after 30000ms for event MESSAGE_CREATE` + - `Slow listener detected ...` + - `discord inbound worker timed out after ...` + + Knob anggaran listener: + + - akun tunggal: `channels.discord.eventQueue.listenerTimeout` + - multi-akun: `channels.discord.accounts..eventQueue.listenerTimeout` + + Knob batas waktu run worker: + + - akun tunggal: `channels.discord.inboundWorker.runTimeoutMs` + - multi-akun: `channels.discord.accounts..inboundWorker.runTimeoutMs` + - default: `1800000` (30 menit); tetapkan `0` untuk menonaktifkan + + Baseline yang direkomendasikan: + +```json5 +{ + channels: { + discord: { + accounts: { + default: { + eventQueue: { + listenerTimeout: 120000, + }, + inboundWorker: { + runTimeoutMs: 1800000, + }, + }, + }, + }, + }, +} +``` + + Gunakan `eventQueue.listenerTimeout` untuk penyiapan listener yang lambat dan `inboundWorker.runTimeoutMs` + hanya jika Anda ingin katup pengaman terpisah untuk giliran agen yang diantrikan. + + + + + Pemeriksaan izin `channels status --probe` hanya berfungsi untuk ID channel numerik. + + Jika Anda menggunakan kunci slug, pencocokan runtime masih dapat berfungsi, tetapi probe tidak dapat memverifikasi izin sepenuhnya. + + + + + + - DM dinonaktifkan: `channels.discord.dm.enabled=false` + - kebijakan DM dinonaktifkan: `channels.discord.dmPolicy="disabled"` (lama: `channels.discord.dm.policy`) + - menunggu persetujuan pairing dalam mode `pairing` + + + + + Secara default, pesan yang ditulis bot diabaikan. + + Jika Anda menetapkan `channels.discord.allowBots=true`, gunakan aturan mention dan allowlist yang ketat untuk menghindari perilaku loop. + Lebih baik gunakan `channels.discord.allowBots="mentions"` agar hanya menerima pesan bot yang me-mention bot. + + + + + + - pastikan OpenClaw tetap mutakhir (`openclaw update`) agar logika pemulihan receive suara Discord tersedia + - pastikan `channels.discord.voice.daveEncryption=true` (default) + - mulai dari `channels.discord.voice.decryptionFailureTolerance=24` (default upstream) dan sesuaikan hanya bila perlu + - pantau log untuk: + - `discord voice: DAVE decrypt failures detected` + - `discord voice: repeated decrypt failures; attempting rejoin` + - jika kegagalan berlanjut setelah join ulang otomatis, kumpulkan log dan bandingkan dengan [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) + + + + +## Pointer referensi konfigurasi + +Referensi utama: + +- [Configuration reference - Discord](/gateway/configuration-reference#discord) + +Field Discord dengan sinyal tinggi: + +- startup/auth: `enabled`, `token`, `accounts.*`, `allowBots` +- kebijakan: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` +- perintah: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*` +- event queue: `eventQueue.listenerTimeout` (anggaran listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency` +- inbound worker: `inboundWorker.runTimeoutMs` +- balasan/riwayat: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- pengiriman: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` +- streaming: `streaming` (alias lama: `streamMode`), `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- media/retry: `mediaMaxMb`, `retry` + - `mediaMaxMb` membatasi upload Discord keluar (default: `8MB`) +- actions: `actions.*` +- presence: `activity`, `status`, `activityType`, `activityUrl` +- UI: `ui.components.accentColor` +- fitur: `threadBindings`, top-level `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` + +## Keamanan dan operasi + +- Perlakukan token bot sebagai rahasia (`DISCORD_BOT_TOKEN` lebih disukai di environment yang diawasi). +- Berikan izin Discord dengan hak minimum. +- Jika deploy/status perintah usang, mulai ulang gateway dan periksa kembali dengan `openclaw channels status --probe`. + +## Terkait + +- [Pairing](/channels/pairing) +- [Groups](/channels/groups) +- [Channel routing](/channels/channel-routing) +- [Security](/gateway/security) +- [Multi-agent routing](/concepts/multi-agent) +- [Troubleshooting](/channels/troubleshooting) +- [Slash commands](/tools/slash-commands) diff --git a/docs/id/channels/feishu.md b/docs/id/channels/feishu.md new file mode 100644 index 000000000..61b857521 --- /dev/null +++ b/docs/id/channels/feishu.md @@ -0,0 +1,800 @@ +--- +read_when: + - Anda ingin menghubungkan bot Feishu/Lark + - Anda sedang mengonfigurasi channel Feishu +summary: Ikhtisar, fitur, dan konfigurasi bot Feishu +title: Feishu +x-i18n: + generated_at: "2026-04-05T13:43:35Z" + model: gpt-5.4 + provider: openai + source_hash: 4e39b6dfe3a3aa4ebbdb992975e570e4f1b5e79f3b400a555fc373a0d1889952 + source_path: channels/feishu.md + workflow: 15 +--- + +# Bot Feishu + +Feishu (Lark) adalah platform obrolan tim yang digunakan perusahaan untuk perpesanan dan kolaborasi. Plugin ini menghubungkan OpenClaw ke bot Feishu/Lark menggunakan langganan peristiwa WebSocket milik platform, sehingga pesan dapat diterima tanpa mengekspos URL webhook publik. + +--- + +## Plugin bawaan + +Feishu sudah disertakan secara bawaan dalam rilis OpenClaw saat ini, sehingga tidak +memerlukan instalasi plugin terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan bundel +Feishu, instal secara manual: + +```bash +openclaw plugins install @openclaw/feishu +``` + +--- + +## Mulai cepat + +Ada dua cara untuk menambahkan channel Feishu: + +### Metode 1: onboarding (direkomendasikan) + +Jika Anda baru saja menginstal OpenClaw, jalankan onboarding: + +```bash +openclaw onboard +``` + +Wizard akan memandu Anda melalui: + +1. Membuat aplikasi Feishu dan mengumpulkan kredensial +2. Mengonfigurasi kredensial aplikasi di OpenClaw +3. Menjalankan gateway + +✅ **Setelah konfigurasi**, periksa status gateway: + +- `openclaw gateway status` +- `openclaw logs --follow` + +### Metode 2: penyiapan CLI + +Jika Anda sudah menyelesaikan instalasi awal, tambahkan channel melalui CLI: + +```bash +openclaw channels add +``` + +Pilih **Feishu**, lalu masukkan App ID dan App Secret. + +✅ **Setelah konfigurasi**, kelola gateway: + +- `openclaw gateway status` +- `openclaw gateway restart` +- `openclaw logs --follow` + +--- + +## Langkah 1: Buat aplikasi Feishu + +### 1. Buka Feishu Open Platform + +Kunjungi [Feishu Open Platform](https://open.feishu.cn/app) dan masuk. + +Tenant Lark (global) harus menggunakan [https://open.larksuite.com/app](https://open.larksuite.com/app) dan menetapkan `domain: "lark"` di konfigurasi Feishu. + +### 2. Buat aplikasi + +1. Klik **Create enterprise app** +2. Isi nama + deskripsi aplikasi +3. Pilih ikon aplikasi + +![Create enterprise app](/images/feishu-step2-create-app.png) + +### 3. Salin kredensial + +Dari **Credentials & Basic Info**, salin: + +- **App ID** (format: `cli_xxx`) +- **App Secret** + +❗ **Penting:** jaga kerahasiaan App Secret. + +![Get credentials](/images/feishu-step3-credentials.png) + +### 4. Konfigurasikan izin + +Pada **Permissions**, klik **Batch import** dan tempel: + +```json +{ + "scopes": { + "tenant": [ + "aily:file:read", + "aily:file:write", + "application:application.app_message_stats.overview:readonly", + "application:application:self_manage", + "application:bot.menu:write", + "cardkit:card:read", + "cardkit:card:write", + "contact:user.employee_id:readonly", + "corehr:file:download", + "event:ip_list", + "im:chat.access_event.bot_p2p_chat:read", + "im:chat.members:bot_access", + "im:message", + "im:message.group_at_msg:readonly", + "im:message.p2p_msg:readonly", + "im:message:readonly", + "im:message:send_as_bot", + "im:resource" + ], + "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"] + } +} +``` + +![Configure permissions](/images/feishu-step4-permissions.png) + +### 5. Aktifkan kemampuan bot + +Di **App Capability** > **Bot**: + +1. Aktifkan kemampuan bot +2. Tetapkan nama bot + +![Enable bot capability](/images/feishu-step5-bot-capability.png) + +### 6. Konfigurasikan langganan peristiwa + +⚠️ **Penting:** sebelum menetapkan langganan peristiwa, pastikan: + +1. Anda sudah menjalankan `openclaw channels add` untuk Feishu +2. Gateway sedang berjalan (`openclaw gateway status`) + +Di **Event Subscription**: + +1. Pilih **Use long connection to receive events** (WebSocket) +2. Tambahkan peristiwa: `im.message.receive_v1` +3. (Opsional) Untuk alur kerja komentar Drive, tambahkan juga: `drive.notice.comment_add_v1` + +⚠️ Jika gateway tidak berjalan, penyiapan long-connection mungkin gagal disimpan. + +![Configure event subscription](/images/feishu-step6-event-subscription.png) + +### 7. Publikasikan aplikasi + +1. Buat versi di **Version Management & Release** +2. Kirim untuk peninjauan dan publikasikan +3. Tunggu persetujuan admin (aplikasi enterprise biasanya disetujui otomatis) + +--- + +## Langkah 2: Konfigurasikan OpenClaw + +### Konfigurasikan dengan wizard (direkomendasikan) + +```bash +openclaw channels add +``` + +Pilih **Feishu** dan tempelkan App ID + App Secret Anda. + +### Konfigurasikan melalui file konfigurasi + +Edit `~/.openclaw/openclaw.json`: + +```json5 +{ + channels: { + feishu: { + enabled: true, + dmPolicy: "pairing", + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + name: "My AI assistant", + }, + }, + }, + }, +} +``` + +Jika Anda menggunakan `connectionMode: "webhook"`, tetapkan `verificationToken` dan `encryptKey`. Server webhook Feishu melakukan bind ke `127.0.0.1` secara default; tetapkan `webhookHost` hanya jika Anda memang sengaja memerlukan alamat bind yang berbeda. + +#### Verification Token dan Encrypt Key (mode webhook) + +Saat menggunakan mode webhook, tetapkan `channels.feishu.verificationToken` dan `channels.feishu.encryptKey` di konfigurasi Anda. Untuk mendapatkan nilainya: + +1. Di Feishu Open Platform, buka aplikasi Anda +2. Buka **Development** → **Events & Callbacks** (开发配置 → 事件与回调) +3. Buka tab **Encryption** (加密策略) +4. Salin **Verification Token** dan **Encrypt Key** + +Tangkapan layar di bawah ini menunjukkan tempat menemukan **Verification Token**. **Encrypt Key** tercantum di bagian **Encryption** yang sama. + +![Verification Token location](/images/feishu-verification-token.png) + +### Konfigurasikan melalui variabel lingkungan + +```bash +export FEISHU_APP_ID="cli_xxx" +export FEISHU_APP_SECRET="xxx" +``` + +### Domain Lark (global) + +Jika tenant Anda berada di Lark (internasional), tetapkan domain ke `lark` (atau string domain lengkap). Anda dapat menetapkannya di `channels.feishu.domain` atau per akun (`channels.feishu.accounts..domain`). + +```json5 +{ + channels: { + feishu: { + domain: "lark", + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + }, + }, + }, + }, +} +``` + +### Flag optimasi kuota + +Anda dapat mengurangi penggunaan API Feishu dengan dua flag opsional: + +- `typingIndicator` (default `true`): saat `false`, lewati panggilan reaksi mengetik. +- `resolveSenderNames` (default `true`): saat `false`, lewati panggilan pencarian profil pengirim. + +Tetapkan di level teratas atau per akun: + +```json5 +{ + channels: { + feishu: { + typingIndicator: false, + resolveSenderNames: false, + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + typingIndicator: true, + resolveSenderNames: false, + }, + }, + }, + }, +} +``` + +--- + +## Langkah 3: Jalankan + uji + +### 1. Jalankan gateway + +```bash +openclaw gateway +``` + +### 2. Kirim pesan uji + +Di Feishu, temukan bot Anda dan kirim pesan. + +### 3. Setujui pairing + +Secara default, bot membalas dengan kode pairing. Setujui: + +```bash +openclaw pairing approve feishu +``` + +Setelah disetujui, Anda dapat mengobrol seperti biasa. + +--- + +## Ikhtisar + +- **Channel bot Feishu**: bot Feishu yang dikelola oleh gateway +- **Routing deterministik**: balasan selalu kembali ke Feishu +- **Isolasi sesi**: DM berbagi satu sesi utama; grup diisolasi +- **Koneksi WebSocket**: long connection melalui SDK Feishu, tidak memerlukan URL publik + +--- + +## Kontrol akses + +### Pesan langsung + +- **Default**: `dmPolicy: "pairing"` (pengguna yang tidak dikenal mendapatkan kode pairing) +- **Setujui pairing**: + + ```bash + openclaw pairing list feishu + openclaw pairing approve feishu + ``` + +- **Mode allowlist**: tetapkan `channels.feishu.allowFrom` dengan Open ID yang diizinkan + +### Obrolan grup + +**1. Kebijakan grup** (`channels.feishu.groupPolicy`): + +- `"open"` = izinkan semua orang di grup +- `"allowlist"` = hanya izinkan `groupAllowFrom` +- `"disabled"` = nonaktifkan pesan grup + +Default: `allowlist` + +**2. Persyaratan mention** (`channels.feishu.requireMention`, dapat dioverride melalui `channels.feishu.groups..requireMention`): + +- `true` eksplisit = memerlukan @mention +- `false` eksplisit = merespons tanpa mention +- jika tidak ditetapkan dan `groupPolicy: "open"` = default ke `false` +- jika tidak ditetapkan dan `groupPolicy` bukan `"open"` = default ke `true` + +--- + +## Contoh konfigurasi grup + +### Izinkan semua grup, tanpa @mention wajib (default untuk grup terbuka) + +```json5 +{ + channels: { + feishu: { + groupPolicy: "open", + }, + }, +} +``` + +### Izinkan semua grup, tetapi tetap memerlukan @mention + +```json5 +{ + channels: { + feishu: { + groupPolicy: "open", + requireMention: true, + }, + }, +} +``` + +### Hanya izinkan grup tertentu + +```json5 +{ + channels: { + feishu: { + groupPolicy: "allowlist", + // Feishu group IDs (chat_id) look like: oc_xxx + groupAllowFrom: ["oc_xxx", "oc_yyy"], + }, + }, +} +``` + +### Batasi pengirim mana yang dapat mengirim pesan dalam grup (allowlist pengirim) + +Selain mengizinkan grup itu sendiri, **semua pesan** dalam grup tersebut dibatasi oleh sender `open_id`: hanya pengguna yang tercantum di `groups..allowFrom` yang pesannya diproses; pesan dari anggota lain diabaikan (ini adalah pembatasan penuh di level pengirim, bukan hanya untuk perintah kontrol seperti /reset atau /new). + +```json5 +{ + channels: { + feishu: { + groupPolicy: "allowlist", + groupAllowFrom: ["oc_xxx"], + groups: { + oc_xxx: { + // Feishu user IDs (open_id) look like: ou_xxx + allowFrom: ["ou_user1", "ou_user2"], + }, + }, + }, + }, +} +``` + +--- + + + +## Dapatkan ID grup/pengguna + +### ID grup (chat_id) + +ID grup terlihat seperti `oc_xxx`. + +**Metode 1 (direkomendasikan)** + +1. Jalankan gateway dan lakukan @mention pada bot di grup +2. Jalankan `openclaw logs --follow` dan cari `chat_id` + +**Metode 2** + +Gunakan debugger API Feishu untuk mencantumkan obrolan grup. + +### ID pengguna (open_id) + +ID pengguna terlihat seperti `ou_xxx`. + +**Metode 1 (direkomendasikan)** + +1. Jalankan gateway dan kirim DM ke bot +2. Jalankan `openclaw logs --follow` dan cari `open_id` + +**Metode 2** + +Periksa permintaan pairing untuk Open ID pengguna: + +```bash +openclaw pairing list feishu +``` + +--- + +## Perintah umum + +| Perintah | Deskripsi | +| --------- | ---------------------- | +| `/status` | Tampilkan status bot | +| `/reset` | Reset sesi | +| `/model` | Tampilkan/ganti model | + +> Catatan: Feishu belum mendukung menu perintah native, jadi perintah harus dikirim sebagai teks. + +## Perintah manajemen gateway + +| Perintah | Deskripsi | +| -------------------------- | ----------------------------- | +| `openclaw gateway status` | Tampilkan status gateway | +| `openclaw gateway install` | Instal/jalankan layanan gateway | +| `openclaw gateway stop` | Hentikan layanan gateway | +| `openclaw gateway restart` | Mulai ulang gateway | +| `openclaw logs --follow` | Ikuti log gateway | + +--- + +## Pemecahan masalah + +### Bot tidak merespons di obrolan grup + +1. Pastikan bot sudah ditambahkan ke grup +2. Pastikan Anda melakukan @mention pada bot (perilaku default) +3. Periksa `groupPolicy` tidak disetel ke `"disabled"` +4. Periksa log: `openclaw logs --follow` + +### Bot tidak menerima pesan + +1. Pastikan aplikasi sudah dipublikasikan dan disetujui +2. Pastikan langganan peristiwa menyertakan `im.message.receive_v1` +3. Pastikan **long connection** diaktifkan +4. Pastikan izin aplikasi sudah lengkap +5. Pastikan gateway sedang berjalan: `openclaw gateway status` +6. Periksa log: `openclaw logs --follow` + +### Kebocoran App Secret + +1. Reset App Secret di Feishu Open Platform +2. Perbarui App Secret di konfigurasi Anda +3. Mulai ulang gateway + +### Kegagalan pengiriman pesan + +1. Pastikan aplikasi memiliki izin `im:message:send_as_bot` +2. Pastikan aplikasi sudah dipublikasikan +3. Periksa log untuk error yang lebih rinci + +--- + +## Konfigurasi lanjutan + +### Banyak akun + +```json5 +{ + channels: { + feishu: { + defaultAccount: "main", + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + name: "Primary bot", + }, + backup: { + appId: "cli_yyy", + appSecret: "yyy", + name: "Backup bot", + enabled: false, + }, + }, + }, + }, +} +``` + +`defaultAccount` mengontrol akun Feishu mana yang digunakan ketika API outbound tidak menentukan `accountId` secara eksplisit. + +### Batas pesan + +- `textChunkLimit`: ukuran potongan teks outbound (default: 2000 karakter) +- `mediaMaxMb`: batas upload/download media (default: 30MB) + +### Streaming + +Feishu mendukung balasan streaming melalui kartu interaktif. Saat diaktifkan, bot memperbarui kartu ketika menghasilkan teks. + +```json5 +{ + channels: { + feishu: { + streaming: true, // enable streaming card output (default true) + blockStreaming: true, // enable block-level streaming (default true) + }, + }, +} +``` + +Tetapkan `streaming: false` untuk menunggu balasan lengkap sebelum mengirim. + +### Sesi ACP + +Feishu mendukung ACP untuk: + +- DM +- percakapan topik grup + +ACP Feishu dikendalikan oleh perintah teks. Tidak ada menu slash-command native, jadi gunakan pesan `/acp ...` langsung di percakapan. + +#### Binding ACP persisten + +Gunakan binding ACP bertipe di level teratas untuk menautkan DM atau percakapan topik Feishu ke sesi ACP persisten. + +```json5 +{ + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { + agent: "codex", + backend: "acpx", + mode: "persistent", + cwd: "/workspace/openclaw", + }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "feishu", + accountId: "default", + peer: { kind: "direct", id: "ou_1234567890" }, + }, + }, + { + type: "acp", + agentId: "codex", + match: { + channel: "feishu", + accountId: "default", + peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" }, + }, + acp: { label: "codex-feishu-topic" }, + }, + ], +} +``` + +#### Spawn ACP terikat thread dari obrolan + +Di DM atau percakapan topik Feishu, Anda dapat membuat dan menautkan sesi ACP langsung di tempat: + +```text +/acp spawn codex --thread here +``` + +Catatan: + +- `--thread here` berfungsi untuk DM dan topik Feishu. +- Pesan lanjutan dalam DM/topik yang terikat dirutekan langsung ke sesi ACP tersebut. +- v1 tidak menargetkan obrolan grup umum tanpa topik. + +### Routing multi-agent + +Gunakan `bindings` untuk merutekan DM atau grup Feishu ke agen yang berbeda. + +```json5 +{ + agents: { + list: [ + { id: "main" }, + { + id: "clawd-fan", + workspace: "/home/user/clawd-fan", + agentDir: "/home/user/.openclaw/agents/clawd-fan/agent", + }, + { + id: "clawd-xi", + workspace: "/home/user/clawd-xi", + agentDir: "/home/user/.openclaw/agents/clawd-xi/agent", + }, + ], + }, + bindings: [ + { + agentId: "main", + match: { + channel: "feishu", + peer: { kind: "direct", id: "ou_xxx" }, + }, + }, + { + agentId: "clawd-fan", + match: { + channel: "feishu", + peer: { kind: "direct", id: "ou_yyy" }, + }, + }, + { + agentId: "clawd-xi", + match: { + channel: "feishu", + peer: { kind: "group", id: "oc_zzz" }, + }, + }, + ], +} +``` + +Field routing: + +- `match.channel`: `"feishu"` +- `match.peer.kind`: `"direct"` atau `"group"` +- `match.peer.id`: Open ID pengguna (`ou_xxx`) atau ID grup (`oc_xxx`) + +Lihat [Dapatkan ID grup/pengguna](#get-groupuser-ids) untuk tips pencarian. + +--- + +## Referensi konfigurasi + +Konfigurasi lengkap: [Gateway configuration](/gateway/configuration) + +Opsi utama: + +| Pengaturan | Deskripsi | Default | +| ------------------------------------------------- | --------------------------------------- | ---------------- | +| `channels.feishu.enabled` | Aktifkan/nonaktifkan channel | `true` | +| `channels.feishu.domain` | Domain API (`feishu` atau `lark`) | `feishu` | +| `channels.feishu.connectionMode` | Mode transport peristiwa | `websocket` | +| `channels.feishu.defaultAccount` | ID akun default untuk routing outbound | `default` | +| `channels.feishu.verificationToken` | Wajib untuk mode webhook | - | +| `channels.feishu.encryptKey` | Wajib untuk mode webhook | - | +| `channels.feishu.webhookPath` | Path rute webhook | `/feishu/events` | +| `channels.feishu.webhookHost` | Host bind webhook | `127.0.0.1` | +| `channels.feishu.webhookPort` | Port bind webhook | `3000` | +| `channels.feishu.accounts..appId` | App ID | - | +| `channels.feishu.accounts..appSecret` | App Secret | - | +| `channels.feishu.accounts..domain` | Override domain API per akun | `feishu` | +| `channels.feishu.dmPolicy` | Kebijakan DM | `pairing` | +| `channels.feishu.allowFrom` | Allowlist DM (daftar `open_id`) | - | +| `channels.feishu.groupPolicy` | Kebijakan grup | `allowlist` | +| `channels.feishu.groupAllowFrom` | Allowlist grup | - | +| `channels.feishu.requireMention` | Persyaratan @mention default | conditional | +| `channels.feishu.groups..requireMention` | Override @mention wajib per grup | inherited | +| `channels.feishu.groups..enabled` | Aktifkan grup | `true` | +| `channels.feishu.textChunkLimit` | Ukuran potongan pesan | `2000` | +| `channels.feishu.mediaMaxMb` | Batas ukuran media | `30` | +| `channels.feishu.streaming` | Aktifkan output kartu streaming | `true` | +| `channels.feishu.blockStreaming` | Aktifkan streaming per blok | `true` | + +--- + +## Referensi dmPolicy + +| Nilai | Perilaku | +| ------------- | --------------------------------------------------------------- | +| `"pairing"` | **Default.** Pengguna tak dikenal mendapatkan kode pairing; harus disetujui | +| `"allowlist"` | Hanya pengguna di `allowFrom` yang dapat mengobrol | +| `"open"` | Izinkan semua pengguna (memerlukan `"*"` di `allowFrom`) | +| `"disabled"` | Nonaktifkan DM | + +--- + +## Jenis pesan yang didukung + +### Menerima + +- ✅ Teks +- ✅ Rich text (post) +- ✅ Gambar +- ✅ File +- ✅ Audio +- ✅ Video/media +- ✅ Stiker + +### Mengirim + +- ✅ Teks +- ✅ Gambar +- ✅ File +- ✅ Audio +- ✅ Video/media +- ✅ Kartu interaktif +- ⚠️ Rich text (pemformatan gaya post dan kartu, bukan fitur authoring Feishu yang sewenang-wenang) + +### Thread dan balasan + +- ✅ Balasan inline +- ✅ Balasan topic-thread saat Feishu mengekspos `reply_in_thread` +- ✅ Balasan media tetap sadar thread saat membalas pesan thread/topik + +## Komentar Drive + +Feishu dapat memicu agen ketika seseorang menambahkan komentar pada dokumen Feishu Drive (Docs, Sheets, +dan lain-lain). Agen menerima teks komentar, konteks dokumen, dan thread komentar sehingga dapat +merespons di dalam thread atau melakukan edit dokumen. + +Persyaratan: + +- Berlangganan ke `drive.notice.comment_add_v1` di pengaturan langganan peristiwa aplikasi Feishu Anda + (bersama `im.message.receive_v1` yang sudah ada) +- Tool Drive aktif secara default; nonaktifkan dengan `channels.feishu.tools.drive: false` + +Tool `feishu_drive` mengekspos tindakan komentar berikut: + +| Tindakan | Deskripsi | +| ---------------------- | -------------------------------------- | +| `list_comments` | Daftarkan komentar pada dokumen | +| `list_comment_replies` | Daftarkan balasan dalam thread komentar | +| `add_comment` | Tambahkan komentar tingkat atas baru | +| `reply_comment` | Balas thread komentar yang ada | + +Saat agen menangani peristiwa komentar Drive, agen menerima: + +- teks komentar dan pengirim +- metadata dokumen (judul, jenis, URL) +- konteks thread komentar untuk balasan dalam thread + +Setelah melakukan edit dokumen, agen diarahkan untuk menggunakan `feishu_drive.reply_comment` guna memberi tahu +pemberi komentar lalu mengeluarkan token senyap yang persis `NO_REPLY` / `no_reply` untuk +menghindari pengiriman duplikat. + +## Permukaan tindakan runtime + +Feishu saat ini mengekspos tindakan runtime berikut: + +- `send` +- `read` +- `edit` +- `thread-reply` +- `pin` +- `list-pins` +- `unpin` +- `member-info` +- `channel-info` +- `channel-list` +- `react` dan `reactions` saat reaksi diaktifkan dalam konfigurasi +- tindakan komentar `feishu_drive`: `list_comments`, `list_comment_replies`, `add_comment`, `reply_comment` + +## Terkait + +- [Channels Overview](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention +- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan +- [Security](/gateway/security) — model akses dan penguatan diff --git a/docs/id/channels/googlechat.md b/docs/id/channels/googlechat.md new file mode 100644 index 000000000..f5a83c02e --- /dev/null +++ b/docs/id/channels/googlechat.md @@ -0,0 +1,277 @@ +--- +read_when: + - Sedang mengerjakan fitur channel Google Chat +summary: Status dukungan aplikasi Google Chat, kapabilitas, dan konfigurasi +title: Google Chat +x-i18n: + generated_at: "2026-04-05T13:42:59Z" + model: gpt-5.4 + provider: openai + source_hash: 570894ed798dd0b9ba42806b050927216379a1228fcd2f96de565bc8a4ac7c2c + source_path: channels/googlechat.md + workflow: 15 +--- + +# Google Chat (Chat API) + +Status: siap untuk DM + space melalui webhook Google Chat API (hanya HTTP). + +## Penyiapan cepat (pemula) + +1. Buat project Google Cloud dan aktifkan **Google Chat API**. + - Buka: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials) + - Aktifkan API jika belum diaktifkan. +2. Buat **Service Account**: + - Tekan **Create Credentials** > **Service Account**. + - Beri nama sesuai keinginan Anda (misalnya, `openclaw-chat`). + - Biarkan izin kosong (tekan **Continue**). + - Biarkan principal dengan akses tetap kosong (tekan **Done**). +3. Buat dan unduh **JSON Key**: + - Dalam daftar service account, klik yang baru saja Anda buat. + - Buka tab **Keys**. + - Klik **Add Key** > **Create new key**. + - Pilih **JSON** dan tekan **Create**. +4. Simpan file JSON yang diunduh di host gateway Anda (misalnya, `~/.openclaw/googlechat-service-account.json`). +5. Buat aplikasi Google Chat di [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat): + - Isi **Application info**: + - **App name**: (misalnya `OpenClaw`) + - **Avatar URL**: (misalnya `https://openclaw.ai/logo.png`) + - **Description**: (misalnya `Personal AI Assistant`) + - Aktifkan **Interactive features**. + - Di bawah **Functionality**, centang **Join spaces and group conversations**. + - Di bawah **Connection settings**, pilih **HTTP endpoint URL**. + - Di bawah **Triggers**, pilih **Use a common HTTP endpoint URL for all triggers** dan atur ke URL publik gateway Anda diikuti dengan `/googlechat`. + - _Tip: Jalankan `openclaw status` untuk menemukan URL publik gateway Anda._ + - Di bawah **Visibility**, centang **Make this Chat app available to specific people and groups in <Your Domain>**. + - Masukkan alamat email Anda (misalnya `user@example.com`) ke dalam kotak teks. + - Klik **Save** di bagian bawah. +6. **Aktifkan status aplikasi**: + - Setelah menyimpan, **muat ulang halaman**. + - Cari bagian **App status** (biasanya di dekat atas atau bawah setelah menyimpan). + - Ubah status menjadi **Live - available to users**. + - Klik **Save** lagi. +7. Konfigurasikan OpenClaw dengan path service account + audience webhook: + - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json` + - Atau config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`. +8. Atur jenis + nilai audience webhook (sesuai dengan config aplikasi Chat Anda). +9. Mulai gateway. Google Chat akan mengirim POST ke path webhook Anda. + +## Tambahkan ke Google Chat + +Setelah gateway berjalan dan email Anda ditambahkan ke daftar visibilitas: + +1. Buka [Google Chat](https://chat.google.com/). +2. Klik ikon **+** (plus) di samping **Direct Messages**. +3. Di bilah pencarian (tempat Anda biasanya menambahkan orang), ketik **App name** yang Anda konfigurasi di Google Cloud Console. + - **Catatan**: Bot _tidak_ akan muncul dalam daftar penelusuran "Marketplace" karena ini adalah aplikasi privat. Anda harus mencarinya berdasarkan nama. +4. Pilih bot Anda dari hasil pencarian. +5. Klik **Add** atau **Chat** untuk memulai percakapan 1:1. +6. Kirim "Hello" untuk memicu asisten! + +## URL publik (khusus webhook) + +Webhook Google Chat memerlukan endpoint HTTPS publik. Demi keamanan, **hanya ekspos path `/googlechat`** ke internet. Simpan dashboard OpenClaw dan endpoint sensitif lainnya di jaringan privat Anda. + +### Opsi A: Tailscale Funnel (Direkomendasikan) + +Gunakan Tailscale Serve untuk dashboard privat dan Funnel untuk path webhook publik. Ini menjaga `/` tetap privat sambil hanya mengekspos `/googlechat`. + +1. **Periksa alamat tempat gateway Anda terikat:** + + ```bash + ss -tlnp | grep 18789 + ``` + + Catat alamat IP (misalnya `127.0.0.1`, `0.0.0.0`, atau IP Tailscale Anda seperti `100.x.x.x`). + +2. **Ekspos dashboard hanya ke tailnet (port 8443):** + + ```bash + # Jika terikat ke localhost (127.0.0.1 atau 0.0.0.0): + tailscale serve --bg --https 8443 http://127.0.0.1:18789 + + # Jika terikat hanya ke IP Tailscale (misalnya, 100.106.161.80): + tailscale serve --bg --https 8443 http://100.106.161.80:18789 + ``` + +3. **Ekspos hanya path webhook secara publik:** + + ```bash + # Jika terikat ke localhost (127.0.0.1 atau 0.0.0.0): + tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat + + # Jika terikat hanya ke IP Tailscale (misalnya, 100.106.161.80): + tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat + ``` + +4. **Otorisasi node untuk akses Funnel:** + Jika diminta, kunjungi URL otorisasi yang ditampilkan dalam output untuk mengaktifkan Funnel bagi node ini dalam kebijakan tailnet Anda. + +5. **Verifikasi konfigurasi:** + + ```bash + tailscale serve status + tailscale funnel status + ``` + +URL webhook publik Anda akan menjadi: +`https://..ts.net/googlechat` + +Dashboard privat Anda tetap hanya untuk tailnet: +`https://..ts.net:8443/` + +Gunakan URL publik (tanpa `:8443`) dalam config aplikasi Google Chat. + +> Catatan: Konfigurasi ini tetap ada setelah reboot. Untuk menghapusnya nanti, jalankan `tailscale funnel reset` dan `tailscale serve reset`. + +### Opsi B: Reverse Proxy (Caddy) + +Jika Anda menggunakan reverse proxy seperti Caddy, proksikan hanya path spesifik: + +```caddy +your-domain.com { + reverse_proxy /googlechat* localhost:18789 +} +``` + +Dengan config ini, setiap permintaan ke `your-domain.com/` akan diabaikan atau mengembalikan 404, sedangkan `your-domain.com/googlechat` akan dirutekan dengan aman ke OpenClaw. + +### Opsi C: Cloudflare Tunnel + +Konfigurasikan aturan ingress tunnel Anda agar hanya merutekan path webhook: + +- **Path**: `/googlechat` -> `http://localhost:18789/googlechat` +- **Default Rule**: HTTP 404 (Not Found) + +## Cara kerjanya + +1. Google Chat mengirim webhook POST ke gateway. Setiap permintaan menyertakan header `Authorization: Bearer `. + - OpenClaw memverifikasi autentikasi bearer sebelum membaca/mem-parse body webhook penuh saat header tersebut ada. + - Permintaan Google Workspace Add-on yang membawa `authorizationEventObject.systemIdToken` di dalam body didukung melalui anggaran body pra-autentikasi yang lebih ketat. +2. OpenClaw memverifikasi token terhadap `audienceType` + `audience` yang dikonfigurasi: + - `audienceType: "app-url"` → audience adalah URL webhook HTTPS Anda. + - `audienceType: "project-number"` → audience adalah nomor project Cloud. +3. Pesan dirutekan berdasarkan space: + - DM menggunakan kunci sesi `agent::googlechat:direct:`. + - Space menggunakan kunci sesi `agent::googlechat:group:`. +4. Akses DM menggunakan pairing secara default. Pengirim yang tidak dikenal menerima kode pairing; setujui dengan: + - `openclaw pairing approve googlechat ` +5. Space grup memerlukan @-mention secara default. Gunakan `botUser` jika deteksi mention memerlukan nama pengguna aplikasi. + +## Target + +Gunakan identifier ini untuk pengiriman dan allowlist: + +- Direct messages: `users/` (direkomendasikan). +- Email mentah `name@example.com` dapat berubah dan hanya digunakan untuk pencocokan allowlist direct saat `channels.googlechat.dangerouslyAllowNameMatching: true`. +- Deprecated: `users/` diperlakukan sebagai user id, bukan allowlist email. +- Spaces: `spaces/`. + +## Sorotan config + +```json5 +{ + channels: { + googlechat: { + enabled: true, + serviceAccountFile: "/path/to/service-account.json", + // atau serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" } + audienceType: "app-url", + audience: "https://gateway.example.com/googlechat", + webhookPath: "/googlechat", + botUser: "users/1234567890", // opsional; membantu deteksi mention + dm: { + policy: "pairing", + allowFrom: ["users/1234567890"], + }, + groupPolicy: "allowlist", + groups: { + "spaces/AAAA": { + allow: true, + requireMention: true, + users: ["users/1234567890"], + systemPrompt: "Short answers only.", + }, + }, + actions: { reactions: true }, + typingIndicator: "message", + mediaMaxMb: 20, + }, + }, +} +``` + +Catatan: + +- Kredensial service account juga dapat diberikan secara inline dengan `serviceAccount` (string JSON). +- `serviceAccountRef` juga didukung (SecretRef env/file), termasuk ref per akun di bawah `channels.googlechat.accounts..serviceAccountRef`. +- Path webhook default adalah `/googlechat` jika `webhookPath` tidak diatur. +- `dangerouslyAllowNameMatching` mengaktifkan kembali pencocokan principal email yang dapat berubah untuk allowlist (mode kompatibilitas break-glass). +- Reactions tersedia melalui alat `reactions` dan `channels action` saat `actions.reactions` diaktifkan. +- Message actions mengekspos `send` untuk teks dan `upload-file` untuk pengiriman lampiran eksplisit. `upload-file` menerima `media` / `filePath` / `path` ditambah `message`, `filename`, dan penargetan thread opsional. +- `typingIndicator` mendukung `none`, `message` (default), dan `reaction` (reaction memerlukan OAuth pengguna). +- Lampiran diunduh melalui Chat API dan disimpan di pipeline media (ukuran dibatasi oleh `mediaMaxMb`). + +Detail referensi rahasia: [Secrets Management](/gateway/secrets). + +## Pemecahan masalah + +### 405 Method Not Allowed + +Jika Google Cloud Logs Explorer menampilkan error seperti: + +``` +status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed +``` + +Ini berarti handler webhook tidak terdaftar. Penyebab umum: + +1. **Channel tidak dikonfigurasi**: Bagian `channels.googlechat` tidak ada dari config Anda. Verifikasi dengan: + + ```bash + openclaw config get channels.googlechat + ``` + + Jika mengembalikan "Config path not found", tambahkan konfigurasi tersebut (lihat [Sorotan config](#config-highlights)). + +2. **Plugin tidak diaktifkan**: Periksa status plugin: + + ```bash + openclaw plugins list | grep googlechat + ``` + + Jika menampilkan "disabled", tambahkan `plugins.entries.googlechat.enabled: true` ke config Anda. + +3. **Gateway belum dimulai ulang**: Setelah menambahkan config, mulai ulang gateway: + + ```bash + openclaw gateway restart + ``` + +Verifikasi bahwa channel berjalan: + +```bash +openclaw channels status +# Harus menampilkan: Google Chat default: enabled, configured, ... +``` + +### Masalah lain + +- Periksa `openclaw channels status --probe` untuk error autentikasi atau config audience yang hilang. +- Jika tidak ada pesan yang masuk, konfirmasikan URL webhook + langganan peristiwa aplikasi Chat. +- Jika pembatasan mention memblokir balasan, atur `botUser` ke nama resource pengguna aplikasi dan verifikasi `requireMention`. +- Gunakan `openclaw logs --follow` saat mengirim pesan uji untuk melihat apakah permintaan mencapai gateway. + +Dokumen terkait: + +- [Konfigurasi gateway](/gateway/configuration) +- [Keamanan](/gateway/security) +- [Reactions](/tools/reactions) + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention +- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan penguatan diff --git a/docs/id/channels/group-messages.md b/docs/id/channels/group-messages.md new file mode 100644 index 000000000..41d034204 --- /dev/null +++ b/docs/id/channels/group-messages.md @@ -0,0 +1,91 @@ +--- +read_when: + - Mengubah aturan pesan grup atau mention +summary: Perilaku dan konfigurasi untuk penanganan pesan grup WhatsApp (mentionPatterns dibagikan di seluruh surface) +title: Pesan Grup +x-i18n: + generated_at: "2026-04-05T13:42:55Z" + model: gpt-5.4 + provider: openai + source_hash: 2543be5bc4c6f188f955df580a6fef585ecbfc1be36ade5d34b1a9157e021bc5 + source_path: channels/group-messages.md + workflow: 15 +--- + +# Pesan grup (channel web WhatsApp) + +Tujuan: membiarkan Clawd berada di grup WhatsApp, aktif hanya saat dipanggil, dan menjaga thread itu tetap terpisah dari sesi DM pribadi. + +Catatan: `agents.list[].groupChat.mentionPatterns` sekarang juga digunakan oleh Telegram/Discord/Slack/iMessage; dokumen ini berfokus pada perilaku khusus WhatsApp. Untuk pengaturan multi-agen, tetapkan `agents.list[].groupChat.mentionPatterns` per agen (atau gunakan `messages.groupChat.mentionPatterns` sebagai fallback global). + +## Implementasi saat ini (2025-12-03) + +- Mode aktivasi: `mention` (default) atau `always`. `mention` memerlukan panggilan (mention WhatsApp @ yang nyata melalui `mentionedJids`, pola regex aman, atau E.164 bot di mana pun dalam teks). `always` membangunkan agen pada setiap pesan tetapi agen seharusnya hanya membalas saat dapat memberi nilai yang bermakna; jika tidak, agen mengembalikan token senyap yang persis `NO_REPLY` / `no_reply`. Default dapat ditetapkan di config (`channels.whatsapp.groups`) dan dioverride per grup melalui `/activation`. Saat `channels.whatsapp.groups` ditetapkan, itu juga bertindak sebagai allowlist grup (sertakan `"*"` untuk mengizinkan semua). +- Kebijakan grup: `channels.whatsapp.groupPolicy` mengontrol apakah pesan grup diterima (`open|disabled|allowlist`). `allowlist` menggunakan `channels.whatsapp.groupAllowFrom` (fallback: `channels.whatsapp.allowFrom` yang eksplisit). Default adalah `allowlist` (diblokir sampai Anda menambahkan pengirim). +- Sesi per grup: kunci sesi berbentuk `agent::whatsapp:group:` sehingga perintah seperti `/verbose on` atau `/think high` (dikirim sebagai pesan mandiri) dibatasi ke grup tersebut; status DM pribadi tidak tersentuh. Heartbeat dilewati untuk thread grup. +- Injeksi konteks: pesan grup **pending-only** (default 50) yang _tidak_ memicu eksekusi diawali di bawah `[Chat messages since your last reply - for context]`, dengan baris pemicu di bawah `[Current message - respond to this]`. Pesan yang sudah ada di sesi tidak diinjeksi ulang. +- Penampilan pengirim: setiap batch grup sekarang diakhiri dengan `[from: Sender Name (+E164)]` sehingga Pi tahu siapa yang sedang berbicara. +- Ephemeral/view-once: kami membuka bungkusnya sebelum mengekstrak teks/mention, sehingga panggilan di dalamnya tetap memicu. +- Prompt sistem grup: pada giliran pertama sesi grup (dan setiap kali `/activation` mengubah mode) kami menyuntikkan uraian singkat ke prompt sistem seperti `You are replying inside the WhatsApp group "". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` Jika metadata tidak tersedia, kami tetap memberi tahu agen bahwa ini adalah obrolan grup. + +## Contoh config (WhatsApp) + +Tambahkan blok `groupChat` ke `~/.openclaw/openclaw.json` agar panggilan nama tampilan berfungsi bahkan saat WhatsApp menghapus `@` visual dari isi teks: + +```json5 +{ + channels: { + whatsapp: { + groups: { + "*": { requireMention: true }, + }, + }, + }, + agents: { + list: [ + { + id: "main", + groupChat: { + historyLimit: 50, + mentionPatterns: ["@?openclaw", "\\+?15555550123"], + }, + }, + ], + }, +} +``` + +Catatan: + +- Regex ini tidak peka huruf besar/kecil dan menggunakan guardrail safe-regex yang sama seperti surface regex config lainnya; pola yang tidak valid dan nested repetition yang tidak aman diabaikan. +- WhatsApp tetap mengirim mention kanonis melalui `mentionedJids` saat seseorang mengetuk kontak, jadi fallback nomor jarang diperlukan tetapi berguna sebagai jaring pengaman. + +### Perintah aktivasi (khusus pemilik) + +Gunakan perintah obrolan grup: + +- `/activation mention` +- `/activation always` + +Hanya nomor pemilik (dari `channels.whatsapp.allowFrom`, atau E.164 bot itu sendiri jika tidak disetel) yang dapat mengubah ini. Kirim `/status` sebagai pesan mandiri di grup untuk melihat mode aktivasi saat ini. + +## Cara menggunakan + +1. Tambahkan akun WhatsApp Anda (yang menjalankan OpenClaw) ke grup. +2. Ucapkan `@openclaw …` (atau sertakan nomornya). Hanya pengirim di allowlist yang dapat memicunya kecuali Anda menetapkan `groupPolicy: "open"`. +3. Prompt agen akan menyertakan konteks grup terbaru plus penanda `[from: …]` di bagian akhir sehingga agen dapat menyapa orang yang tepat. +4. Direktif tingkat sesi (`/verbose on`, `/think high`, `/new` atau `/reset`, `/compact`) hanya berlaku untuk sesi grup itu; kirim sebagai pesan mandiri agar terdaftar. Sesi DM pribadi Anda tetap independen. + +## Pengujian / verifikasi + +- Smoke manual: + - Kirim panggilan `@openclaw` di grup dan konfirmasikan ada balasan yang merujuk nama pengirim. + - Kirim panggilan kedua dan verifikasi blok riwayat disertakan lalu dibersihkan pada giliran berikutnya. +- Periksa log gateway (jalankan dengan `--verbose`) untuk melihat entri `inbound web message` yang menampilkan `from: ` dan sufiks `[from: …]`. + +## Hal-hal yang perlu diperhatikan + +- Heartbeat sengaja dilewati untuk grup agar tidak menimbulkan broadcast yang berisik. +- Penekanan echo menggunakan string batch gabungan; jika Anda mengirim teks identik dua kali tanpa mention, hanya yang pertama akan mendapat respons. +- Entri penyimpanan sesi akan muncul sebagai `agent::whatsapp:group:` di penyimpanan sesi (default `~/.openclaw/agents//sessions/sessions.json`); entri yang hilang hanya berarti grup tersebut belum memicu eksekusi. +- Indikator mengetik di grup mengikuti `agents.defaults.typingMode` (default: `message` saat tidak di-mention). diff --git a/docs/id/channels/groups.md b/docs/id/channels/groups.md new file mode 100644 index 000000000..8b7d8cf5a --- /dev/null +++ b/docs/id/channels/groups.md @@ -0,0 +1,417 @@ +--- +read_when: + - Mengubah perilaku obrolan grup atau gating mention +summary: Perilaku obrolan grup di berbagai surface (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo) +title: Grup +x-i18n: + generated_at: "2026-04-05T13:43:23Z" + model: gpt-5.4 + provider: openai + source_hash: 39d066e0542b468c6f8b384b463e2316590ea09a00ecb2065053e1e2ce55bd5f + source_path: channels/groups.md + workflow: 15 +--- + +# Grup + +OpenClaw memperlakukan obrolan grup secara konsisten di berbagai surface: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo. + +## Pengantar untuk pemula (2 menit) + +OpenClaw “hidup” di akun pesan Anda sendiri. Tidak ada pengguna bot WhatsApp terpisah. +Jika **Anda** berada di dalam grup, OpenClaw dapat melihat grup tersebut dan merespons di sana. + +Perilaku default: + +- Grup dibatasi (`groupPolicy: "allowlist"`). +- Balasan memerlukan mention kecuali Anda secara eksplisit menonaktifkan gating mention. + +Artinya: pengirim yang ada dalam allowlist dapat memicu OpenClaw dengan menyebutnya. + +> TL;DR +> +> - **Akses DM** dikendalikan oleh `*.allowFrom`. +> - **Akses grup** dikendalikan oleh `*.groupPolicy` + allowlist (`*.groups`, `*.groupAllowFrom`). +> - **Pemicu balasan** dikendalikan oleh gating mention (`requireMention`, `/activation`). + +Alur singkat (apa yang terjadi pada pesan grup): + +``` +groupPolicy? disabled -> drop +groupPolicy? allowlist -> group allowed? no -> drop +requireMention? yes -> mentioned? no -> store for context only +otherwise -> reply +``` + +## Visibilitas konteks dan allowlist + +Dua kontrol yang berbeda terlibat dalam keamanan grup: + +- **Otorisasi pemicu**: siapa yang dapat memicu agen (`groupPolicy`, `groups`, `groupAllowFrom`, allowlist khusus channel). +- **Visibilitas konteks**: konteks tambahan apa yang disuntikkan ke model (teks balasan, kutipan, riwayat thread, metadata forward). + +Secara default, OpenClaw memprioritaskan perilaku chat normal dan menjaga konteks sebagian besar tetap seperti diterima. Artinya, allowlist terutama menentukan siapa yang dapat memicu tindakan, bukan batas redaksi universal untuk setiap kutipan atau potongan riwayat. + +Perilaku saat ini bersifat spesifik per channel: + +- Beberapa channel sudah menerapkan pemfilteran berbasis pengirim untuk konteks tambahan pada jalur tertentu (misalnya seeding thread Slack, lookup balasan/thread Matrix). +- Channel lain masih meneruskan konteks kutipan/balasan/forward sebagaimana diterima. + +Arah hardening (direncanakan): + +- `contextVisibility: "all"` (default) mempertahankan perilaku saat ini sebagaimana diterima. +- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang ada dalam allowlist. +- `contextVisibility: "allowlist_quote"` adalah `allowlist` ditambah satu pengecualian kutipan/balasan yang eksplisit. + +Sampai model hardening ini diimplementasikan secara konsisten di seluruh channel, perkirakan akan ada perbedaan antar surface. + +![Alur pesan grup](/images/groups-flow.svg) + +Jika Anda ingin... + +| Tujuan | Yang harus disetel | +| ------------------------------------------- | ----------------------------------------------------------- | +| Izinkan semua grup tetapi hanya balas pada @mention | `groups: { "*": { requireMention: true } }` | +| Nonaktifkan semua balasan grup | `groupPolicy: "disabled"` | +| Hanya grup tertentu | `groups: { "": { ... } }` (tanpa key `"*"` ) | +| Hanya Anda yang dapat memicu di grup | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` | + +## Session key + +- Sesi grup menggunakan session key `agent:::group:` (room/channel menggunakan `agent:::channel:`). +- Topik forum Telegram menambahkan `:topic:` ke id grup sehingga setiap topik memiliki sesinya sendiri. +- Obrolan langsung menggunakan sesi utama (atau per pengirim jika dikonfigurasi). +- Heartbeat dilewati untuk sesi grup. + + + +## Pola: DM pribadi + grup publik (agen tunggal) + +Ya — ini bekerja dengan baik jika trafik “pribadi” Anda adalah **DM** dan trafik “publik” Anda adalah **grup**. + +Alasannya: dalam mode agen tunggal, DM biasanya masuk ke session key **utama** (`agent:main:main`), sementara grup selalu menggunakan session key **non-utama** (`agent:main::group:`). Jika Anda mengaktifkan sandboxing dengan `mode: "non-main"`, sesi grup tersebut berjalan di Docker sementara sesi DM utama Anda tetap berjalan di host. + +Ini memberi Anda satu “otak” agen (workspace + memori bersama), tetapi dua postur eksekusi: + +- **DM**: alat penuh (host) +- **Grup**: sandbox + alat terbatas (Docker) + +> Jika Anda memerlukan workspace/persona yang benar-benar terpisah (“pribadi” dan “publik” sama sekali tidak boleh bercampur), gunakan agen kedua + binding. Lihat [Multi-Agent Routing](/concepts/multi-agent). + +Contoh (DM di host, grup di-sandbox + alat khusus messaging): + +```json5 +{ + agents: { + defaults: { + sandbox: { + mode: "non-main", // groups/channels are non-main -> sandboxed + scope: "session", // strongest isolation (one container per group/channel) + workspaceAccess: "none", + }, + }, + }, + tools: { + sandbox: { + tools: { + // If allow is non-empty, everything else is blocked (deny still wins). + allow: ["group:messaging", "group:sessions"], + deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"], + }, + }, + }, +} +``` + +Ingin “grup hanya bisa melihat folder X” alih-alih “tidak ada akses host”? Pertahankan `workspaceAccess: "none"` dan mount hanya path yang ada dalam allowlist ke sandbox: + +```json5 +{ + agents: { + defaults: { + sandbox: { + mode: "non-main", + scope: "session", + workspaceAccess: "none", + docker: { + binds: [ + // hostPath:containerPath:mode + "/home/user/FriendsShared:/data:ro", + ], + }, + }, + }, + }, +} +``` + +Terkait: + +- Key konfigurasi dan default: [Konfigurasi Gateway](/gateway/configuration-reference#agentsdefaultssandbox) +- Men-debug mengapa suatu alat diblokir: [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) +- Detail bind mount: [Sandboxing](/gateway/sandboxing#custom-bind-mounts) + +## Label tampilan + +- Label UI menggunakan `displayName` bila tersedia, diformat sebagai `:`. +- `#room` dicadangkan untuk room/channel; obrolan grup menggunakan `g-` (huruf kecil, spasi -> `-`, pertahankan `#@+._-`). + +## Kebijakan grup + +Kendalikan cara pesan grup/room ditangani per channel: + +```json5 +{ + channels: { + whatsapp: { + groupPolicy: "disabled", // "open" | "disabled" | "allowlist" + groupAllowFrom: ["+15551234567"], + }, + telegram: { + groupPolicy: "disabled", + groupAllowFrom: ["123456789"], // numeric Telegram user id (wizard can resolve @username) + }, + signal: { + groupPolicy: "disabled", + groupAllowFrom: ["+15551234567"], + }, + imessage: { + groupPolicy: "disabled", + groupAllowFrom: ["chat_id:123"], + }, + msteams: { + groupPolicy: "disabled", + groupAllowFrom: ["user@org.com"], + }, + discord: { + groupPolicy: "allowlist", + guilds: { + GUILD_ID: { channels: { help: { allow: true } } }, + }, + }, + slack: { + groupPolicy: "allowlist", + channels: { "#general": { allow: true } }, + }, + matrix: { + groupPolicy: "allowlist", + groupAllowFrom: ["@owner:example.org"], + groups: { + "!roomId:example.org": { allow: true }, + "#alias:example.org": { allow: true }, + }, + }, + }, +} +``` + +| Kebijakan | Perilaku | +| ------------- | ------------------------------------------------------------ | +| `"open"` | Grup melewati allowlist; gating mention tetap berlaku. | +| `"disabled"` | Blokir semua pesan grup sepenuhnya. | +| `"allowlist"` | Hanya izinkan grup/room yang cocok dengan allowlist yang dikonfigurasi. | + +Catatan: + +- `groupPolicy` terpisah dari gating mention (yang memerlukan @mention). +- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: gunakan `groupAllowFrom` (fallback: `allowFrom` eksplisit). +- Persetujuan pairing DM (entri penyimpanan `*-allowFrom`) hanya berlaku untuk akses DM; otorisasi pengirim grup tetap eksplisit ke allowlist grup. +- Discord: allowlist menggunakan `channels.discord.guilds..channels`. +- Slack: allowlist menggunakan `channels.slack.channels`. +- Matrix: allowlist menggunakan `channels.matrix.groups`. Pilih room ID atau alias; lookup nama joined-room bersifat best-effort, dan nama yang tidak dapat diselesaikan diabaikan saat runtime. Gunakan `channels.matrix.groupAllowFrom` untuk membatasi pengirim; allowlist `users` per room juga didukung. +- Group DM dikendalikan secara terpisah (`channels.discord.dm.*`, `channels.slack.dm.*`). +- Allowlist Telegram dapat mencocokkan user ID (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) atau username (`"@alice"` atau `"alice"`); prefiks tidak peka huruf besar/kecil. +- Default adalah `groupPolicy: "allowlist"`; jika allowlist grup Anda kosong, pesan grup diblokir. +- Keamanan runtime: saat blok provider sama sekali tidak ada (`channels.` tidak ada), kebijakan grup fallback ke mode fail-closed (biasanya `allowlist`) alih-alih mewarisi `channels.defaults.groupPolicy`. + +Model mental singkat (urutan evaluasi untuk pesan grup): + +1. `groupPolicy` (open/disabled/allowlist) +2. allowlist grup (`*.groups`, `*.groupAllowFrom`, allowlist khusus channel) +3. gating mention (`requireMention`, `/activation`) + +## Gating mention (default) + +Pesan grup memerlukan mention kecuali ditimpa per grup. Default berada per subsistem di bawah `*.groups."*"`. + +Membalas pesan bot dihitung sebagai mention implisit (saat channel mendukung metadata balasan). Ini berlaku untuk Telegram, WhatsApp, Slack, Discord, dan Microsoft Teams. + +```json5 +{ + channels: { + whatsapp: { + groups: { + "*": { requireMention: true }, + "123@g.us": { requireMention: false }, + }, + }, + telegram: { + groups: { + "*": { requireMention: true }, + "123456789": { requireMention: false }, + }, + }, + imessage: { + groups: { + "*": { requireMention: true }, + "123": { requireMention: false }, + }, + }, + }, + agents: { + list: [ + { + id: "main", + groupChat: { + mentionPatterns: ["@openclaw", "openclaw", "\\+15555550123"], + historyLimit: 50, + }, + }, + ], + }, +} +``` + +Catatan: + +- `mentionPatterns` adalah pola regex aman yang tidak peka huruf besar/kecil; pola yang tidak valid dan bentuk nested-repetition yang tidak aman akan diabaikan. +- Surface yang menyediakan mention eksplisit tetap lolos; pola hanyalah fallback. +- Override per agen: `agents.list[].groupChat.mentionPatterns` (berguna saat beberapa agen berbagi satu grup). +- Gating mention hanya diterapkan ketika deteksi mention memungkinkan (mention native atau `mentionPatterns` dikonfigurasi). +- Default Discord berada di `channels.discord.guilds."*"` (dapat ditimpa per guild/channel). +- Konteks riwayat grup dibungkus secara seragam di seluruh channel dan hanya **pending-only** (pesan yang dilewati karena gating mention); gunakan `messages.groupChat.historyLimit` untuk default global dan `channels..historyLimit` (atau `channels..accounts.*.historyLimit`) untuk override. Set `0` untuk menonaktifkan. + +## Pembatasan alat grup/channel (opsional) + +Beberapa config channel mendukung pembatasan alat mana yang tersedia **di dalam grup/room/channel tertentu**. + +- `tools`: izinkan/tolak alat untuk seluruh grup. +- `toolsBySender`: override per pengirim di dalam grup. + Gunakan prefiks key eksplisit: + `id:`, `e164:`, `username:`, `name:`, dan wildcard `"*"`. + Key lama tanpa prefiks masih diterima dan hanya dicocokkan sebagai `id:`. + +Urutan resolusi (yang paling spesifik menang): + +1. kecocokan `toolsBySender` grup/channel +2. `tools` grup/channel +3. kecocokan `toolsBySender` default (`"*"`) +4. `tools` default (`"*"`) + +Contoh (Telegram): + +```json5 +{ + channels: { + telegram: { + groups: { + "*": { tools: { deny: ["exec"] } }, + "-1001234567890": { + tools: { deny: ["exec", "read", "write"] }, + toolsBySender: { + "id:123456789": { alsoAllow: ["exec"] }, + }, + }, + }, + }, + }, +} +``` + +Catatan: + +- Pembatasan alat grup/channel diterapkan sebagai tambahan terhadap kebijakan alat global/agen (deny tetap menang). +- Beberapa channel menggunakan nesting yang berbeda untuk room/channel (misalnya Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`). + +## Allowlist grup + +Saat `channels.whatsapp.groups`, `channels.telegram.groups`, atau `channels.imessage.groups` dikonfigurasi, key-nya bertindak sebagai allowlist grup. Gunakan `"*"` untuk mengizinkan semua grup sambil tetap mengatur perilaku mention default. + +Kebingungan umum: persetujuan pairing DM tidak sama dengan otorisasi grup. +Untuk channel yang mendukung pairing DM, penyimpanan pairing hanya membuka DM. Perintah grup tetap memerlukan otorisasi pengirim grup yang eksplisit dari allowlist config seperti `groupAllowFrom` atau fallback config terdokumentasi untuk channel tersebut. + +Maksud umum (salin/tempel): + +1. Nonaktifkan semua balasan grup + +```json5 +{ + channels: { whatsapp: { groupPolicy: "disabled" } }, +} +``` + +2. Izinkan hanya grup tertentu (WhatsApp) + +```json5 +{ + channels: { + whatsapp: { + groups: { + "123@g.us": { requireMention: true }, + "456@g.us": { requireMention: false }, + }, + }, + }, +} +``` + +3. Izinkan semua grup tetapi wajib mention (eksplisit) + +```json5 +{ + channels: { + whatsapp: { + groups: { "*": { requireMention: true } }, + }, + }, +} +``` + +4. Hanya pemilik yang dapat memicu di grup (WhatsApp) + +```json5 +{ + channels: { + whatsapp: { + groupPolicy: "allowlist", + groupAllowFrom: ["+15551234567"], + groups: { "*": { requireMention: true } }, + }, + }, +} +``` + +## Aktivasi (khusus pemilik) + +Pemilik grup dapat mengubah aktivasi per grup: + +- `/activation mention` +- `/activation always` + +Pemilik ditentukan oleh `channels.whatsapp.allowFrom` (atau E.164 milik bot sendiri jika tidak disetel). Kirim perintah sebagai pesan mandiri. Surface lain saat ini mengabaikan `/activation`. + +## Field konteks + +Payload masuk grup menetapkan: + +- `ChatType=group` +- `GroupSubject` (jika diketahui) +- `GroupMembers` (jika diketahui) +- `WasMentioned` (hasil gating mention) +- Topik forum Telegram juga menyertakan `MessageThreadId` dan `IsForum`. + +Catatan khusus channel: + +- BlueBubbles secara opsional dapat memperkaya peserta grup macOS tanpa nama dari database Kontak lokal sebelum mengisi `GroupMembers`. Ini nonaktif secara default dan hanya berjalan setelah gating grup normal lolos. + +System prompt agen menyertakan pengantar grup pada giliran pertama dari sesi grup baru. Ini mengingatkan model agar merespons seperti manusia, menghindari tabel Markdown, dan menghindari mengetik urutan literal `\n`. + +## Hal spesifik iMessage + +- Pilih `chat_id:` saat routing atau membuat allowlist. +- Daftar obrolan: `imsg chats --limit 20`. +- Balasan grup selalu kembali ke `chat_id` yang sama. + +## Hal spesifik WhatsApp + +Lihat [Pesan grup](/channels/group-messages) untuk perilaku khusus WhatsApp (injeksi riwayat, detail penanganan mention). diff --git a/docs/id/channels/imessage.md b/docs/id/channels/imessage.md new file mode 100644 index 000000000..11b68133d --- /dev/null +++ b/docs/id/channels/imessage.md @@ -0,0 +1,434 @@ +--- +read_when: + - Menyiapkan dukungan iMessage + - Men-debug kirim/terima iMessage +summary: Dukungan iMessage lama melalui imsg (JSON-RPC melalui stdio). Penyiapan baru sebaiknya menggunakan BlueBubbles. +title: iMessage +x-i18n: + generated_at: "2026-04-05T13:43:28Z" + model: gpt-5.4 + provider: openai + source_hash: 086d85bead49f75d12ae6b14ac917af52375b6afd28f6af1a0dcbbc7fcb628a0 + source_path: channels/imessage.md + workflow: 15 +--- + +# iMessage (lama: imsg) + + +Untuk deployment iMessage baru, gunakan BlueBubbles. + +Integrasi `imsg` adalah versi lama dan mungkin akan dihapus pada rilis mendatang. + + +Status: integrasi CLI eksternal versi lama. Gateway memunculkan `imsg rpc` dan berkomunikasi melalui JSON-RPC di stdio (tanpa daemon/port terpisah). + + + + Jalur iMessage yang diprioritaskan untuk penyiapan baru. + + + DM iMessage secara default menggunakan mode pairing. + + + Referensi lengkap field iMessage. + + + +## Penyiapan cepat + + + + + + +```bash +brew install steipete/tap/imsg +imsg rpc --help +``` + + + + + +```json5 +{ + channels: { + imessage: { + enabled: true, + cliPath: "/usr/local/bin/imsg", + dbPath: "/Users//Library/Messages/chat.db", + }, + }, +} +``` + + + + + +```bash +openclaw gateway +``` + + + + + +```bash +openclaw pairing list imessage +openclaw pairing approve imessage +``` + + Permintaan pairing kedaluwarsa setelah 1 jam. + + + + + + + OpenClaw hanya memerlukan `cliPath` yang kompatibel dengan stdio, jadi Anda dapat mengarahkan `cliPath` ke skrip pembungkus yang melakukan SSH ke Mac jarak jauh dan menjalankan `imsg`. + +```bash +#!/usr/bin/env bash +exec ssh -T gateway-host imsg "$@" +``` + + Konfigurasi yang direkomendasikan saat lampiran diaktifkan: + +```json5 +{ + channels: { + imessage: { + enabled: true, + cliPath: "~/.openclaw/scripts/imsg-ssh", + remoteHost: "user@gateway-host", // digunakan untuk pengambilan lampiran melalui SCP + includeAttachments: true, + // Opsional: timpa root lampiran yang diizinkan. + // Default mencakup /Users/*/Library/Messages/Attachments + attachmentRoots: ["/Users/*/Library/Messages/Attachments"], + remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"], + }, + }, +} +``` + + Jika `remoteHost` tidak diatur, OpenClaw mencoba mendeteksinya secara otomatis dengan mem-parsing skrip pembungkus SSH. + `remoteHost` harus berupa `host` atau `user@host` (tanpa spasi atau opsi SSH). + OpenClaw menggunakan pemeriksaan host-key ketat untuk SCP, jadi host key relay harus sudah ada di `~/.ssh/known_hosts`. + Path lampiran divalidasi terhadap root yang diizinkan (`attachmentRoots` / `remoteAttachmentRoots`). + + + + +## Persyaratan dan izin (macOS) + +- Messages harus sudah login di Mac yang menjalankan `imsg`. +- Full Disk Access diperlukan untuk konteks proses yang menjalankan OpenClaw/`imsg` (akses DB Messages). +- Izin Automation diperlukan untuk mengirim pesan melalui Messages.app. + + +Izin diberikan per konteks proses. Jika gateway berjalan headless (LaunchAgent/SSH), jalankan satu perintah interaktif sekali dalam konteks yang sama untuk memicu prompt: + +```bash +imsg chats --limit 1 +# atau +imsg send "test" +``` + + + +## Kontrol akses dan perutean + + + + `channels.imessage.dmPolicy` mengontrol pesan langsung: + + - `pairing` (default) + - `allowlist` + - `open` (mengharuskan `allowFrom` menyertakan `"*"`) + - `disabled` + + Field allowlist: `channels.imessage.allowFrom`. + + Entri allowlist dapat berupa handle atau target chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`). + + + + + `channels.imessage.groupPolicy` mengontrol penanganan grup: + + - `allowlist` (default saat dikonfigurasi) + - `open` + - `disabled` + + Allowlist pengirim grup: `channels.imessage.groupAllowFrom`. + + Fallback runtime: jika `groupAllowFrom` tidak diatur, pemeriksaan pengirim grup iMessage akan fallback ke `allowFrom` jika tersedia. + Catatan runtime: jika `channels.imessage` sama sekali tidak ada, runtime fallback ke `groupPolicy="allowlist"` dan mencatat peringatan (bahkan jika `channels.defaults.groupPolicy` diatur). + + Penyaringan mention untuk grup: + + - iMessage tidak memiliki metadata mention bawaan + - deteksi mention menggunakan pola regex (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) + - tanpa pola yang dikonfigurasi, penyaringan mention tidak dapat diberlakukan + + Perintah kontrol dari pengirim yang diotorisasi dapat melewati penyaringan mention di grup. + + + + + - DM menggunakan perutean langsung; grup menggunakan perutean grup. + - Dengan default `session.dmScope=main`, DM iMessage digabungkan ke sesi utama agen. + - Sesi grup diisolasi (`agent::imessage:group:`). + - Balasan dirutekan kembali ke iMessage menggunakan metadata channel/target asal. + + Perilaku thread mirip grup: + + Beberapa thread iMessage multi-peserta dapat datang dengan `is_group=false`. + Jika `chat_id` tersebut dikonfigurasi secara eksplisit di bawah `channels.imessage.groups`, OpenClaw memperlakukannya sebagai lalu lintas grup (penyaringan grup + isolasi sesi grup). + + + + +## Binding percakapan ACP + +Chat iMessage versi lama juga dapat diikat ke sesi ACP. + +Alur operator cepat: + +- Jalankan `/acp spawn codex --bind here` di dalam DM atau chat grup yang diizinkan. +- Pesan berikutnya di percakapan iMessage yang sama akan dirutekan ke sesi ACP yang dimunculkan. +- `/new` dan `/reset` mengatur ulang sesi ACP terikat yang sama di tempat. +- `/acp close` menutup sesi ACP dan menghapus binding. + +Binding persisten yang dikonfigurasi didukung melalui entri `bindings[]` tingkat atas dengan `type: "acp"` dan `match.channel: "imessage"`. + +`match.peer.id` dapat menggunakan: + +- handle DM yang dinormalisasi seperti `+15555550123` atau `user@example.com` +- `chat_id:` (direkomendasikan untuk binding grup yang stabil) +- `chat_guid:` +- `chat_identifier:` + +Contoh: + +```json5 +{ + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { agent: "codex", backend: "acpx", mode: "persistent" }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "imessage", + accountId: "default", + peer: { kind: "group", id: "chat_id:123" }, + }, + acp: { label: "codex-group" }, + }, + ], +} +``` + +Lihat [ACP Agents](/tools/acp-agents) untuk perilaku binding ACP bersama. + +## Pola deployment + + + + Gunakan Apple ID dan pengguna macOS khusus agar lalu lintas bot terisolasi dari profil Messages pribadi Anda. + + Alur umum: + + 1. Buat/login pengguna macOS khusus. + 2. Login ke Messages dengan Apple ID bot pada pengguna tersebut. + 3. Instal `imsg` pada pengguna tersebut. + 4. Buat pembungkus SSH agar OpenClaw dapat menjalankan `imsg` dalam konteks pengguna tersebut. + 5. Arahkan `channels.imessage.accounts..cliPath` dan `.dbPath` ke profil pengguna tersebut. + + Eksekusi pertama mungkin memerlukan persetujuan GUI (Automation + Full Disk Access) pada sesi pengguna bot tersebut. + + + + + Topologi umum: + + - gateway berjalan di Linux/VM + - iMessage + `imsg` berjalan di Mac dalam tailnet Anda + - pembungkus `cliPath` menggunakan SSH untuk menjalankan `imsg` + - `remoteHost` mengaktifkan pengambilan lampiran melalui SCP + + Contoh: + +```json5 +{ + channels: { + imessage: { + enabled: true, + cliPath: "~/.openclaw/scripts/imsg-ssh", + remoteHost: "bot@mac-mini.tailnet-1234.ts.net", + includeAttachments: true, + dbPath: "/Users/bot/Library/Messages/chat.db", + }, + }, +} +``` + +```bash +#!/usr/bin/env bash +exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@" +``` + + Gunakan SSH key agar SSH dan SCP sama-sama non-interaktif. + Pastikan host key sudah dipercaya terlebih dahulu (misalnya `ssh bot@mac-mini.tailnet-1234.ts.net`) agar `known_hosts` terisi. + + + + + iMessage mendukung konfigurasi per akun di bawah `channels.imessage.accounts`. + + Setiap akun dapat menimpa field seperti `cliPath`, `dbPath`, `allowFrom`, `groupPolicy`, `mediaMaxMb`, pengaturan riwayat, dan allowlist root lampiran. + + + + +## Media, pemotongan, dan target pengiriman + + + + - ingest lampiran masuk bersifat opsional: `channels.imessage.includeAttachments` + - path lampiran jarak jauh dapat diambil melalui SCP saat `remoteHost` diatur + - path lampiran harus cocok dengan root yang diizinkan: + - `channels.imessage.attachmentRoots` (lokal) + - `channels.imessage.remoteAttachmentRoots` (mode SCP jarak jauh) + - pola root default: `/Users/*/Library/Messages/Attachments` + - SCP menggunakan pemeriksaan host-key ketat (`StrictHostKeyChecking=yes`) + - ukuran media keluar menggunakan `channels.imessage.mediaMaxMb` (default 16 MB) + + + + - batas potongan teks: `channels.imessage.textChunkLimit` (default 4000) + - mode potongan: `channels.imessage.chunkMode` + - `length` (default) + - `newline` (pemisahan dengan paragraf terlebih dahulu) + + + + Target eksplisit yang direkomendasikan: + + - `chat_id:123` (direkomendasikan untuk perutean yang stabil) + - `chat_guid:...` + - `chat_identifier:...` + + Target handle juga didukung: + + - `imessage:+1555...` + - `sms:+1555...` + - `user@example.com` + +```bash +imsg chats --limit 20 +``` + + + + +## Penulisan konfigurasi + +iMessage mengizinkan penulisan konfigurasi yang dimulai dari channel secara default (untuk `/config set|unset` saat `commands.config: true`). + +Nonaktifkan: + +```json5 +{ + channels: { + imessage: { + configWrites: false, + }, + }, +} +``` + +## Pemecahan masalah + + + + Validasi biner dan dukungan RPC: + +```bash +imsg rpc --help +openclaw channels status --probe +``` + + Jika probe melaporkan RPC tidak didukung, perbarui `imsg`. + + + + + Periksa: + + - `channels.imessage.dmPolicy` + - `channels.imessage.allowFrom` + - persetujuan pairing (`openclaw pairing list imessage`) + + + + + Periksa: + + - `channels.imessage.groupPolicy` + - `channels.imessage.groupAllowFrom` + - perilaku allowlist `channels.imessage.groups` + - konfigurasi pola mention (`agents.list[].groupChat.mentionPatterns`) + + + + + Periksa: + + - `channels.imessage.remoteHost` + - `channels.imessage.remoteAttachmentRoots` + - autentikasi key SSH/SCP dari host gateway + - host key ada di `~/.ssh/known_hosts` pada host gateway + - keterbacaan path jarak jauh pada Mac yang menjalankan Messages + + + + + Jalankan ulang di terminal GUI interaktif dalam konteks pengguna/sesi yang sama dan setujui prompt: + +```bash +imsg chats --limit 1 +imsg send "test" +``` + + Pastikan Full Disk Access + Automation telah diberikan untuk konteks proses yang menjalankan OpenClaw/`imsg`. + + + + +## Penunjuk referensi konfigurasi + +- [Referensi konfigurasi - iMessage](/gateway/configuration-reference#imessage) +- [Konfigurasi gateway](/gateway/configuration) +- [Pairing](/channels/pairing) +- [BlueBubbles](/channels/bluebubbles) + +## Terkait + +- [Ikhtisar Channel](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Grup](/channels/groups) — perilaku chat grup dan penyaringan mention +- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/index.md b/docs/id/channels/index.md new file mode 100644 index 000000000..9a118027a --- /dev/null +++ b/docs/id/channels/index.md @@ -0,0 +1,57 @@ +--- +read_when: + - Anda ingin memilih chat channel untuk OpenClaw + - Anda memerlukan ikhtisar singkat tentang platform perpesanan yang didukung +summary: Platform perpesanan yang dapat dihubungkan dengan OpenClaw +title: Chat Channels +x-i18n: + generated_at: "2026-04-05T13:43:03Z" + model: gpt-5.4 + provider: openai + source_hash: 246ee6f16aebe751241f00102bb435978ed21f6158385aff5d8e222e30567416 + source_path: channels/index.md + workflow: 15 +--- + +# Chat Channels + +OpenClaw dapat berbicara dengan Anda di aplikasi chat apa pun yang sudah Anda gunakan. Setiap channel terhubung melalui Gateway. +Teks didukung di semua tempat; media dan reaksi berbeda-beda menurut channel. + +## Channel yang didukung + +- [BlueBubbles](/channels/bluebubbles) — **Direkomendasikan untuk iMessage**; menggunakan REST API server macOS BlueBubbles dengan dukungan fitur penuh (plugin bawaan; edit, unsend, efek, reaksi, manajemen grup — edit saat ini rusak di macOS 26 Tahoe). +- [Discord](/channels/discord) — Discord Bot API + Gateway; mendukung server, channel, dan DM. +- [Feishu](/channels/feishu) — Bot Feishu/Lark melalui WebSocket (plugin bawaan). +- [Google Chat](/channels/googlechat) — Aplikasi Google Chat API melalui webhook HTTP. +- [iMessage (lama)](/channels/imessage) — Integrasi macOS lama melalui CLI imsg (tidak digunakan lagi, gunakan BlueBubbles untuk penyiapan baru). +- [IRC](/channels/irc) — Server IRC klasik; channel + DM dengan kontrol pairing/allowlist. +- [LINE](/channels/line) — Bot LINE Messaging API (plugin bawaan). +- [Matrix](/channels/matrix) — Protokol Matrix (plugin bawaan). +- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channel, grup, DM (plugin bawaan). +- [Microsoft Teams](/channels/msteams) — Bot Framework; dukungan enterprise (plugin bawaan). +- [Nextcloud Talk](/channels/nextcloud-talk) — Chat self-hosted melalui Nextcloud Talk (plugin bawaan). +- [Nostr](/channels/nostr) — DM terdesentralisasi melalui NIP-04 (plugin bawaan). +- [QQ Bot](/channels/qqbot) — QQ Bot API; chat privat, chat grup, dan media kaya (plugin bawaan). +- [Signal](/channels/signal) — signal-cli; berfokus pada privasi. +- [Slack](/channels/slack) — Bolt SDK; aplikasi workspace. +- [Synology Chat](/channels/synology-chat) — Chat Synology NAS melalui webhook keluar+masuk (plugin bawaan). +- [Telegram](/channels/telegram) — Bot API melalui grammY; mendukung grup. +- [Tlon](/channels/tlon) — Messenger berbasis Urbit (plugin bawaan). +- [Twitch](/channels/twitch) — Chat Twitch melalui koneksi IRC (plugin bawaan). +- [Voice Call](/plugins/voice-call) — Telepon melalui Plivo atau Twilio (plugin, dipasang secara terpisah). +- [WebChat](/web/webchat) — UI Gateway WebChat melalui WebSocket. +- [WeChat](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — Plugin Tencent iLink Bot melalui login QR; hanya chat privat. +- [WhatsApp](/channels/whatsapp) — Paling populer; menggunakan Baileys dan memerlukan pairing QR. +- [Zalo](/channels/zalo) — Zalo Bot API; messenger populer di Vietnam (plugin bawaan). +- [Zalo Personal](/channels/zalouser) — Akun pribadi Zalo melalui login QR (plugin bawaan). + +## Catatan + +- Channel dapat berjalan secara bersamaan; konfigurasikan beberapa channel dan OpenClaw akan melakukan routing per chat. +- Penyiapan tercepat biasanya **Telegram** (token bot sederhana). WhatsApp memerlukan pairing QR dan + menyimpan lebih banyak status di disk. +- Perilaku grup berbeda-beda menurut channel; lihat [Groups](/channels/groups). +- Pairing DM dan allowlist diterapkan demi keamanan; lihat [Security](/gateway/security). +- Pemecahan masalah: [Pemecahan masalah channel](/channels/troubleshooting). +- Provider model didokumentasikan secara terpisah; lihat [Model Providers](/providers/models). diff --git a/docs/id/channels/irc.md b/docs/id/channels/irc.md new file mode 100644 index 000000000..9a4f1f8cd --- /dev/null +++ b/docs/id/channels/irc.md @@ -0,0 +1,259 @@ +--- +read_when: + - Anda ingin menghubungkan OpenClaw ke channel IRC atau DM + - Anda sedang mengonfigurasi allowlist IRC, kebijakan grup, atau gating mention +summary: Penyiapan plugin IRC, kontrol akses, dan pemecahan masalah +title: IRC +x-i18n: + generated_at: "2026-04-05T13:43:16Z" + model: gpt-5.4 + provider: openai + source_hash: fceab2979db72116689c6c774d6736a8a2eee3559e3f3cf8969e673d317edd94 + source_path: channels/irc.md + workflow: 15 +--- + +# IRC + +Gunakan IRC saat Anda ingin OpenClaw berada di channel klasik (`#room`) dan direct message. +IRC dikirim sebagai extension plugin, tetapi dikonfigurasi di config utama di bawah `channels.irc`. + +## Mulai cepat + +1. Aktifkan config IRC di `~/.openclaw/openclaw.json`. +2. Setidaknya atur: + +```json5 +{ + channels: { + irc: { + enabled: true, + host: "irc.example.com", + port: 6697, + tls: true, + nick: "openclaw-bot", + channels: ["#openclaw"], + }, + }, +} +``` + +Utamakan server IRC privat untuk koordinasi bot. Jika Anda sengaja menggunakan jaringan IRC publik, pilihan umum mencakup Libera.Chat, OFTC, dan Snoonet. Hindari channel publik yang mudah ditebak untuk lalu lintas backchannel bot atau swarm. + +3. Mulai/restart gateway: + +```bash +openclaw gateway run +``` + +## Default keamanan + +- `channels.irc.dmPolicy` default ke `"pairing"`. +- `channels.irc.groupPolicy` default ke `"allowlist"`. +- Dengan `groupPolicy="allowlist"`, atur `channels.irc.groups` untuk menentukan channel yang diizinkan. +- Gunakan TLS (`channels.irc.tls=true`) kecuali Anda memang sengaja menerima transport plaintext. + +## Kontrol akses + +Ada dua “gate” terpisah untuk channel IRC: + +1. **Akses channel** (`groupPolicy` + `groups`): apakah bot menerima pesan dari suatu channel sama sekali. +2. **Akses pengirim** (`groupAllowFrom` / per-channel `groups["#channel"].allowFrom`): siapa yang diizinkan memicu bot di dalam channel tersebut. + +Kunci config: + +- Allowlist DM (akses pengirim DM): `channels.irc.allowFrom` +- Allowlist pengirim grup (akses pengirim channel): `channels.irc.groupAllowFrom` +- Kontrol per-channel (channel + pengirim + aturan mention): `channels.irc.groups["#channel"]` +- `channels.irc.groupPolicy="open"` mengizinkan channel yang tidak dikonfigurasi (**tetap di-gate oleh mention secara default**) + +Entri allowlist sebaiknya menggunakan identitas pengirim yang stabil (`nick!user@host`). +Pencocokan nick polos dapat berubah-ubah dan hanya diaktifkan saat `channels.irc.dangerouslyAllowNameMatching: true`. + +### Jebakan umum: `allowFrom` untuk DM, bukan channel + +Jika Anda melihat log seperti: + +- `irc: drop group sender alice!ident@host (policy=allowlist)` + +...artinya pengirim tidak diizinkan untuk pesan **grup/channel**. Perbaiki dengan salah satu cara berikut: + +- mengatur `channels.irc.groupAllowFrom` (global untuk semua channel), atau +- mengatur allowlist pengirim per-channel: `channels.irc.groups["#channel"].allowFrom` + +Contoh (izinkan siapa pun di `#tuirc-dev` berbicara dengan bot): + +```json5 +{ + channels: { + irc: { + groupPolicy: "allowlist", + groups: { + "#tuirc-dev": { allowFrom: ["*"] }, + }, + }, + }, +} +``` + +## Pemicu balasan (mention) + +Walaupun suatu channel diizinkan (melalui `groupPolicy` + `groups`) dan pengirim diizinkan, OpenClaw secara default menggunakan **gating mention** dalam konteks grup. + +Artinya Anda mungkin melihat log seperti `drop channel … (missing-mention)` kecuali pesan menyertakan pola mention yang cocok dengan bot. + +Untuk membuat bot membalas di channel IRC **tanpa memerlukan mention**, nonaktifkan gating mention untuk channel tersebut: + +```json5 +{ + channels: { + irc: { + groupPolicy: "allowlist", + groups: { + "#tuirc-dev": { + requireMention: false, + allowFrom: ["*"], + }, + }, + }, + }, +} +``` + +Atau untuk mengizinkan **semua** channel IRC (tanpa allowlist per-channel) dan tetap membalas tanpa mention: + +```json5 +{ + channels: { + irc: { + groupPolicy: "open", + groups: { + "*": { requireMention: false, allowFrom: ["*"] }, + }, + }, + }, +} +``` + +## Catatan keamanan (disarankan untuk channel publik) + +Jika Anda mengizinkan `allowFrom: ["*"]` di channel publik, siapa pun dapat memberi prompt ke bot. +Untuk mengurangi risiko, batasi tools untuk channel tersebut. + +### Tools yang sama untuk semua orang di channel + +```json5 +{ + channels: { + irc: { + groups: { + "#tuirc-dev": { + allowFrom: ["*"], + tools: { + deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"], + }, + }, + }, + }, + }, +} +``` + +### Tools berbeda per pengirim (pemilik mendapat lebih banyak kuasa) + +Gunakan `toolsBySender` untuk menerapkan kebijakan yang lebih ketat ke `"*"` dan yang lebih longgar ke nick Anda: + +```json5 +{ + channels: { + irc: { + groups: { + "#tuirc-dev": { + allowFrom: ["*"], + toolsBySender: { + "*": { + deny: ["group:runtime", "group:fs", "gateway", "nodes", "cron", "browser"], + }, + "id:eigen": { + deny: ["gateway", "nodes", "cron"], + }, + }, + }, + }, + }, + }, +} +``` + +Catatan: + +- Kunci `toolsBySender` sebaiknya menggunakan `id:` untuk nilai identitas pengirim IRC: + `id:eigen` atau `id:eigen!~eigen@174.127.248.171` untuk pencocokan yang lebih kuat. +- Kunci lama tanpa prefiks masih diterima dan hanya dicocokkan sebagai `id:`. +- Kebijakan pengirim pertama yang cocok akan menang; `"*"` adalah fallback wildcard. + +Untuk informasi lebih lanjut tentang akses grup vs gating mention (dan bagaimana keduanya berinteraksi), lihat: [/channels/groups](/channels/groups). + +## NickServ + +Untuk mengidentifikasi diri ke NickServ setelah terhubung: + +```json5 +{ + channels: { + irc: { + nickserv: { + enabled: true, + service: "NickServ", + password: "your-nickserv-password", + }, + }, + }, +} +``` + +Registrasi satu kali opsional saat terhubung: + +```json5 +{ + channels: { + irc: { + nickserv: { + register: true, + registerEmail: "bot@example.com", + }, + }, + }, +} +``` + +Nonaktifkan `register` setelah nick terdaftar agar tidak terjadi percobaan REGISTER berulang. + +## Variabel lingkungan + +Akun default mendukung: + +- `IRC_HOST` +- `IRC_PORT` +- `IRC_TLS` +- `IRC_NICK` +- `IRC_USERNAME` +- `IRC_REALNAME` +- `IRC_PASSWORD` +- `IRC_CHANNELS` (dipisahkan dengan koma) +- `IRC_NICKSERV_PASSWORD` +- `IRC_NICKSERV_REGISTER_EMAIL` + +## Pemecahan masalah + +- Jika bot terhubung tetapi tidak pernah membalas di channel, verifikasi `channels.irc.groups` **dan** apakah gating mention membuang pesan (`missing-mention`). Jika Anda ingin bot membalas tanpa ping, set `requireMention:false` untuk channel tersebut. +- Jika login gagal, verifikasi ketersediaan nick dan kata sandi server. +- Jika TLS gagal pada jaringan kustom, verifikasi host/port dan penyiapan sertifikat. + +## Terkait + +- [Ringkasan Channel](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan gating mention +- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/line.md b/docs/id/channels/line.md new file mode 100644 index 000000000..9d27434a2 --- /dev/null +++ b/docs/id/channels/line.md @@ -0,0 +1,232 @@ +--- +read_when: + - Anda ingin menghubungkan OpenClaw ke LINE + - Anda memerlukan penyiapan webhook + kredensial LINE + - Anda menginginkan opsi pesan khusus LINE +summary: Penyiapan, config, dan penggunaan plugin LINE Messaging API +title: LINE +x-i18n: + generated_at: "2026-04-05T13:43:23Z" + model: gpt-5.4 + provider: openai + source_hash: b4782b2aa3e8654505d7f1fd6fc112adf125b5010fc84d655d033688ded37414 + source_path: channels/line.md + workflow: 15 +--- + +# LINE + +LINE terhubung ke OpenClaw melalui LINE Messaging API. Plugin berjalan sebagai +penerima webhook di gateway dan menggunakan token akses channel + rahasia channel Anda untuk +autentikasi. + +Status: plugin bawaan. Direct message, obrolan grup, media, lokasi, pesan Flex, +pesan template, dan quick reply didukung. Reactions dan thread +tidak didukung. + +## Plugin bawaan + +LINE dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build +terpaket normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan LINE, instal +secara manual: + +```bash +openclaw plugins install @openclaw/line +``` + +Checkout lokal (saat berjalan dari repo git): + +```bash +openclaw plugins install ./path/to/local/line-plugin +``` + +## Penyiapan + +1. Buat akun LINE Developers dan buka Console: + [https://developers.line.biz/console/](https://developers.line.biz/console/) +2. Buat (atau pilih) Provider dan tambahkan channel **Messaging API**. +3. Salin **Channel access token** dan **Channel secret** dari pengaturan channel. +4. Aktifkan **Use webhook** di pengaturan Messaging API. +5. Atur URL webhook ke endpoint gateway Anda (HTTPS wajib): + +``` +https://gateway-host/line/webhook +``` + +Gateway merespons verifikasi webhook LINE (GET) dan peristiwa masuk (POST). +Jika Anda memerlukan path kustom, atur `channels.line.webhookPath` atau +`channels.line.accounts..webhookPath` dan perbarui URL sesuai kebutuhan. + +Catatan keamanan: + +- Verifikasi signature LINE bergantung pada body (HMAC atas body mentah), jadi OpenClaw menerapkan batas body pra-autentikasi yang ketat dan timeout sebelum verifikasi. +- OpenClaw memproses peristiwa webhook dari byte permintaan mentah yang telah diverifikasi. Nilai `req.body` yang diubah oleh middleware upstream diabaikan demi keamanan integritas signature. + +## Konfigurasi + +Config minimal: + +```json5 +{ + channels: { + line: { + enabled: true, + channelAccessToken: "LINE_CHANNEL_ACCESS_TOKEN", + channelSecret: "LINE_CHANNEL_SECRET", + dmPolicy: "pairing", + }, + }, +} +``` + +Variabel env (hanya akun default): + +- `LINE_CHANNEL_ACCESS_TOKEN` +- `LINE_CHANNEL_SECRET` + +File token/secret: + +```json5 +{ + channels: { + line: { + tokenFile: "/path/to/line-token.txt", + secretFile: "/path/to/line-secret.txt", + }, + }, +} +``` + +`tokenFile` dan `secretFile` harus menunjuk ke file reguler. Symlink ditolak. + +Beberapa akun: + +```json5 +{ + channels: { + line: { + accounts: { + marketing: { + channelAccessToken: "...", + channelSecret: "...", + webhookPath: "/line/marketing", + }, + }, + }, + }, +} +``` + +## Kontrol akses + +Direct message secara default menggunakan pairing. Pengirim yang tidak dikenal akan mendapatkan kode pairing dan +pesannya diabaikan sampai disetujui. + +```bash +openclaw pairing list line +openclaw pairing approve line +``` + +Allowlist dan kebijakan: + +- `channels.line.dmPolicy`: `pairing | allowlist | open | disabled` +- `channels.line.allowFrom`: ID pengguna LINE yang masuk allowlist untuk DM +- `channels.line.groupPolicy`: `allowlist | open | disabled` +- `channels.line.groupAllowFrom`: ID pengguna LINE yang masuk allowlist untuk grup +- Override per grup: `channels.line.groups..allowFrom` +- Catatan runtime: jika `channels.line` tidak ada sama sekali, runtime akan fallback ke `groupPolicy="allowlist"` untuk pemeriksaan grup (bahkan jika `channels.defaults.groupPolicy` diatur). + +ID LINE peka huruf besar/kecil. ID yang valid terlihat seperti: + +- Pengguna: `U` + 32 karakter hex +- Grup: `C` + 32 karakter hex +- Room: `R` + 32 karakter hex + +## Perilaku pesan + +- Teks dipotong per 5000 karakter. +- Format Markdown dihapus; blok kode dan tabel dikonversi menjadi kartu Flex + jika memungkinkan. +- Respons streaming dibuffer; LINE menerima potongan penuh dengan animasi + loading saat agen bekerja. +- Unduhan media dibatasi oleh `channels.line.mediaMaxMb` (default 10). + +## Data channel (pesan kaya) + +Gunakan `channelData.line` untuk mengirim quick reply, lokasi, kartu Flex, atau pesan +template. + +```json5 +{ + text: "Here you go", + channelData: { + line: { + quickReplies: ["Status", "Help"], + location: { + title: "Office", + address: "123 Main St", + latitude: 35.681236, + longitude: 139.767125, + }, + flexMessage: { + altText: "Status card", + contents: { + /* Flex payload */ + }, + }, + templateMessage: { + type: "confirm", + text: "Proceed?", + confirmLabel: "Yes", + confirmData: "yes", + cancelLabel: "No", + cancelData: "no", + }, + }, + }, +} +``` + +Plugin LINE juga menyertakan perintah `/card` untuk preset pesan Flex: + +``` +/card info "Welcome" "Thanks for joining!" +``` + +## Dukungan ACP + +LINE mendukung binding percakapan ACP (Agent Communication Protocol): + +- `/acp spawn --bind here` mengikat obrolan LINE saat ini ke sesi ACP tanpa membuat child thread. +- Binding ACP yang dikonfigurasi dan sesi ACP aktif yang terikat percakapan bekerja di LINE seperti di channel percakapan lainnya. + +Lihat [ACP agents](/tools/acp-agents) untuk detail. + +## Media keluar + +Plugin LINE mendukung pengiriman file gambar, video, dan audio melalui alat pesan agen. Media dikirim melalui jalur pengiriman khusus LINE dengan penanganan pratinjau dan pelacakan yang sesuai: + +- **Gambar**: dikirim sebagai pesan gambar LINE dengan pembuatan pratinjau otomatis. +- **Video**: dikirim dengan pratinjau eksplisit dan penanganan content-type. +- **Audio**: dikirim sebagai pesan audio LINE. + +Pengiriman media generik akan fallback ke rute khusus gambar yang sudah ada saat jalur khusus LINE tidak tersedia. + +## Pemecahan masalah + +- **Verifikasi webhook gagal:** pastikan URL webhook menggunakan HTTPS dan + `channelSecret` cocok dengan console LINE. +- **Tidak ada peristiwa masuk:** pastikan path webhook cocok dengan `channels.line.webhookPath` + dan gateway dapat dijangkau dari LINE. +- **Error unduhan media:** tingkatkan `channels.line.mediaMaxMb` jika media melebihi + batas default. + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention +- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan +- [Security](/gateway/security) — model akses dan penguatan diff --git a/docs/id/channels/location.md b/docs/id/channels/location.md new file mode 100644 index 000000000..8e1e407b1 --- /dev/null +++ b/docs/id/channels/location.md @@ -0,0 +1,63 @@ +--- +read_when: + - Menambahkan atau memodifikasi penguraian lokasi channel + - Menggunakan field konteks lokasi dalam prompt agent atau tool +summary: Penguraian lokasi channel masuk (Telegram/WhatsApp/Matrix) dan field konteks +title: Channel Location Parsing +x-i18n: + generated_at: "2026-04-05T13:43:13Z" + model: gpt-5.4 + provider: openai + source_hash: 10061f0c109240a9e0bcab649b17f03b674e8bdf410debf3669b7b6da8189d96 + source_path: channels/location.md + workflow: 15 +--- + +# Penguraian lokasi channel + +OpenClaw menormalkan lokasi bersama dari chat channel menjadi: + +- teks yang dapat dibaca manusia yang ditambahkan ke body masuk, dan +- field terstruktur dalam payload konteks balasan otomatis. + +Saat ini didukung: + +- **Telegram** (pin lokasi + venue + lokasi live) +- **WhatsApp** (`locationMessage` + `liveLocationMessage`) +- **Matrix** (`m.location` dengan `geo_uri`) + +## Pemformatan teks + +Lokasi dirender sebagai baris yang ramah tanpa tanda kurung: + +- Pin: + - `📍 48.858844, 2.294351 ±12m` +- Tempat bernama: + - `📍 Eiffel Tower — Champ de Mars, Paris (48.858844, 2.294351 ±12m)` +- Berbagi live: + - `🛰 Lokasi live: 48.858844, 2.294351 ±12m` + +Jika channel menyertakan caption/komentar, itu ditambahkan pada baris berikutnya: + +``` +📍 48.858844, 2.294351 ±12m +Temui di sini +``` + +## Field konteks + +Saat lokasi ada, field ini ditambahkan ke `ctx`: + +- `LocationLat` (angka) +- `LocationLon` (angka) +- `LocationAccuracy` (angka, meter; opsional) +- `LocationName` (string; opsional) +- `LocationAddress` (string; opsional) +- `LocationSource` (`pin | place | live`) +- `LocationIsLive` (boolean) + +## Catatan channel + +- **Telegram**: venue dipetakan ke `LocationName/LocationAddress`; lokasi live menggunakan `live_period`. +- **WhatsApp**: `locationMessage.comment` dan `liveLocationMessage.caption` ditambahkan sebagai baris caption. +- **Matrix**: `geo_uri` diurai sebagai lokasi pin; ketinggian diabaikan dan `LocationIsLive` selalu false. diff --git a/docs/id/channels/matrix.md b/docs/id/channels/matrix.md new file mode 100644 index 000000000..c0a039f7f --- /dev/null +++ b/docs/id/channels/matrix.md @@ -0,0 +1,870 @@ +--- +read_when: + - Menyiapkan Matrix di OpenClaw + - Mengonfigurasi Matrix E2EE dan verifikasi +summary: Status dukungan, penyiapan, dan contoh konfigurasi Matrix +title: Matrix +x-i18n: + generated_at: "2026-04-05T13:44:56Z" + model: gpt-5.4 + provider: openai + source_hash: ba5c49ad2125d97adf66b5517f8409567eff8b86e20224a32fcb940a02cb0659 + source_path: channels/matrix.md + workflow: 15 +--- + +# Matrix + +Matrix adalah plugin channel bawaan Matrix untuk OpenClaw. +Plugin ini menggunakan `matrix-js-sdk` resmi dan mendukung DM, room, thread, media, reaksi, polling, lokasi, dan E2EE. + +## Plugin bawaan + +Matrix dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build +paket normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build yang lebih lama atau instalasi kustom yang tidak menyertakan Matrix, instal +secara manual: + +Instal dari npm: + +```bash +openclaw plugins install @openclaw/matrix +``` + +Instal dari checkout lokal: + +```bash +openclaw plugins install ./path/to/local/matrix-plugin +``` + +Lihat [Plugins](/tools/plugin) untuk perilaku plugin dan aturan instalasi. + +## Penyiapan + +1. Pastikan plugin Matrix tersedia. + - Rilis OpenClaw dalam paket saat ini sudah menyertakannya. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Buat akun Matrix di homeserver Anda. +3. Konfigurasikan `channels.matrix` dengan salah satu dari: + - `homeserver` + `accessToken`, atau + - `homeserver` + `userId` + `password`. +4. Mulai ulang gateway. +5. Mulai DM dengan bot atau undang bot ke room. + +Jalur penyiapan interaktif: + +```bash +openclaw channels add +openclaw configure --section channels +``` + +Yang benar-benar ditanyakan wizard Matrix: + +- URL homeserver +- metode auth: access token atau password +- ID pengguna hanya saat Anda memilih auth password +- nama perangkat opsional +- apakah akan mengaktifkan E2EE +- apakah akan mengonfigurasi akses room Matrix sekarang + +Perilaku wizard yang penting: + +- Jika env var auth Matrix sudah ada untuk akun yang dipilih, dan akun tersebut belum memiliki auth yang tersimpan di config, wizard menawarkan pintasan env dan hanya menulis `enabled: true` untuk akun tersebut. +- Saat Anda menambahkan akun Matrix lain secara interaktif, nama akun yang dimasukkan dinormalisasi menjadi ID akun yang digunakan di config dan env vars. Misalnya, `Ops Bot` menjadi `ops-bot`. +- Prompt allowlist DM langsung menerima nilai `@user:server` penuh. Nama tampilan hanya berfungsi saat lookup direktori langsung menemukan satu kecocokan yang tepat; jika tidak, wizard meminta Anda mencoba lagi dengan ID Matrix penuh. +- Prompt allowlist room menerima ID room dan alias secara langsung. Prompt ini juga dapat meresolusikan nama room yang sudah diikuti secara live, tetapi nama yang tidak teresolusikan hanya dipertahankan sebagaimana diketik saat penyiapan dan diabaikan nanti oleh resolusi allowlist saat runtime. Utamakan `!room:server` atau `#alias:server`. +- Identitas room/sesi saat runtime menggunakan ID room Matrix yang stabil. Alias yang dideklarasikan room hanya digunakan sebagai input lookup, bukan sebagai kunci sesi jangka panjang atau identitas grup yang stabil. +- Untuk meresolusikan nama room sebelum menyimpannya, gunakan `openclaw channels resolve --channel matrix "Project Room"`. + +Penyiapan minimal berbasis token: + +```json5 +{ + channels: { + matrix: { + enabled: true, + homeserver: "https://matrix.example.org", + accessToken: "syt_xxx", + dm: { policy: "pairing" }, + }, + }, +} +``` + +Penyiapan berbasis password (token di-cache setelah login): + +```json5 +{ + channels: { + matrix: { + enabled: true, + homeserver: "https://matrix.example.org", + userId: "@bot:example.org", + password: "replace-me", // pragma: allowlist secret + deviceName: "OpenClaw Gateway", + }, + }, +} +``` + +Matrix menyimpan kredensial cache di `~/.openclaw/credentials/matrix/`. +Akun default menggunakan `credentials.json`; akun bernama menggunakan `credentials-.json`. + +Padanan variabel environment (digunakan saat kunci config tidak ditetapkan): + +- `MATRIX_HOMESERVER` +- `MATRIX_ACCESS_TOKEN` +- `MATRIX_USER_ID` +- `MATRIX_PASSWORD` +- `MATRIX_DEVICE_ID` +- `MATRIX_DEVICE_NAME` + +Untuk akun non-default, gunakan env vars dengan cakupan akun: + +- `MATRIX__HOMESERVER` +- `MATRIX__ACCESS_TOKEN` +- `MATRIX__USER_ID` +- `MATRIX__PASSWORD` +- `MATRIX__DEVICE_ID` +- `MATRIX__DEVICE_NAME` + +Contoh untuk akun `ops`: + +- `MATRIX_OPS_HOMESERVER` +- `MATRIX_OPS_ACCESS_TOKEN` + +Untuk ID akun yang dinormalisasi `ops-bot`, gunakan: + +- `MATRIX_OPS_X2D_BOT_HOMESERVER` +- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` + +Matrix meng-escape tanda baca dalam ID akun agar env vars bercakupan tetap bebas tabrakan. +Misalnya, `-` menjadi `_X2D_`, sehingga `ops-prod` dipetakan ke `MATRIX_OPS_X2D_PROD_*`. + +Wizard interaktif hanya menawarkan pintasan env-var saat env vars auth tersebut sudah ada dan akun yang dipilih belum memiliki auth Matrix yang tersimpan di config. + +## Contoh konfigurasi + +Ini adalah config baseline praktis dengan pairing DM, allowlist room, dan E2EE diaktifkan: + +```json5 +{ + channels: { + matrix: { + enabled: true, + homeserver: "https://matrix.example.org", + accessToken: "syt_xxx", + encryption: true, + + dm: { + policy: "pairing", + threadReplies: "off", + }, + + groupPolicy: "allowlist", + groupAllowFrom: ["@admin:example.org"], + groups: { + "!roomid:example.org": { + requireMention: true, + }, + }, + + autoJoin: "allowlist", + autoJoinAllowlist: ["!roomid:example.org"], + threadReplies: "inbound", + replyToMode: "off", + streaming: "partial", + }, + }, +} +``` + +## Pratinjau streaming + +Streaming balasan Matrix bersifat opt-in. + +Tetapkan `channels.matrix.streaming` ke `"partial"` saat Anda ingin OpenClaw mengirim satu balasan draf, +mengedit draf tersebut di tempat saat model sedang menghasilkan teks, lalu memfinalkannya ketika balasan +selesai: + +```json5 +{ + channels: { + matrix: { + streaming: "partial", + }, + }, +} +``` + +- `streaming: "off"` adalah default. OpenClaw menunggu balasan final dan mengirimnya sekali. +- `streaming: "partial"` membuat satu pesan pratinjau yang dapat diedit untuk blok asisten saat ini alih-alih mengirim beberapa pesan parsial. +- `blockStreaming: true` mengaktifkan pesan progres Matrix terpisah. Dengan `streaming: "partial"`, Matrix mempertahankan draf live untuk blok saat ini dan mempertahankan blok yang sudah selesai sebagai pesan terpisah. +- Saat `streaming: "partial"` dan `blockStreaming` nonaktif, Matrix hanya mengedit draf live dan mengirim balasan lengkap setelah blok atau giliran tersebut selesai. +- Jika pratinjau tidak lagi muat dalam satu event Matrix, OpenClaw menghentikan streaming pratinjau dan kembali ke pengiriman final normal. +- Balasan media tetap mengirim lampiran secara normal. Jika pratinjau lama tidak lagi dapat digunakan kembali dengan aman, OpenClaw meredaksinya sebelum mengirim balasan media final. +- Edit pratinjau memerlukan panggilan API Matrix tambahan. Biarkan streaming nonaktif jika Anda menginginkan perilaku rate-limit yang paling konservatif. + +`blockStreaming` tidak dengan sendirinya mengaktifkan pratinjau draf. +Gunakan `streaming: "partial"` untuk edit pratinjau; lalu tambahkan `blockStreaming: true` hanya jika Anda juga ingin blok asisten yang selesai tetap terlihat sebagai pesan progres terpisah. + +## Enkripsi dan verifikasi + +Di room terenkripsi (E2EE), event gambar keluar menggunakan `thumbnail_file` sehingga pratinjau gambar terenkripsi bersama lampiran penuh. Room yang tidak terenkripsi tetap menggunakan `thumbnail_url` biasa. Tidak diperlukan konfigurasi — plugin mendeteksi status E2EE secara otomatis. + +### Room bot ke bot + +Secara default, pesan Matrix dari akun Matrix OpenClaw lain yang dikonfigurasi akan diabaikan. + +Gunakan `allowBots` saat Anda memang ingin lalu lintas Matrix antar-agen: + +```json5 +{ + channels: { + matrix: { + allowBots: "mentions", // true | "mentions" + groups: { + "!roomid:example.org": { + requireMention: true, + }, + }, + }, + }, +} +``` + +- `allowBots: true` menerima pesan dari akun bot Matrix lain yang dikonfigurasi di room dan DM yang diizinkan. +- `allowBots: "mentions"` menerima pesan tersebut hanya saat pesan secara terlihat me-mention bot ini di room. DM tetap diizinkan. +- `groups..allowBots` menimpa setelan tingkat akun untuk satu room. +- OpenClaw tetap mengabaikan pesan dari ID pengguna Matrix yang sama untuk menghindari loop balas-diri. +- Matrix tidak mengekspos flag bot native di sini; OpenClaw menganggap "dibuat oleh bot" sebagai "dikirim oleh akun Matrix lain yang dikonfigurasi pada gateway OpenClaw ini". + +Gunakan allowlist room yang ketat dan persyaratan mention saat mengaktifkan lalu lintas bot-ke-bot di room bersama. + +Aktifkan enkripsi: + +```json5 +{ + channels: { + matrix: { + enabled: true, + homeserver: "https://matrix.example.org", + accessToken: "syt_xxx", + encryption: true, + dm: { policy: "pairing" }, + }, + }, +} +``` + +Periksa status verifikasi: + +```bash +openclaw matrix verify status +``` + +Status verbose (diagnostik lengkap): + +```bash +openclaw matrix verify status --verbose +``` + +Sertakan recovery key yang tersimpan dalam output yang dapat dibaca mesin: + +```bash +openclaw matrix verify status --include-recovery-key --json +``` + +Bootstrap status cross-signing dan verifikasi: + +```bash +openclaw matrix verify bootstrap +``` + +Dukungan multi-akun: gunakan `channels.matrix.accounts` dengan kredensial per akun dan `name` opsional. Lihat [Referensi konfigurasi](/gateway/configuration-reference#multi-account-all-channels) untuk pola bersama. + +Diagnostik bootstrap verbose: + +```bash +openclaw matrix verify bootstrap --verbose +``` + +Paksa reset identitas cross-signing baru sebelum bootstrap: + +```bash +openclaw matrix verify bootstrap --force-reset-cross-signing +``` + +Verifikasi perangkat ini dengan recovery key: + +```bash +openclaw matrix verify device "" +``` + +Detail verifikasi perangkat verbose: + +```bash +openclaw matrix verify device "" --verbose +``` + +Periksa kesehatan backup room-key: + +```bash +openclaw matrix verify backup status +``` + +Diagnostik kesehatan backup verbose: + +```bash +openclaw matrix verify backup status --verbose +``` + +Pulihkan room key dari backup server: + +```bash +openclaw matrix verify backup restore +``` + +Diagnostik pemulihan verbose: + +```bash +openclaw matrix verify backup restore --verbose +``` + +Hapus backup server saat ini dan buat baseline backup baru. Jika backup key yang tersimpan +tidak dapat dimuat dengan bersih, reset ini juga dapat membuat ulang secret storage sehingga +cold start berikutnya dapat memuat backup key yang baru: + +```bash +openclaw matrix verify backup reset --yes +``` + +Semua perintah `verify` ringkas secara default (termasuk logging SDK internal yang sunyi) dan hanya menampilkan diagnostik terperinci dengan `--verbose`. +Gunakan `--json` untuk output lengkap yang dapat dibaca mesin saat scripting. + +Dalam penyiapan multi-akun, perintah CLI Matrix menggunakan akun default Matrix implisit kecuali Anda meneruskan `--account `. +Jika Anda mengonfigurasi beberapa akun bernama, tetapkan `channels.matrix.defaultAccount` terlebih dahulu atau operasi CLI implisit tersebut akan berhenti dan meminta Anda memilih akun secara eksplisit. +Gunakan `--account` setiap kali Anda ingin operasi verifikasi atau perangkat menargetkan akun bernama secara eksplisit: + +```bash +openclaw matrix verify status --account assistant +openclaw matrix verify backup restore --account assistant +openclaw matrix devices list --account assistant +``` + +Saat enkripsi dinonaktifkan atau tidak tersedia untuk akun bernama, peringatan Matrix dan error verifikasi menunjuk ke kunci config akun tersebut, misalnya `channels.matrix.accounts.assistant.encryption`. + +### Arti "terverifikasi" + +OpenClaw menganggap perangkat Matrix ini terverifikasi hanya jika perangkat tersebut diverifikasi oleh identitas cross-signing Anda sendiri. +Dalam praktiknya, `openclaw matrix verify status --verbose` mengekspos tiga sinyal kepercayaan: + +- `Locally trusted`: perangkat ini dipercaya hanya oleh klien saat ini +- `Cross-signing verified`: SDK melaporkan perangkat sebagai terverifikasi melalui cross-signing +- `Signed by owner`: perangkat ditandatangani oleh self-signing key milik Anda sendiri + +`Verified by owner` menjadi `yes` hanya saat verifikasi cross-signing atau owner-signing ada. +Kepercayaan lokal saja tidak cukup bagi OpenClaw untuk menganggap perangkat sepenuhnya terverifikasi. + +### Fungsi bootstrap + +`openclaw matrix verify bootstrap` adalah perintah perbaikan dan penyiapan untuk akun Matrix terenkripsi. +Perintah ini melakukan semua hal berikut secara berurutan: + +- mem-bootstrap secret storage, menggunakan kembali recovery key yang sudah ada bila memungkinkan +- mem-bootstrap cross-signing dan mengunggah public cross-signing keys yang hilang +- mencoba menandai dan me-cross-sign perangkat saat ini +- membuat backup room-key sisi server baru jika belum ada + +Jika homeserver memerlukan auth interaktif untuk mengunggah cross-signing keys, OpenClaw mencoba unggahan tanpa auth terlebih dahulu, lalu dengan `m.login.dummy`, lalu dengan `m.login.password` saat `channels.matrix.password` dikonfigurasi. + +Gunakan `--force-reset-cross-signing` hanya saat Anda memang ingin membuang identitas cross-signing saat ini dan membuat yang baru. + +Jika Anda memang ingin membuang backup room-key saat ini dan memulai baseline backup +baru untuk pesan mendatang, gunakan `openclaw matrix verify backup reset --yes`. +Lakukan ini hanya jika Anda menerima bahwa riwayat terenkripsi lama yang tidak dapat dipulihkan akan tetap +tidak tersedia dan bahwa OpenClaw dapat membuat ulang secret storage jika secret backup saat ini +tidak dapat dimuat dengan aman. + +### Baseline backup baru + +Jika Anda ingin menjaga agar pesan terenkripsi di masa depan tetap berfungsi dan menerima kehilangan riwayat lama yang tidak dapat dipulihkan, jalankan perintah ini secara berurutan: + +```bash +openclaw matrix verify backup reset --yes +openclaw matrix verify backup status --verbose +openclaw matrix verify status +``` + +Tambahkan `--account ` ke setiap perintah saat Anda ingin secara eksplisit menargetkan akun Matrix bernama. + +### Perilaku startup + +Saat `encryption: true`, Matrix secara default menetapkan `startupVerification` ke `"if-unverified"`. +Saat startup, jika perangkat ini masih belum terverifikasi, Matrix akan meminta self-verification di klien Matrix lain, +melewati permintaan duplikat saat sudah ada satu yang tertunda, dan menerapkan cooldown lokal sebelum mencoba lagi setelah restart. +Upaya permintaan yang gagal akan mencoba ulang lebih cepat daripada pembuatan permintaan yang berhasil secara default. +Tetapkan `startupVerification: "off"` untuk menonaktifkan permintaan startup otomatis, atau atur `startupVerificationCooldownHours` +jika Anda menginginkan jendela coba ulang yang lebih pendek atau lebih panjang. + +Startup juga melakukan pass bootstrap crypto yang konservatif secara otomatis. +Pass tersebut mencoba menggunakan kembali secret storage dan identitas cross-signing saat ini terlebih dahulu, dan menghindari reset cross-signing kecuali Anda menjalankan alur perbaikan bootstrap eksplisit. + +Jika startup menemukan status bootstrap yang rusak dan `channels.matrix.password` dikonfigurasi, OpenClaw dapat mencoba jalur perbaikan yang lebih ketat. +Jika perangkat saat ini sudah owner-signed, OpenClaw mempertahankan identitas tersebut alih-alih meresetnya secara otomatis. + +Upgrade dari plugin Matrix publik sebelumnya: + +- OpenClaw secara otomatis menggunakan kembali akun Matrix, access token, dan identitas perangkat yang sama bila memungkinkan. +- Sebelum perubahan migrasi Matrix yang dapat ditindaklanjuti dijalankan, OpenClaw membuat atau menggunakan kembali snapshot pemulihan di `~/Backups/openclaw-migrations/`. +- Jika Anda menggunakan beberapa akun Matrix, tetapkan `channels.matrix.defaultAccount` sebelum upgrade dari tata letak flat-store lama agar OpenClaw tahu akun mana yang harus menerima status lama bersama tersebut. +- Jika plugin sebelumnya menyimpan decryption key backup room-key Matrix secara lokal, startup atau `openclaw doctor --fix` akan mengimpornya secara otomatis ke alur recovery-key baru. +- Jika access token Matrix berubah setelah migrasi disiapkan, startup sekarang memindai root penyimpanan hash token saudara untuk status restore lama yang tertunda sebelum menyerah pada restore backup otomatis. +- Jika access token Matrix berubah kemudian untuk akun, homeserver, dan pengguna yang sama, OpenClaw sekarang mengutamakan penggunaan kembali root hash token yang paling lengkap alih-alih memulai dari direktori status Matrix kosong. +- Pada startup gateway berikutnya, room key yang telah dibackup dipulihkan secara otomatis ke crypto store baru. +- Jika plugin lama memiliki room key hanya-lokal yang tidak pernah dibackup, OpenClaw akan memberi peringatan dengan jelas. Kunci tersebut tidak dapat diekspor secara otomatis dari rust crypto store sebelumnya, sehingga beberapa riwayat terenkripsi lama mungkin tetap tidak tersedia sampai dipulihkan secara manual. +- Lihat [Migrasi Matrix](/install/migrating-matrix) untuk alur upgrade lengkap, batasan, perintah pemulihan, dan pesan migrasi umum. + +Status runtime terenkripsi diatur di bawah root hash token per akun, per pengguna dalam +`~/.openclaw/matrix/accounts//__//`. +Direktori tersebut berisi sync store (`bot-storage.json`), crypto store (`crypto/`), +file recovery key (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`), +thread bindings (`thread-bindings.json`), dan status verifikasi startup (`startup-verification.json`) +saat fitur-fitur tersebut digunakan. +Ketika token berubah tetapi identitas akun tetap sama, OpenClaw menggunakan kembali root +terbaik yang ada untuk tuple akun/homeserver/pengguna tersebut sehingga status sinkronisasi sebelumnya, status crypto, thread bindings, +dan status verifikasi startup tetap terlihat. + +### Model crypto store Node + +Matrix E2EE di plugin ini menggunakan jalur Rust crypto `matrix-js-sdk` resmi di Node. +Jalur tersebut mengharapkan persistensi berbasis IndexedDB saat Anda ingin status crypto tetap bertahan setelah restart. + +Saat ini OpenClaw menyediakannya di Node dengan cara: + +- menggunakan `fake-indexeddb` sebagai shim API IndexedDB yang diharapkan SDK +- memulihkan isi IndexedDB Rust crypto dari `crypto-idb-snapshot.json` sebelum `initRustCrypto` +- mempertahankan isi IndexedDB yang diperbarui kembali ke `crypto-idb-snapshot.json` setelah init dan selama runtime +- menserialisasikan pemulihan dan persist snapshot terhadap `crypto-idb-snapshot.json` dengan advisory file lock agar persistensi runtime gateway dan pemeliharaan CLI tidak saling balapan pada file snapshot yang sama + +Ini adalah plumbing kompatibilitas/penyimpanan, bukan implementasi crypto kustom. +File snapshot adalah status runtime sensitif dan disimpan dengan izin file yang ketat. +Dalam model keamanan OpenClaw, host gateway dan direktori status OpenClaw lokal sudah berada di dalam batas operator tepercaya, jadi ini terutama merupakan persoalan durabilitas operasional, bukan batas kepercayaan jarak jauh yang terpisah. + +Peningkatan yang direncanakan: + +- menambahkan dukungan SecretRef untuk materi key Matrix persisten sehingga recovery key dan secret enkripsi store terkait dapat bersumber dari penyedia secret OpenClaw, bukan hanya file lokal + +## Manajemen profil + +Perbarui self-profile Matrix untuk akun yang dipilih dengan: + +```bash +openclaw matrix profile set --name "OpenClaw Assistant" +openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png +``` + +Tambahkan `--account ` saat Anda ingin secara eksplisit menargetkan akun Matrix bernama. + +Matrix menerima URL avatar `mxc://` secara langsung. Saat Anda meneruskan URL avatar `http://` atau `https://`, OpenClaw akan mengunggahnya ke Matrix terlebih dahulu dan menyimpan kembali URL `mxc://` yang sudah diresolusikan ke `channels.matrix.avatarUrl` (atau override akun yang dipilih). + +## Pemberitahuan verifikasi otomatis + +Matrix sekarang memposting pemberitahuan siklus hidup verifikasi langsung ke room verifikasi DM ketat sebagai pesan `m.notice`. +Ini mencakup: + +- pemberitahuan permintaan verifikasi +- pemberitahuan verifikasi siap (dengan panduan eksplisit "Verify by emoji") +- pemberitahuan mulai dan selesai verifikasi +- detail SAS (emoji dan desimal) bila tersedia + +Permintaan verifikasi masuk dari klien Matrix lain dilacak dan diterima otomatis oleh OpenClaw. +Untuk alur self-verification, OpenClaw juga memulai alur SAS secara otomatis saat verifikasi emoji tersedia dan mengonfirmasi sisinya sendiri. +Untuk permintaan verifikasi dari pengguna/perangkat Matrix lain, OpenClaw menerima permintaan secara otomatis lalu menunggu alur SAS berjalan secara normal. +Anda tetap perlu membandingkan emoji atau SAS desimal di klien Matrix Anda dan mengonfirmasi "They match" di sana untuk menyelesaikan verifikasi. + +OpenClaw tidak menerima otomatis alur duplikat yang dimulai sendiri secara membabi buta. Startup melewati pembuatan permintaan baru saat permintaan self-verification sudah tertunda. + +Pemberitahuan protokol/sistem verifikasi tidak diteruskan ke pipeline chat agen, sehingga tidak menghasilkan `NO_REPLY`. + +### Kebersihan perangkat + +Perangkat Matrix yang dikelola OpenClaw lama dapat menumpuk di akun dan membuat kepercayaan room terenkripsi lebih sulit dipahami. +Daftarkan perangkat tersebut dengan: + +```bash +openclaw matrix devices list +``` + +Hapus perangkat OpenClaw terkelola yang usang dengan: + +```bash +openclaw matrix devices prune-stale +``` + +### Perbaikan Direct Room + +Jika status direct-message tidak sinkron, OpenClaw dapat berakhir dengan pemetaan `m.direct` usang yang menunjuk ke room solo lama, bukan DM aktif. Periksa pemetaan saat ini untuk peer dengan: + +```bash +openclaw matrix direct inspect --user-id @alice:example.org +``` + +Perbaiki dengan: + +```bash +openclaw matrix direct repair --user-id @alice:example.org +``` + +Perbaikan menjaga logika khusus Matrix tetap berada di dalam plugin: + +- plugin mengutamakan DM 1:1 ketat yang sudah dipetakan di `m.direct` +- jika tidak, plugin kembali ke DM 1:1 ketat mana pun yang saat ini sudah diikuti dengan pengguna tersebut +- jika tidak ada DM sehat, plugin membuat direct room baru dan menulis ulang `m.direct` agar menunjuk ke room tersebut + +Alur perbaikan tidak menghapus room lama secara otomatis. Alur ini hanya memilih DM yang sehat dan memperbarui pemetaan agar pengiriman Matrix baru, pemberitahuan verifikasi, dan alur direct-message lainnya kembali menargetkan room yang benar. + +## Thread + +Matrix mendukung thread Matrix native untuk balasan otomatis dan pengiriman alat pesan. + +- `threadReplies: "off"` menjaga balasan tetap di tingkat atas dan menjaga pesan ber-thread masuk tetap pada sesi induk. +- `threadReplies: "inbound"` membalas di dalam thread hanya saat pesan masuk sudah berada di thread tersebut. +- `threadReplies: "always"` menjaga balasan room tetap di thread yang berakar pada pesan pemicu dan merutekan percakapan tersebut melalui sesi bercakupan thread yang cocok dari pesan pemicu pertama. +- `dm.threadReplies` menimpa setelan tingkat atas hanya untuk DM. Misalnya, Anda dapat menjaga thread room tetap terisolasi sambil menjaga DM tetap datar. +- Pesan ber-thread masuk menyertakan pesan akar thread sebagai konteks agen tambahan. +- Pengiriman alat pesan kini otomatis mewarisi thread Matrix saat ini ketika targetnya adalah room yang sama, atau target pengguna DM yang sama, kecuali jika `threadId` eksplisit diberikan. +- Thread bindings saat runtime didukung untuk Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, dan `/acp spawn` terikat thread kini berfungsi di room dan DM Matrix. +- `/focus` room/DM Matrix tingkat atas membuat thread Matrix baru dan mengikatnya ke sesi target saat `threadBindings.spawnSubagentSessions=true`. +- Menjalankan `/focus` atau `/acp spawn --thread here` di dalam thread Matrix yang sudah ada akan mengikat thread saat ini sebagai gantinya. + +## Binding percakapan ACP + +Room, DM, dan thread Matrix yang sudah ada dapat diubah menjadi workspace ACP yang persisten tanpa mengubah permukaan chat. + +Alur operator cepat: + +- Jalankan `/acp spawn codex --bind here` di dalam DM Matrix, room, atau thread yang sudah ada yang ingin terus Anda gunakan. +- Di DM atau room Matrix tingkat atas, DM/room saat ini tetap menjadi permukaan chat dan pesan berikutnya dirutekan ke sesi ACP yang telah di-spawn. +- Di dalam thread Matrix yang sudah ada, `--bind here` mengikat thread saat ini di tempat. +- `/new` dan `/reset` mereset sesi ACP terikat yang sama di tempat. +- `/acp close` menutup sesi ACP dan menghapus binding. + +Catatan: + +- `--bind here` tidak membuat thread Matrix turunan. +- `threadBindings.spawnAcpSessions` hanya diperlukan untuk `/acp spawn --thread auto|here`, saat OpenClaw perlu membuat atau mengikat thread Matrix turunan. + +### Konfigurasi Thread Binding + +Matrix mewarisi default global dari `session.threadBindings`, dan juga mendukung override per channel: + +- `threadBindings.enabled` +- `threadBindings.idleHours` +- `threadBindings.maxAgeHours` +- `threadBindings.spawnSubagentSessions` +- `threadBindings.spawnAcpSessions` + +Flag spawn terikat thread Matrix bersifat opt-in: + +- Tetapkan `threadBindings.spawnSubagentSessions: true` untuk mengizinkan `/focus` tingkat atas membuat dan mengikat thread Matrix baru. +- Tetapkan `threadBindings.spawnAcpSessions: true` untuk mengizinkan `/acp spawn --thread auto|here` mengikat sesi ACP ke thread Matrix. + +## Reaksi + +Matrix mendukung tindakan reaksi keluar, notifikasi reaksi masuk, dan reaksi ack masuk. + +- Tooling reaksi keluar digate oleh `channels["matrix"].actions.reactions`. +- `react` menambahkan reaksi ke event Matrix tertentu. +- `reactions` mencantumkan ringkasan reaksi saat ini untuk event Matrix tertentu. +- `emoji=""` menghapus reaksi milik akun bot sendiri pada event tersebut. +- `remove: true` hanya menghapus reaksi emoji yang ditentukan dari akun bot. + +Cakupan reaksi ack diresolusikan dalam urutan standar OpenClaw: + +- `channels["matrix"].accounts..ackReaction` +- `channels["matrix"].ackReaction` +- `messages.ackReaction` +- fallback emoji identitas agen + +Cakupan reaksi ack diresolusikan dalam urutan ini: + +- `channels["matrix"].accounts..ackReactionScope` +- `channels["matrix"].ackReactionScope` +- `messages.ackReactionScope` + +Mode notifikasi reaksi diresolusikan dalam urutan ini: + +- `channels["matrix"].accounts..reactionNotifications` +- `channels["matrix"].reactionNotifications` +- default: `own` + +Perilaku saat ini: + +- `reactionNotifications: "own"` meneruskan event `m.reaction` yang ditambahkan saat event tersebut menargetkan pesan Matrix buatan bot. +- `reactionNotifications: "off"` menonaktifkan event sistem reaksi. +- Penghapusan reaksi masih belum disintesis menjadi event sistem karena Matrix menampilkannya sebagai redaksi, bukan sebagai penghapusan `m.reaction` mandiri. + +## Konteks riwayat + +- `channels.matrix.historyLimit` mengontrol berapa banyak pesan room terbaru yang disertakan sebagai `InboundHistory` saat pesan room Matrix memicu agen. +- Ini kembali ke `messages.groupChat.historyLimit`. Tetapkan `0` untuk menonaktifkan. +- Riwayat room Matrix hanya untuk room. DM tetap menggunakan riwayat sesi normal. +- Riwayat room Matrix bersifat pending-only: OpenClaw men-buffer pesan room yang belum memicu balasan, lalu mengambil snapshot jendela tersebut saat mention atau pemicu lain tiba. +- Pesan pemicu saat ini tidak disertakan dalam `InboundHistory`; pesan tersebut tetap berada di body masuk utama untuk giliran itu. +- Percobaan ulang event Matrix yang sama menggunakan kembali snapshot riwayat asli alih-alih bergeser maju ke pesan room yang lebih baru. + +## Visibilitas konteks + +Matrix mendukung kontrol `contextVisibility` bersama untuk konteks room tambahan seperti teks balasan yang diambil, akar thread, dan riwayat tertunda. + +- `contextVisibility: "all"` adalah default. Konteks tambahan dipertahankan sebagaimana diterima. +- `contextVisibility: "allowlist"` memfilter konteks tambahan ke pengirim yang diizinkan oleh pemeriksaan allowlist room/pengguna aktif. +- `contextVisibility: "allowlist_quote"` berperilaku seperti `allowlist`, tetapi tetap menyimpan satu balasan kutipan eksplisit. + +Setelan ini memengaruhi visibilitas konteks tambahan, bukan apakah pesan masuk itu sendiri dapat memicu balasan. +Otorisasi pemicu tetap berasal dari setelan `groupPolicy`, `groups`, `groupAllowFrom`, dan kebijakan DM. + +## Contoh kebijakan DM dan room + +```json5 +{ + channels: { + matrix: { + dm: { + policy: "allowlist", + allowFrom: ["@admin:example.org"], + threadReplies: "off", + }, + groupPolicy: "allowlist", + groupAllowFrom: ["@admin:example.org"], + groups: { + "!roomid:example.org": { + requireMention: true, + }, + }, + }, + }, +} +``` + +Lihat [Groups](/channels/groups) untuk perilaku penggatingan mention dan allowlist. + +Contoh pairing untuk DM Matrix: + +```bash +openclaw pairing list matrix +openclaw pairing approve matrix +``` + +Jika pengguna Matrix yang belum disetujui terus mengirim pesan kepada Anda sebelum persetujuan, OpenClaw menggunakan kembali kode pairing tertunda yang sama dan dapat mengirim balasan pengingat lagi setelah cooldown singkat alih-alih mencetak kode baru. + +Lihat [Pairing](/channels/pairing) untuk alur pairing DM dan tata letak penyimpanan bersama. + +## Persetujuan exec + +Matrix dapat bertindak sebagai klien persetujuan exec untuk akun Matrix. + +- `channels.matrix.execApprovals.enabled` +- `channels.matrix.execApprovals.approvers` (opsional; kembali ke `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`) +- `channels.matrix.execApprovals.agentFilter` +- `channels.matrix.execApprovals.sessionFilter` + +Approver harus berupa ID pengguna Matrix seperti `@owner:example.org`. Matrix otomatis mengaktifkan persetujuan exec native saat `enabled` tidak ditetapkan atau `"auto"` dan setidaknya satu approver dapat diresolusikan, baik dari `execApprovals.approvers` atau dari `channels.matrix.dm.allowFrom`. Tetapkan `enabled: false` untuk menonaktifkan Matrix sebagai klien persetujuan native secara eksplisit. Jika tidak, permintaan persetujuan kembali ke rute persetujuan lain yang dikonfigurasi atau ke kebijakan fallback persetujuan exec. + +Perutean native Matrix saat ini hanya untuk exec: + +- `channels.matrix.execApprovals.*` mengontrol perutean DM/channel native hanya untuk persetujuan exec. +- Persetujuan plugin tetap menggunakan `/approve` di chat yang sama bersama dengan forwarding `approvals.plugin` yang dikonfigurasi. +- Matrix tetap dapat menggunakan kembali `channels.matrix.dm.allowFrom` untuk otorisasi persetujuan plugin saat Matrix dapat menyimpulkan approver dengan aman, tetapi Matrix tidak mengekspos jalur fanout DM/channel persetujuan plugin native yang terpisah. + +Aturan pengiriman: + +- `target: "dm"` mengirim prompt persetujuan ke DM approver +- `target: "channel"` mengirim prompt kembali ke room atau DM Matrix asal +- `target: "both"` mengirim ke DM approver dan room atau DM Matrix asal + +Saat ini Matrix menggunakan prompt persetujuan berbasis teks. Approver menyelesaikannya dengan `/approve allow-once`, `/approve allow-always`, atau `/approve deny`. + +Hanya approver yang teresolusikan yang dapat menyetujui atau menolak. Pengiriman ke channel menyertakan teks perintah, jadi aktifkan `channel` atau `both` hanya di room tepercaya. + +Prompt persetujuan Matrix menggunakan kembali planner persetujuan inti bersama. Permukaan native khusus Matrix hanyalah transport untuk persetujuan exec: perutean room/DM dan perilaku kirim/perbarui/hapus pesan. + +Override per akun: + +- `channels.matrix.accounts..execApprovals` + +Dokumentasi terkait: [Persetujuan exec](/tools/exec-approvals) + +## Contoh multi-akun + +```json5 +{ + channels: { + matrix: { + enabled: true, + defaultAccount: "assistant", + dm: { policy: "pairing" }, + accounts: { + assistant: { + homeserver: "https://matrix.example.org", + accessToken: "syt_assistant_xxx", + encryption: true, + }, + alerts: { + homeserver: "https://matrix.example.org", + accessToken: "syt_alerts_xxx", + dm: { + policy: "allowlist", + allowFrom: ["@ops:example.org"], + threadReplies: "off", + }, + }, + }, + }, + }, +} +``` + +Nilai `channels.matrix` tingkat atas bertindak sebagai default untuk akun bernama kecuali jika sebuah akun menimpanya. +Anda dapat mencakup entri room turunan ke satu akun Matrix dengan `groups..account` (atau `rooms..account` lama). +Entri tanpa `account` tetap dibagikan di semua akun Matrix, dan entri dengan `account: "default"` tetap berfungsi saat akun default dikonfigurasi langsung di `channels.matrix.*` tingkat atas. +Default auth bersama parsial tidak dengan sendirinya membuat akun default implisit terpisah. OpenClaw hanya mensintesis akun tingkat atas `default` saat default tersebut memiliki auth yang baru (`homeserver` plus `accessToken`, atau `homeserver` plus `userId` dan `password`); akun bernama tetap dapat ditemukan dari `homeserver` plus `userId` saat kredensial cache memenuhi auth nanti. +Jika Matrix sudah memiliki tepat satu akun bernama, atau `defaultAccount` menunjuk ke kunci akun bernama yang sudah ada, promosi perbaikan/penyiapan dari akun tunggal ke multi-akun mempertahankan akun tersebut alih-alih membuat entri `accounts.default` baru. Hanya kunci auth/bootstrap Matrix yang dipindahkan ke akun yang dipromosikan itu; kunci kebijakan pengiriman bersama tetap di tingkat atas. +Tetapkan `defaultAccount` saat Anda ingin OpenClaw mengutamakan satu akun Matrix bernama untuk perutean implisit, probing, dan operasi CLI. +Jika Anda mengonfigurasi beberapa akun bernama, tetapkan `defaultAccount` atau teruskan `--account ` untuk perintah CLI yang bergantung pada pemilihan akun implisit. +Teruskan `--account ` ke `openclaw matrix verify ...` dan `openclaw matrix devices ...` saat Anda ingin menimpa pemilihan implisit tersebut untuk satu perintah. + +## Homeserver privat/LAN + +Secara default, OpenClaw memblokir homeserver Matrix privat/internal untuk perlindungan SSRF kecuali Anda +secara eksplisit melakukan opt-in per akun. + +Jika homeserver Anda berjalan di localhost, IP LAN/Tailscale, atau hostname internal, aktifkan +`allowPrivateNetwork` untuk akun Matrix tersebut: + +```json5 +{ + channels: { + matrix: { + homeserver: "http://matrix-synapse:8008", + allowPrivateNetwork: true, + accessToken: "syt_internal_xxx", + }, + }, +} +``` + +Contoh penyiapan CLI: + +```bash +openclaw matrix account add \ + --account ops \ + --homeserver http://matrix-synapse:8008 \ + --allow-private-network \ + --access-token syt_ops_xxx +``` + +Opt-in ini hanya mengizinkan target privat/internal tepercaya. Homeserver cleartext publik seperti +`http://matrix.example.org:8008` tetap diblokir. Utamakan `https://` bila memungkinkan. + +## Mem-proxy lalu lintas Matrix + +Jika deployment Matrix Anda memerlukan proxy HTTP(S) keluar eksplisit, tetapkan `channels.matrix.proxy`: + +```json5 +{ + channels: { + matrix: { + homeserver: "https://matrix.example.org", + accessToken: "syt_bot_xxx", + proxy: "http://127.0.0.1:7890", + }, + }, +} +``` + +Akun bernama dapat menimpa default tingkat atas dengan `channels.matrix.accounts..proxy` miliknya sendiri. +OpenClaw menggunakan setelan proxy yang sama untuk lalu lintas Matrix saat runtime dan probe status akun. + +## Resolusi target + +Matrix menerima bentuk target ini di mana pun OpenClaw meminta target room atau pengguna: + +- Pengguna: `@user:server`, `user:@user:server`, atau `matrix:user:@user:server` +- Room: `!room:server`, `room:!room:server`, atau `matrix:room:!room:server` +- Alias: `#alias:server`, `channel:#alias:server`, atau `matrix:channel:#alias:server` + +Lookup direktori live menggunakan akun Matrix yang sudah login: + +- Lookup pengguna mengueri direktori pengguna Matrix di homeserver tersebut. +- Lookup room menerima ID room dan alias eksplisit secara langsung, lalu kembali ke pencarian nama room yang sudah diikuti untuk akun tersebut. +- Lookup nama room yang sudah diikuti bersifat best-effort. Jika nama room tidak dapat diresolusikan menjadi ID atau alias, nama tersebut diabaikan oleh resolusi allowlist saat runtime. + +## Referensi konfigurasi + +- `enabled`: aktifkan atau nonaktifkan channel. +- `name`: label opsional untuk akun. +- `defaultAccount`: ID akun pilihan saat beberapa akun Matrix dikonfigurasi. +- `homeserver`: URL homeserver, misalnya `https://matrix.example.org`. +- `allowPrivateNetwork`: izinkan akun Matrix ini terhubung ke homeserver privat/internal. Aktifkan ini saat homeserver diresolusikan ke `localhost`, IP LAN/Tailscale, atau host internal seperti `matrix-synapse`. +- `proxy`: URL proxy HTTP(S) opsional untuk lalu lintas Matrix. Akun bernama dapat menimpa default tingkat atas dengan `proxy` miliknya sendiri. +- `userId`: ID pengguna Matrix penuh, misalnya `@bot:example.org`. +- `accessToken`: access token untuk auth berbasis token. Nilai plaintext dan SecretRef didukung untuk `channels.matrix.accessToken` dan `channels.matrix.accounts..accessToken` di seluruh penyedia env/file/exec. Lihat [Secrets Management](/gateway/secrets). +- `password`: password untuk login berbasis password. Nilai plaintext dan SecretRef didukung. +- `deviceId`: ID perangkat Matrix eksplisit. +- `deviceName`: nama tampilan perangkat untuk login password. +- `avatarUrl`: URL avatar diri yang tersimpan untuk sinkronisasi profil dan pembaruan `set-profile`. +- `initialSyncLimit`: batas event sinkronisasi saat startup. +- `encryption`: aktifkan E2EE. +- `allowlistOnly`: paksa perilaku hanya-allowlist untuk DM dan room. +- `allowBots`: izinkan pesan dari akun Matrix OpenClaw lain yang dikonfigurasi (`true` atau `"mentions"`). +- `groupPolicy`: `open`, `allowlist`, atau `disabled`. +- `contextVisibility`: mode visibilitas konteks room tambahan (`all`, `allowlist`, `allowlist_quote`). +- `groupAllowFrom`: allowlist ID pengguna untuk lalu lintas room. +- Entri `groupAllowFrom` harus berupa ID pengguna Matrix penuh. Nama yang tidak teresolusikan diabaikan saat runtime. +- `historyLimit`: jumlah maksimum pesan room yang disertakan sebagai konteks riwayat grup. Kembali ke `messages.groupChat.historyLimit`. Tetapkan `0` untuk menonaktifkan. +- `replyToMode`: `off`, `first`, atau `all`. +- `markdown`: konfigurasi rendering Markdown opsional untuk teks Matrix keluar. +- `streaming`: `off` (default), `partial`, `true`, atau `false`. `partial` dan `true` mengaktifkan pratinjau draf satu pesan dengan pembaruan edit-di-tempat. +- `blockStreaming`: `true` mengaktifkan pesan progres terpisah untuk blok asisten yang selesai saat streaming pratinjau draf aktif. +- `threadReplies`: `off`, `inbound`, atau `always`. +- `threadBindings`: override per channel untuk perutean sesi terikat thread dan siklus hidupnya. +- `startupVerification`: mode permintaan self-verification otomatis saat startup (`if-unverified`, `off`). +- `startupVerificationCooldownHours`: cooldown sebelum mencoba ulang permintaan verifikasi startup otomatis. +- `textChunkLimit`: ukuran chunk pesan keluar. +- `chunkMode`: `length` atau `newline`. +- `responsePrefix`: prefiks pesan opsional untuk balasan keluar. +- `ackReaction`: override reaksi ack opsional untuk channel/akun ini. +- `ackReactionScope`: override cakupan reaksi ack opsional (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `reactionNotifications`: mode notifikasi reaksi masuk (`own`, `off`). +- `mediaMaxMb`: batas ukuran media dalam MB untuk penanganan media Matrix. Berlaku untuk pengiriman keluar dan pemrosesan media masuk. +- `autoJoin`: kebijakan auto-join undangan (`always`, `allowlist`, `off`). Default: `off`. +- `autoJoinAllowlist`: room/alias yang diizinkan saat `autoJoin` adalah `allowlist`. Entri alias diresolusikan menjadi ID room selama penanganan undangan; OpenClaw tidak mempercayai status alias yang diklaim oleh room yang mengundang. +- `dm`: blok kebijakan DM (`enabled`, `policy`, `allowFrom`, `threadReplies`). +- Entri `dm.allowFrom` harus berupa ID pengguna Matrix penuh kecuali Anda sudah meresolusikannya melalui lookup direktori live. +- `dm.threadReplies`: override kebijakan thread khusus DM (`off`, `inbound`, `always`). Menimpa setelan `threadReplies` tingkat atas untuk penempatan balasan dan isolasi sesi di DM. +- `execApprovals`: pengiriman persetujuan exec native Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: ID pengguna Matrix yang diizinkan menyetujui permintaan exec. Opsional jika `dm.allowFrom` sudah mengidentifikasi approver. +- `execApprovals.target`: `dm | channel | both` (default: `dm`). +- `accounts`: override bernama per akun. Nilai `channels.matrix` tingkat atas bertindak sebagai default untuk entri ini. +- `groups`: peta kebijakan per room. Utamakan ID room atau alias; nama room yang tidak teresolusikan diabaikan saat runtime. Identitas sesi/grup menggunakan ID room stabil setelah resolusi, sementara label yang dapat dibaca manusia tetap berasal dari nama room. +- `groups..account`: batasi satu entri room turunan ke akun Matrix tertentu dalam penyiapan multi-akun. +- `groups..allowBots`: override tingkat room untuk pengirim bot yang dikonfigurasi (`true` atau `"mentions"`). +- `groups..users`: allowlist pengirim per room. +- `groups..tools`: override izinkan/tolak alat per room. +- `groups..autoReply`: override penggatingan mention tingkat room. `true` menonaktifkan persyaratan mention untuk room tersebut; `false` memaksanya aktif kembali. +- `groups..skills`: filter skill tingkat room opsional. +- `groups..systemPrompt`: cuplikan system prompt tingkat room opsional. +- `rooms`: alias lama untuk `groups`. +- `actions`: gating alat per tindakan (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku chat grup dan penggatingan mention +- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/mattermost.md b/docs/id/channels/mattermost.md new file mode 100644 index 000000000..6480d0c6d --- /dev/null +++ b/docs/id/channels/mattermost.md @@ -0,0 +1,479 @@ +--- +read_when: + - Menyiapkan Mattermost + - Men-debug routing Mattermost +summary: Penyiapan bot Mattermost dan konfigurasi OpenClaw +title: Mattermost +x-i18n: + generated_at: "2026-04-05T13:44:13Z" + model: gpt-5.4 + provider: openai + source_hash: f21dc7543176fda0b38b00fab60f0daae38dffcf68fa1cf7930a9f14ec57cb5a + source_path: channels/mattermost.md + workflow: 15 +--- + +# Mattermost + +Status: plugin bawaan (token bot + event WebSocket). Channel, grup, dan DM didukung. +Mattermost adalah platform perpesanan tim yang dapat di-host sendiri; lihat situs resmi di +[mattermost.com](https://mattermost.com) untuk detail produk dan unduhan. + +## Plugin bawaan + +Mattermost dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build +paket normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Mattermost, +instal secara manual: + +Instal melalui CLI (registry npm): + +```bash +openclaw plugins install @openclaw/mattermost +``` + +Checkout lokal (saat berjalan dari repo git): + +```bash +openclaw plugins install ./path/to/local/mattermost-plugin +``` + +Detail: [Plugins](/tools/plugin) + +## Penyiapan cepat + +1. Pastikan plugin Mattermost tersedia. + - Rilis OpenClaw terpaket saat ini sudah menyertakannya. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Buat akun bot Mattermost dan salin **token bot**. +3. Salin **URL dasar** Mattermost (misalnya `https://chat.example.com`). +4. Konfigurasikan OpenClaw dan jalankan gateway. + +Konfigurasi minimal: + +```json5 +{ + channels: { + mattermost: { + enabled: true, + botToken: "mm-token", + baseUrl: "https://chat.example.com", + dmPolicy: "pairing", + }, + }, +} +``` + +## Native slash commands + +Native slash commands bersifat opt-in. Saat diaktifkan, OpenClaw mendaftarkan slash command `oc_*` melalui +Mattermost API dan menerima POST callback pada server HTTP gateway. + +```json5 +{ + channels: { + mattermost: { + commands: { + native: true, + nativeSkills: true, + callbackPath: "/api/channels/mattermost/command", + // Gunakan saat Mattermost tidak dapat menjangkau gateway secara langsung (reverse proxy/URL publik). + callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", + }, + }, + }, +} +``` + +Catatan: + +- `native: "auto"` secara default dinonaktifkan untuk Mattermost. Setel `native: true` untuk mengaktifkannya. +- Jika `callbackUrl` dihilangkan, OpenClaw akan menurunkannya dari host/port gateway + `callbackPath`. +- Untuk penyiapan multi-akun, `commands` dapat disetel di tingkat atas atau di bawah + `channels.mattermost.accounts..commands` (nilai akun menimpa field tingkat atas). +- Callback perintah divalidasi dengan token per perintah yang dikembalikan oleh + Mattermost saat OpenClaw mendaftarkan perintah `oc_*`. +- Callback slash gagal secara tertutup saat pendaftaran gagal, startup parsial, atau + token callback tidak cocok dengan salah satu perintah yang terdaftar. +- Persyaratan keterjangkauan: endpoint callback harus dapat dijangkau dari server Mattermost. + - Jangan setel `callbackUrl` ke `localhost` kecuali Mattermost berjalan pada host/network namespace yang sama dengan OpenClaw. + - Jangan setel `callbackUrl` ke URL dasar Mattermost Anda kecuali URL tersebut melakukan reverse-proxy `/api/channels/mattermost/command` ke OpenClaw. + - Pemeriksaan cepat: `curl https:///api/channels/mattermost/command`; GET harus mengembalikan `405 Method Not Allowed` dari OpenClaw, bukan `404`. +- Persyaratan allowlist egress Mattermost: + - Jika callback Anda menargetkan alamat privat/tailnet/internal, setel Mattermost + `ServiceSettings.AllowedUntrustedInternalConnections` agar menyertakan host/domain callback. + - Gunakan entri host/domain, bukan URL lengkap. + - Baik: `gateway.tailnet-name.ts.net` + - Buruk: `https://gateway.tailnet-name.ts.net` + +## Variabel lingkungan (akun default) + +Setel ini pada host gateway jika Anda lebih memilih env var: + +- `MATTERMOST_BOT_TOKEN=...` +- `MATTERMOST_URL=https://chat.example.com` + +Env var hanya berlaku untuk akun **default** (`default`). Akun lain harus menggunakan nilai konfigurasi. + +## Mode chat + +Mattermost merespons DM secara otomatis. Perilaku channel dikendalikan oleh `chatmode`: + +- `oncall` (default): hanya merespons saat di-@mention di channel. +- `onmessage`: merespons setiap pesan channel. +- `onchar`: merespons saat pesan dimulai dengan prefiks pemicu. + +Contoh konfigurasi: + +```json5 +{ + channels: { + mattermost: { + chatmode: "onchar", + oncharPrefixes: [">", "!"], + }, + }, +} +``` + +Catatan: + +- `onchar` tetap merespons @mention eksplisit. +- `channels.mattermost.requireMention` dihormati untuk konfigurasi lama, tetapi `chatmode` lebih disukai. + +## Threading dan sesi + +Gunakan `channels.mattermost.replyToMode` untuk mengontrol apakah balasan channel dan grup tetap berada di +channel utama atau memulai thread di bawah post pemicu. + +- `off` (default): hanya membalas dalam thread saat post masuk memang sudah berada di thread. +- `first`: untuk post channel/grup tingkat atas, mulai thread di bawah post tersebut dan rutekan + percakapan ke sesi dengan cakupan thread. +- `all`: perilakunya sama dengan `first` untuk Mattermost saat ini. +- Pesan langsung mengabaikan pengaturan ini dan tetap non-threaded. + +Contoh konfigurasi: + +```json5 +{ + channels: { + mattermost: { + replyToMode: "all", + }, + }, +} +``` + +Catatan: + +- Sesi dengan cakupan thread menggunakan id post pemicu sebagai akar thread. +- `first` dan `all` saat ini setara karena setelah Mattermost memiliki akar thread, + chunk lanjutan dan media akan tetap berada di thread yang sama. + +## Kontrol akses (DM) + +- Default: `channels.mattermost.dmPolicy = "pairing"` (pengirim yang tidak dikenal mendapatkan kode pairing). +- Setujui melalui: + - `openclaw pairing list mattermost` + - `openclaw pairing approve mattermost ` +- DM publik: `channels.mattermost.dmPolicy="open"` plus `channels.mattermost.allowFrom=["*"]`. + +## Channel (grup) + +- Default: `channels.mattermost.groupPolicy = "allowlist"` (dibatasi mention). +- Allowlist pengirim dengan `channels.mattermost.groupAllowFrom` (ID pengguna direkomendasikan). +- Override mention per channel ada di bawah `channels.mattermost.groups..requireMention` + atau `channels.mattermost.groups["*"].requireMention` sebagai default. +- Pencocokan `@username` bersifat dapat berubah dan hanya diaktifkan saat `channels.mattermost.dangerouslyAllowNameMatching: true`. +- Channel terbuka: `channels.mattermost.groupPolicy="open"` (dibatasi mention). +- Catatan runtime: jika `channels.mattermost` sama sekali tidak ada, runtime akan fallback ke `groupPolicy="allowlist"` untuk pemeriksaan grup (bahkan jika `channels.defaults.groupPolicy` disetel). + +Contoh: + +```json5 +{ + channels: { + mattermost: { + groupPolicy: "open", + groups: { + "*": { requireMention: true }, + "team-channel-id": { requireMention: false }, + }, + }, + }, +} +``` + +## Target untuk pengiriman keluar + +Gunakan format target ini dengan `openclaw message send` atau cron/webhook: + +- `channel:` untuk channel +- `user:` untuk DM +- `@username` untuk DM (di-resolve melalui Mattermost API) + +ID opak biasa (seperti `64ifufp...`) **ambigu** di Mattermost (ID pengguna vs ID channel). + +OpenClaw me-resolve-nya dengan prioritas **pengguna terlebih dahulu**: + +- Jika ID ada sebagai pengguna (`GET /api/v4/users/` berhasil), OpenClaw mengirim **DM** dengan me-resolve channel langsung melalui `/api/v4/channels/direct`. +- Jika tidak, ID diperlakukan sebagai **ID channel**. + +Jika Anda membutuhkan perilaku deterministik, selalu gunakan prefiks eksplisit (`user:` / `channel:`). + +## Percobaan ulang channel DM + +Saat OpenClaw mengirim ke target DM Mattermost dan perlu me-resolve channel langsung terlebih dahulu, OpenClaw +secara default mencoba ulang kegagalan sementara pada pembuatan channel langsung. + +Gunakan `channels.mattermost.dmChannelRetry` untuk menyetel perilaku itu secara global untuk plugin Mattermost, +atau `channels.mattermost.accounts..dmChannelRetry` untuk satu akun. + +```json5 +{ + channels: { + mattermost: { + dmChannelRetry: { + maxRetries: 3, + initialDelayMs: 1000, + maxDelayMs: 10000, + timeoutMs: 30000, + }, + }, + }, +} +``` + +Catatan: + +- Ini hanya berlaku untuk pembuatan channel DM (`/api/v4/channels/direct`), bukan setiap panggilan Mattermost API. +- Percobaan ulang berlaku untuk kegagalan sementara seperti rate limit, respons 5xx, dan kesalahan jaringan atau timeout. +- Kesalahan klien 4xx selain `429` diperlakukan sebagai permanen dan tidak dicoba ulang. + +## Reaksi (message tool) + +- Gunakan `message action=react` dengan `channel=mattermost`. +- `messageId` adalah id post Mattermost. +- `emoji` menerima nama seperti `thumbsup` atau `:+1:` (titik dua opsional). +- Setel `remove=true` (boolean) untuk menghapus reaksi. +- Event tambah/hapus reaksi diteruskan sebagai event sistem ke sesi agent yang dirutekan. + +Contoh: + +``` +message action=react channel=mattermost target=channel: messageId= emoji=thumbsup +message action=react channel=mattermost target=channel: messageId= emoji=thumbsup remove=true +``` + +Konfigurasi: + +- `channels.mattermost.actions.reactions`: aktifkan/nonaktifkan tindakan reaksi (default true). +- Override per akun: `channels.mattermost.accounts..actions.reactions`. + +## Tombol interaktif (message tool) + +Kirim pesan dengan tombol yang dapat diklik. Saat pengguna mengklik tombol, agent menerima +pilihan tersebut dan dapat merespons. + +Aktifkan tombol dengan menambahkan `inlineButtons` ke capability channel: + +```json5 +{ + channels: { + mattermost: { + capabilities: ["inlineButtons"], + }, + }, +} +``` + +Gunakan `message action=send` dengan parameter `buttons`. Tombol adalah array 2D (baris tombol): + +``` +message action=send channel=mattermost target=channel: buttons=[[{"text":"Yes","callback_data":"yes"},{"text":"No","callback_data":"no"}]] +``` + +Field tombol: + +- `text` (wajib): label tampilan. +- `callback_data` (wajib): nilai yang dikirim kembali saat diklik (digunakan sebagai action ID). +- `style` (opsional): `"default"`, `"primary"`, atau `"danger"`. + +Saat pengguna mengklik tombol: + +1. Semua tombol diganti dengan baris konfirmasi (misalnya, "✓ **Yes** selected by @user"). +2. Agent menerima pilihan sebagai pesan masuk dan merespons. + +Catatan: + +- Callback tombol menggunakan verifikasi HMAC-SHA256 (otomatis, tidak perlu konfigurasi). +- Mattermost menghapus callback data dari respons API-nya (fitur keamanan), sehingga semua tombol + dihapus saat diklik — penghapusan sebagian tidak dimungkinkan. +- Action ID yang berisi tanda hubung atau garis bawah disanitasi secara otomatis + (keterbatasan routing Mattermost). + +Konfigurasi: + +- `channels.mattermost.capabilities`: array string capability. Tambahkan `"inlineButtons"` untuk + mengaktifkan deskripsi tool tombol dalam prompt sistem agent. +- `channels.mattermost.interactions.callbackBaseUrl`: URL dasar eksternal opsional untuk callback + tombol (misalnya `https://gateway.example.com`). Gunakan ini saat Mattermost tidak dapat + menjangkau gateway pada bind host-nya secara langsung. +- Dalam penyiapan multi-akun, Anda juga dapat menyetel field yang sama di bawah + `channels.mattermost.accounts..interactions.callbackBaseUrl`. +- Jika `interactions.callbackBaseUrl` dihilangkan, OpenClaw menurunkan URL callback dari + `gateway.customBindHost` + `gateway.port`, lalu fallback ke `http://localhost:`. +- Aturan keterjangkauan: URL callback tombol harus dapat dijangkau dari server Mattermost. + `localhost` hanya berfungsi jika Mattermost dan OpenClaw berjalan pada host/network namespace yang sama. +- Jika target callback Anda bersifat privat/tailnet/internal, tambahkan host/domain-nya ke Mattermost + `ServiceSettings.AllowedUntrustedInternalConnections`. + +### Integrasi API langsung (skrip eksternal) + +Skrip eksternal dan webhook dapat mem-posting tombol langsung melalui Mattermost REST API +alih-alih melalui `message` tool milik agent. Gunakan `buildButtonAttachments()` dari +ekstensi bila memungkinkan; jika mem-posting JSON mentah, ikuti aturan ini: + +**Struktur payload:** + +```json5 +{ + channel_id: "", + message: "Choose an option:", + props: { + attachments: [ + { + actions: [ + { + id: "mybutton01", // alfanumerik saja — lihat di bawah + type: "button", // wajib, atau klik akan diabaikan secara diam-diam + name: "Approve", // label tampilan + style: "primary", // opsional: "default", "primary", "danger" + integration: { + url: "https://gateway.example.com/mattermost/interactions/default", + context: { + action_id: "mybutton01", // harus cocok dengan id tombol (untuk lookup nama) + action: "approve", + // ... field kustom apa pun ... + _token: "", // lihat bagian HMAC di bawah + }, + }, + }, + ], + }, + ], + }, +} +``` + +**Aturan penting:** + +1. Attachment ditempatkan di `props.attachments`, bukan `attachments` tingkat atas (kalau tidak akan diabaikan secara diam-diam). +2. Setiap action memerlukan `type: "button"` — tanpa itu, klik akan tertelan secara diam-diam. +3. Setiap action memerlukan field `id` — Mattermost mengabaikan action tanpa ID. +4. `id` action harus **hanya alfanumerik** (`[a-zA-Z0-9]`). Tanda hubung dan garis bawah merusak + routing action sisi server Mattermost (mengembalikan 404). Hapus karakter tersebut sebelum digunakan. +5. `context.action_id` harus cocok dengan `id` tombol agar pesan konfirmasi menampilkan + nama tombol (misalnya, "Approve"), bukan ID mentah. +6. `context.action_id` wajib — handler interaksi mengembalikan 400 tanpanya. + +**Pembuatan token HMAC:** + +Gateway memverifikasi klik tombol dengan HMAC-SHA256. Skrip eksternal harus membuat token +yang cocok dengan logika verifikasi gateway: + +1. Turunkan secret dari token bot: + `HMAC-SHA256(key="openclaw-mattermost-interactions", data=botToken)` +2. Bangun objek context dengan semua field **kecuali** `_token`. +3. Serialisasikan dengan **kunci yang diurutkan** dan **tanpa spasi** (gateway menggunakan `JSON.stringify` + dengan kunci yang diurutkan, yang menghasilkan output ringkas). +4. Tanda tangani: `HMAC-SHA256(key=secret, data=serializedContext)` +5. Tambahkan hex digest yang dihasilkan sebagai `_token` dalam context. + +Contoh Python: + +```python +import hmac, hashlib, json + +secret = hmac.new( + b"openclaw-mattermost-interactions", + bot_token.encode(), hashlib.sha256 +).hexdigest() + +ctx = {"action_id": "mybutton01", "action": "approve"} +payload = json.dumps(ctx, sort_keys=True, separators=(",", ":")) +token = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() + +context = {**ctx, "_token": token} +``` + +Jebakan umum HMAC: + +- `json.dumps` Python secara default menambahkan spasi (`{"key": "val"}`). Gunakan + `separators=(",", ":")` agar cocok dengan output ringkas JavaScript (`{"key":"val"}`). +- Selalu tanda tangani **semua** field context (tanpa `_token`). Gateway menghapus `_token` lalu + menandatangani semua yang tersisa. Menandatangani subset akan menyebabkan kegagalan verifikasi diam-diam. +- Gunakan `sort_keys=True` — gateway mengurutkan kunci sebelum penandatanganan, dan Mattermost dapat + mengubah urutan field context saat menyimpan payload. +- Turunkan secret dari token bot (deterministik), bukan byte acak. Secret + harus sama di seluruh proses yang membuat tombol dan gateway yang memverifikasi. + +## Adapter direktori + +Plugin Mattermost menyertakan adapter direktori yang me-resolve nama channel dan pengguna +melalui Mattermost API. Ini memungkinkan target `#channel-name` dan `@username` dalam +`openclaw message send` dan pengiriman cron/webhook. + +Tidak diperlukan konfigurasi — adapter menggunakan token bot dari konfigurasi akun. + +## Multi-akun + +Mattermost mendukung beberapa akun di bawah `channels.mattermost.accounts`: + +```json5 +{ + channels: { + mattermost: { + accounts: { + default: { name: "Primary", botToken: "mm-token", baseUrl: "https://chat.example.com" }, + alerts: { name: "Alerts", botToken: "mm-token-2", baseUrl: "https://alerts.example.com" }, + }, + }, + }, +} +``` + +## Pemecahan masalah + +- Tidak ada balasan di channel: pastikan bot ada di channel dan sebut bot tersebut (oncall), gunakan prefiks pemicu (onchar), atau setel `chatmode: "onmessage"`. +- Kesalahan autentikasi: periksa token bot, URL dasar, dan apakah akun diaktifkan. +- Masalah multi-akun: env var hanya berlaku untuk akun `default`. +- Native slash commands mengembalikan `Unauthorized: invalid command token.`: OpenClaw + tidak menerima token callback. Penyebab umum: + - pendaftaran slash command gagal atau hanya selesai sebagian saat startup + - callback mengenai gateway/akun yang salah + - Mattermost masih memiliki perintah lama yang menunjuk ke target callback sebelumnya + - gateway direstart tanpa mengaktifkan kembali slash commands +- Jika native slash commands berhenti berfungsi, periksa log untuk + `mattermost: failed to register slash commands` atau + `mattermost: native slash commands enabled but no commands could be registered`. +- Jika `callbackUrl` dihilangkan dan log memperingatkan bahwa callback di-resolve ke + `http://127.0.0.1:18789/...`, URL tersebut kemungkinan hanya dapat dijangkau saat + Mattermost berjalan pada host/network namespace yang sama dengan OpenClaw. Setel + `commands.callbackUrl` eksplisit yang dapat dijangkau dari luar. +- Tombol muncul sebagai kotak putih: agent mungkin mengirim data tombol yang tidak valid. Pastikan setiap tombol memiliki field `text` dan `callback_data`. +- Tombol dirender tetapi klik tidak melakukan apa-apa: verifikasi `AllowedUntrustedInternalConnections` pada konfigurasi server Mattermost menyertakan `127.0.0.1 localhost`, dan `EnablePostActionIntegration` bernilai `true` di ServiceSettings. +- Tombol mengembalikan 404 saat diklik: `id` tombol kemungkinan berisi tanda hubung atau garis bawah. Router action Mattermost rusak pada ID non-alfanumerik. Gunakan hanya `[a-zA-Z0-9]`. +- Log gateway `invalid _token`: HMAC tidak cocok. Periksa bahwa Anda menandatangani semua field context (bukan subset), menggunakan kunci yang diurutkan, dan JSON ringkas (tanpa spasi). Lihat bagian HMAC di atas. +- Log gateway `missing _token in context`: field `_token` tidak ada dalam context tombol. Pastikan field tersebut disertakan saat membangun payload integrasi. +- Konfirmasi menampilkan ID mentah alih-alih nama tombol: `context.action_id` tidak cocok dengan `id` tombol. Setel keduanya ke nilai tersanitasi yang sama. +- Agent tidak mengetahui tombol: tambahkan `capabilities: ["inlineButtons"]` ke konfigurasi channel Mattermost. + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention +- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan +- [Security](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/msteams.md b/docs/id/channels/msteams.md new file mode 100644 index 000000000..6a42b9bed --- /dev/null +++ b/docs/id/channels/msteams.md @@ -0,0 +1,810 @@ +--- +read_when: + - Mengerjakan fitur channel Microsoft Teams +summary: Status dukungan bot Microsoft Teams, kapabilitas, dan konfigurasi +title: Microsoft Teams +x-i18n: + generated_at: "2026-04-05T13:44:53Z" + model: gpt-5.4 + provider: openai + source_hash: 99fc6e136893ec65dc85d3bc0c0d92134069a2f3b8cb4fcf66c14674399b3eaf + source_path: channels/msteams.md + workflow: 15 +--- + +# Microsoft Teams + +> "Tinggalkan semua harapan, hai kalian yang masuk ke sini." + +Diperbarui: 2026-01-21 + +Status: teks + lampiran DM didukung; pengiriman file channel/grup memerlukan `sharePointSiteId` + izin Graph (lihat [Mengirim file di obrolan grup](#sending-files-in-group-chats)). Poll dikirim melalui Adaptive Cards. Aksi pesan mengekspos `upload-file` secara eksplisit untuk pengiriman yang mengutamakan file. + +## Plugin bawaan + +Microsoft Teams dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi tidak diperlukan instalasi terpisah dalam build paket normal. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Teams bawaan, instal secara manual: + +```bash +openclaw plugins install @openclaw/msteams +``` + +Checkout lokal (saat berjalan dari repo git): + +```bash +openclaw plugins install ./path/to/local/msteams-plugin +``` + +Detail: [Plugins](/tools/plugin) + +## Penyiapan cepat (pemula) + +1. Pastikan plugin Microsoft Teams tersedia. + - Rilis OpenClaw paket saat ini sudah menyertakannya. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Buat **Azure Bot** (App ID + client secret + tenant ID). +3. Konfigurasikan OpenClaw dengan kredensial tersebut. +4. Ekspos `/api/messages` (default port 3978) melalui URL publik atau tunnel. +5. Instal paket aplikasi Teams dan jalankan gateway. + +Config minimal: + +```json5 +{ + channels: { + msteams: { + enabled: true, + appId: "", + appPassword: "", + tenantId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, +} +``` + +Catatan: obrolan grup diblokir secara default (`channels.msteams.groupPolicy: "allowlist"`). Untuk mengizinkan balasan grup, atur `channels.msteams.groupAllowFrom` (atau gunakan `groupPolicy: "open"` untuk mengizinkan anggota mana pun, dengan gating mention). + +## Tujuan + +- Berbicara dengan OpenClaw melalui DM, obrolan grup, atau channel Teams. +- Menjaga perutean tetap deterministik: balasan selalu kembali ke channel asal kedatangannya. +- Default ke perilaku channel yang aman (mention diwajibkan kecuali dikonfigurasi lain). + +## Penulisan config + +Secara default, Microsoft Teams diizinkan menulis pembaruan config yang dipicu oleh `/config set|unset` (memerlukan `commands.config: true`). + +Nonaktifkan dengan: + +```json5 +{ + channels: { msteams: { configWrites: false } }, +} +``` + +## Kontrol akses (DM + grup) + +**Akses DM** + +- Default: `channels.msteams.dmPolicy = "pairing"`. Pengirim yang tidak dikenal diabaikan sampai disetujui. +- `channels.msteams.allowFrom` sebaiknya menggunakan AAD object ID yang stabil. +- UPN/nama tampilan dapat berubah; pencocokan langsung dinonaktifkan secara default dan hanya diaktifkan dengan `channels.msteams.dangerouslyAllowNameMatching: true`. +- Wizard dapat me-resolve nama ke ID melalui Microsoft Graph jika kredensial mengizinkan. + +**Akses grup** + +- Default: `channels.msteams.groupPolicy = "allowlist"` (diblokir kecuali Anda menambahkan `groupAllowFrom`). Gunakan `channels.defaults.groupPolicy` untuk menimpa default saat tidak disetel. +- `channels.msteams.groupAllowFrom` mengontrol pengirim mana yang dapat memicu di obrolan grup/channel (fallback ke `channels.msteams.allowFrom`). +- Set `groupPolicy: "open"` untuk mengizinkan anggota mana pun (tetap di-gate oleh mention secara default). +- Untuk mengizinkan **tanpa channel apa pun**, set `channels.msteams.groupPolicy: "disabled"`. + +Contoh: + +```json5 +{ + channels: { + msteams: { + groupPolicy: "allowlist", + groupAllowFrom: ["user@org.com"], + }, + }, +} +``` + +**Teams + allowlist channel** + +- Lingkupi balasan grup/channel dengan mendaftarkan team dan channel di bawah `channels.msteams.teams`. +- Kunci sebaiknya menggunakan team ID yang stabil dan channel conversation ID. +- Saat `groupPolicy="allowlist"` dan allowlist teams tersedia, hanya team/channel yang terdaftar yang diterima (dengan gating mention). +- Wizard konfigurasi menerima entri `Team/Channel` dan menyimpannya untuk Anda. +- Saat startup, OpenClaw me-resolve nama team/channel dan nama allowlist pengguna ke ID (saat izin Graph mengizinkan) + dan mencatat pemetaannya; nama team/channel yang tidak ter-resolve tetap disimpan seperti diketik tetapi diabaikan untuk perutean secara default kecuali `channels.msteams.dangerouslyAllowNameMatching: true` diaktifkan. + +Contoh: + +```json5 +{ + channels: { + msteams: { + groupPolicy: "allowlist", + teams: { + "My Team": { + channels: { + General: { requireMention: true }, + }, + }, + }, + }, + }, +} +``` + +## Cara kerjanya + +1. Pastikan plugin Microsoft Teams tersedia. + - Rilis OpenClaw paket saat ini sudah menyertakannya. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Buat **Azure Bot** (App ID + secret + tenant ID). +3. Bangun **paket aplikasi Teams** yang merujuk ke bot dan menyertakan izin RSC di bawah ini. +4. Unggah/instal aplikasi Teams ke dalam team (atau cakupan personal untuk DM). +5. Konfigurasikan `msteams` di `~/.openclaw/openclaw.json` (atau env vars) dan jalankan gateway. +6. Gateway mendengarkan traffic webhook Bot Framework di `/api/messages` secara default. + +## Penyiapan Azure Bot (Prasyarat) + +Sebelum mengonfigurasi OpenClaw, Anda perlu membuat resource Azure Bot. + +### Langkah 1: Buat Azure Bot + +1. Buka [Create Azure Bot](https://portal.azure.com/#create/Microsoft.AzureBot) +2. Isi tab **Basics**: + + | Field | Value | + | ------------------ | -------------------------------------------------------- | + | **Bot handle** | Nama bot Anda, mis. `openclaw-msteams` (harus unik) | + | **Subscription** | Pilih subscription Azure Anda | + | **Resource group** | Buat baru atau gunakan yang sudah ada | + | **Pricing tier** | **Free** untuk dev/testing | + | **Type of App** | **Single Tenant** (disarankan - lihat catatan di bawah) | + | **Creation type** | **Create new Microsoft App ID** | + +> **Pemberitahuan deprecation:** Pembuatan bot multi-tenant baru tidak lagi didukung setelah 2025-07-31. Gunakan **Single Tenant** untuk bot baru. + +3. Klik **Review + create** → **Create** (tunggu ~1-2 menit) + +### Langkah 2: Dapatkan Kredensial + +1. Buka resource Azure Bot Anda → **Configuration** +2. Salin **Microsoft App ID** → ini adalah `appId` Anda +3. Klik **Manage Password** → buka App Registration +4. Di bawah **Certificates & secrets** → **New client secret** → salin **Value** → ini adalah `appPassword` Anda +5. Buka **Overview** → salin **Directory (tenant) ID** → ini adalah `tenantId` Anda + +### Langkah 3: Konfigurasikan Messaging Endpoint + +1. Di Azure Bot → **Configuration** +2. Set **Messaging endpoint** ke URL webhook Anda: + - Produksi: `https://your-domain.com/api/messages` + - Dev lokal: gunakan tunnel (lihat [Pengembangan Lokal](#local-development-tunneling) di bawah) + +### Langkah 4: Aktifkan Channel Teams + +1. Di Azure Bot → **Channels** +2. Klik **Microsoft Teams** → Configure → Save +3. Terima Terms of Service + +## Pengembangan Lokal (Tunneling) + +Teams tidak dapat menjangkau `localhost`. Gunakan tunnel untuk pengembangan lokal: + +**Opsi A: ngrok** + +```bash +ngrok http 3978 +# Salin URL https, mis. https://abc123.ngrok.io +# Set messaging endpoint ke: https://abc123.ngrok.io/api/messages +``` + +**Opsi B: Tailscale Funnel** + +```bash +tailscale funnel 3978 +# Gunakan URL Tailscale funnel Anda sebagai messaging endpoint +``` + +## Teams Developer Portal (Alternatif) + +Alih-alih membuat ZIP manifest secara manual, Anda dapat menggunakan [Teams Developer Portal](https://dev.teams.microsoft.com/apps): + +1. Klik **+ New app** +2. Isi info dasar (nama, deskripsi, info developer) +3. Buka **App features** → **Bot** +4. Pilih **Enter a bot ID manually** dan tempel Azure Bot App ID Anda +5. Centang scope: **Personal**, **Team**, **Group Chat** +6. Klik **Distribute** → **Download app package** +7. Di Teams: **Apps** → **Manage your apps** → **Upload a custom app** → pilih ZIP + +Ini sering lebih mudah daripada mengedit manifest JSON secara manual. + +## Menguji Bot + +**Opsi A: Azure Web Chat (verifikasi webhook terlebih dahulu)** + +1. Di Azure Portal → resource Azure Bot Anda → **Test in Web Chat** +2. Kirim pesan - Anda seharusnya melihat respons +3. Ini mengonfirmasi bahwa endpoint webhook Anda berfungsi sebelum penyiapan Teams + +**Opsi B: Teams (setelah aplikasi diinstal)** + +1. Instal aplikasi Teams (sideload atau katalog organisasi) +2. Temukan bot di Teams dan kirim DM +3. Periksa log gateway untuk aktivitas masuk + +## Penyiapan (minimal hanya teks) + +1. **Pastikan plugin Microsoft Teams tersedia** + - Rilis OpenClaw paket saat ini sudah menyertakannya. + - Instalasi lama/kustom dapat menambahkannya secara manual: + - Dari npm: `openclaw plugins install @openclaw/msteams` + - Dari checkout lokal: `openclaw plugins install ./path/to/local/msteams-plugin` + +2. **Registrasi bot** + - Buat Azure Bot (lihat di atas) dan catat: + - App ID + - Client secret (App password) + - Tenant ID (single-tenant) + +3. **Manifest aplikasi Teams** + - Sertakan entri `bot` dengan `botId = `. + - Scope: `personal`, `team`, `groupChat`. + - `supportsFiles: true` (diperlukan untuk penanganan file dalam scope personal). + - Tambahkan izin RSC (di bawah). + - Buat ikon: `outline.png` (32x32) dan `color.png` (192x192). + - Zip ketiga file menjadi satu: `manifest.json`, `outline.png`, `color.png`. + +4. **Konfigurasikan OpenClaw** + + ```json5 + { + channels: { + msteams: { + enabled: true, + appId: "", + appPassword: "", + tenantId: "", + webhook: { port: 3978, path: "/api/messages" }, + }, + }, + } + ``` + + Anda juga dapat menggunakan variabel lingkungan alih-alih kunci config: + - `MSTEAMS_APP_ID` + - `MSTEAMS_APP_PASSWORD` + - `MSTEAMS_TENANT_ID` + +5. **Endpoint bot** + - Set Azure Bot Messaging Endpoint ke: + - `https://:3978/api/messages` (atau path/port pilihan Anda). + +6. **Jalankan gateway** + - Channel Teams dimulai secara otomatis saat plugin bawaan atau plugin yang diinstal manual tersedia dan config `msteams` ada beserta kredensialnya. + +## Aksi info anggota + +OpenClaw mengekspos aksi `member-info` berbasis Graph untuk Microsoft Teams sehingga agen dan otomatisasi dapat me-resolve detail anggota channel (nama tampilan, email, peran) langsung dari Microsoft Graph. + +Persyaratan: + +- Izin RSC `Member.Read.Group` (sudah ada dalam manifest yang direkomendasikan) +- Untuk lookup lintas-team: izin Graph Application `User.Read.All` dengan admin consent + +Aksi ini di-gate oleh `channels.msteams.actions.memberInfo` (default: aktif saat kredensial Graph tersedia). + +## Konteks riwayat + +- `channels.msteams.historyLimit` mengontrol berapa banyak pesan channel/grup terbaru yang dibungkus ke dalam prompt. +- Fallback ke `messages.groupChat.historyLimit`. Set `0` untuk menonaktifkan (default 50). +- Riwayat thread yang diambil difilter oleh allowlist pengirim (`allowFrom` / `groupAllowFrom`), sehingga penanaman konteks thread hanya menyertakan pesan dari pengirim yang diizinkan. +- Konteks lampiran kutipan (`ReplyTo*` yang diturunkan dari HTML balasan Teams) saat ini diteruskan apa adanya. +- Dengan kata lain, allowlist mengatur siapa yang dapat memicu agen; hanya jalur konteks tambahan tertentu yang difilter saat ini. +- Riwayat DM dapat dibatasi dengan `channels.msteams.dmHistoryLimit` (giliran pengguna). Override per pengguna: `channels.msteams.dms[""].historyLimit`. + +## Izin RSC Teams saat ini (Manifest) + +Berikut adalah **resourceSpecific permissions** yang sudah ada di manifest aplikasi Teams kami. Izin ini hanya berlaku di dalam team/chat tempat aplikasi diinstal. + +**Untuk channel (scope team):** + +- `ChannelMessage.Read.Group` (Application) - menerima semua teks pesan channel tanpa @mention +- `ChannelMessage.Send.Group` (Application) +- `Member.Read.Group` (Application) +- `Owner.Read.Group` (Application) +- `ChannelSettings.Read.Group` (Application) +- `TeamMember.Read.Group` (Application) +- `TeamSettings.Read.Group` (Application) + +**Untuk obrolan grup:** + +- `ChatMessage.Read.Chat` (Application) - menerima semua pesan obrolan grup tanpa @mention + +## Contoh Manifest Teams (disamarkan) + +Contoh minimal yang valid dengan field yang diperlukan. Ganti ID dan URL. + +```json5 +{ + $schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json", + manifestVersion: "1.23", + version: "1.0.0", + id: "00000000-0000-0000-0000-000000000000", + name: { short: "OpenClaw" }, + developer: { + name: "Your Org", + websiteUrl: "https://example.com", + privacyUrl: "https://example.com/privacy", + termsOfUseUrl: "https://example.com/terms", + }, + description: { short: "OpenClaw in Teams", full: "OpenClaw in Teams" }, + icons: { outline: "outline.png", color: "color.png" }, + accentColor: "#5B6DEF", + bots: [ + { + botId: "11111111-1111-1111-1111-111111111111", + scopes: ["personal", "team", "groupChat"], + isNotificationOnly: false, + supportsCalling: false, + supportsVideo: false, + supportsFiles: true, + }, + ], + webApplicationInfo: { + id: "11111111-1111-1111-1111-111111111111", + }, + authorization: { + permissions: { + resourceSpecific: [ + { name: "ChannelMessage.Read.Group", type: "Application" }, + { name: "ChannelMessage.Send.Group", type: "Application" }, + { name: "Member.Read.Group", type: "Application" }, + { name: "Owner.Read.Group", type: "Application" }, + { name: "ChannelSettings.Read.Group", type: "Application" }, + { name: "TeamMember.Read.Group", type: "Application" }, + { name: "TeamSettings.Read.Group", type: "Application" }, + { name: "ChatMessage.Read.Chat", type: "Application" }, + ], + }, + }, +} +``` + +### Catatan penting manifest (field wajib) + +- `bots[].botId` **harus** cocok dengan Azure Bot App ID. +- `webApplicationInfo.id` **harus** cocok dengan Azure Bot App ID. +- `bots[].scopes` harus menyertakan surface yang ingin Anda gunakan (`personal`, `team`, `groupChat`). +- `bots[].supportsFiles: true` diperlukan untuk penanganan file dalam scope personal. +- `authorization.permissions.resourceSpecific` harus menyertakan izin baca/kirim channel jika Anda ingin traffic channel. + +### Memperbarui aplikasi yang sudah ada + +Untuk memperbarui aplikasi Teams yang sudah terinstal (misalnya untuk menambahkan izin RSC): + +1. Perbarui `manifest.json` Anda dengan setelan baru +2. **Naikkan field `version`** (mis. `1.0.0` → `1.1.0`) +3. **Zip ulang** manifest dengan ikon (`manifest.json`, `outline.png`, `color.png`) +4. Unggah ZIP baru: + - **Opsi A (Teams Admin Center):** Teams Admin Center → Teams apps → Manage apps → temukan aplikasi Anda → Upload new version + - **Opsi B (Sideload):** Di Teams → Apps → Manage your apps → Upload a custom app +5. **Untuk channel team:** instal ulang aplikasi di setiap team agar izin baru berlaku +6. **Keluar sepenuhnya lalu jalankan ulang Teams** (bukan hanya menutup jendela) untuk membersihkan metadata aplikasi yang di-cache + +## Kapabilitas: hanya RSC vs Graph + +### Dengan **hanya Teams RSC** (aplikasi terinstal, tanpa izin Microsoft Graph API) + +Berfungsi: + +- Membaca konten **teks** pesan channel. +- Mengirim konten **teks** pesan channel. +- Menerima lampiran file **personal (DM)**. + +Tidak berfungsi: + +- **Konten gambar atau file** channel/grup (payload hanya menyertakan stub HTML). +- Mengunduh lampiran yang disimpan di SharePoint/OneDrive. +- Membaca riwayat pesan (di luar event webhook langsung). + +### Dengan **Teams RSC + izin Microsoft Graph Application** + +Menambahkan: + +- Mengunduh hosted content (gambar yang ditempel ke pesan). +- Mengunduh lampiran file yang disimpan di SharePoint/OneDrive. +- Membaca riwayat pesan channel/chat melalui Graph. + +### RSC vs Graph API + +| Kapabilitas | Izin RSC | Graph API | +| ----------------------- | --------------------- | ------------------------------------ | +| **Pesan real-time** | Ya (melalui webhook) | Tidak (hanya polling) | +| **Pesan historis** | Tidak | Ya (dapat mengambil riwayat) | +| **Kompleksitas setup** | Hanya manifest aplikasi | Memerlukan admin consent + alur token | +| **Berfungsi offline** | Tidak (harus berjalan) | Ya (dapat melakukan query kapan saja) | + +**Intinya:** RSC untuk mendengarkan secara real-time; Graph API untuk akses historis. Untuk mengejar pesan yang terlewat saat offline, Anda memerlukan Graph API dengan `ChannelMessage.Read.All` (memerlukan admin consent). + +## Media + riwayat dengan Graph (diperlukan untuk channel) + +Jika Anda memerlukan gambar/file di **channel** atau ingin mengambil **riwayat pesan**, Anda harus mengaktifkan izin Microsoft Graph dan memberikan admin consent. + +1. Di Entra ID (Azure AD) **App Registration**, tambahkan Microsoft Graph **Application permissions**: + - `ChannelMessage.Read.All` (lampiran channel + riwayat) + - `Chat.Read.All` atau `ChatMessage.Read.All` (obrolan grup) +2. **Berikan admin consent** untuk tenant. +3. Naikkan **versi manifest** aplikasi Teams, unggah ulang, dan **instal ulang aplikasi di Teams**. +4. **Keluar sepenuhnya lalu jalankan ulang Teams** untuk membersihkan metadata aplikasi yang di-cache. + +**Izin tambahan untuk mention pengguna:** Mention @pengguna berfungsi langsung untuk pengguna dalam percakapan. Namun, jika Anda ingin mencari dan me-mention pengguna secara dinamis yang **tidak berada dalam percakapan saat ini**, tambahkan izin `User.Read.All` (Application) dan berikan admin consent. + +## Keterbatasan yang diketahui + +### Timeout webhook + +Teams mengirim pesan melalui webhook HTTP. Jika pemrosesan terlalu lama (misalnya respons LLM lambat), Anda mungkin melihat: + +- Timeout gateway +- Teams mencoba ulang pesan (menyebabkan duplikasi) +- Balasan yang terlewat + +OpenClaw menanganinya dengan mengembalikan respons dengan cepat dan mengirim balasan secara proaktif, tetapi respons yang sangat lambat masih dapat menyebabkan masalah. + +### Pemformatan + +Markdown Teams lebih terbatas daripada Slack atau Discord: + +- Pemformatan dasar berfungsi: **tebal**, _miring_, `code`, tautan +- Markdown kompleks (tabel, daftar bertingkat) mungkin tidak dirender dengan benar +- Adaptive Cards didukung untuk poll dan pengiriman card arbitrer (lihat di bawah) + +## Konfigurasi + +Setelan utama (lihat `/gateway/configuration` untuk pola channel bersama): + +- `channels.msteams.enabled`: aktifkan/nonaktifkan channel. +- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: kredensial bot. +- `channels.msteams.webhook.port` (default `3978`) +- `channels.msteams.webhook.path` (default `/api/messages`) +- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing) +- `channels.msteams.allowFrom`: allowlist DM (AAD object ID direkomendasikan). Wizard me-resolve nama ke ID selama setup saat akses Graph tersedia. +- `channels.msteams.dangerouslyAllowNameMatching`: toggle break-glass untuk mengaktifkan kembali pencocokan UPN/nama tampilan yang bisa berubah dan perutean langsung nama team/channel. +- `channels.msteams.textChunkLimit`: ukuran chunk teks outbound. +- `channels.msteams.chunkMode`: `length` (default) atau `newline` untuk memisah berdasarkan baris kosong (batas paragraf) sebelum chunking berdasarkan panjang. +- `channels.msteams.mediaAllowHosts`: allowlist untuk host lampiran masuk (default ke domain Microsoft/Teams). +- `channels.msteams.mediaAuthAllowHosts`: allowlist untuk melampirkan header Authorization pada percobaan ulang media (default ke host Graph + Bot Framework). +- `channels.msteams.requireMention`: wajibkan @mention di channel/grup (default true). +- `channels.msteams.replyStyle`: `thread | top-level` (lihat [Gaya Balasan](#reply-style-threads-vs-posts)). +- `channels.msteams.teams..replyStyle`: override per-team. +- `channels.msteams.teams..requireMention`: override per-team. +- `channels.msteams.teams..tools`: override kebijakan tool default per-team (`allow`/`deny`/`alsoAllow`) yang digunakan saat override channel tidak ada. +- `channels.msteams.teams..toolsBySender`: override kebijakan tool per-pengirim default per-team (`"*"` wildcard didukung). +- `channels.msteams.teams..channels..replyStyle`: override per-channel. +- `channels.msteams.teams..channels..requireMention`: override per-channel. +- `channels.msteams.teams..channels..tools`: override kebijakan tool per-channel (`allow`/`deny`/`alsoAllow`). +- `channels.msteams.teams..channels..toolsBySender`: override kebijakan tool per-pengirim per-channel (`"*"` wildcard didukung). +- Kunci `toolsBySender` sebaiknya menggunakan prefiks eksplisit: + `id:`, `e164:`, `username:`, `name:` (kunci lama tanpa prefiks masih dipetakan hanya ke `id:`). +- `channels.msteams.actions.memberInfo`: aktifkan atau nonaktifkan aksi info anggota berbasis Graph (default: aktif saat kredensial Graph tersedia). +- `channels.msteams.sharePointSiteId`: SharePoint site ID untuk upload file di obrolan grup/channel (lihat [Mengirim file di obrolan grup](#sending-files-in-group-chats)). + +## Perutean & Sesi + +- Kunci sesi mengikuti format agen standar (lihat [/concepts/session](/concepts/session)): + - Direct message berbagi sesi utama (`agent::`). + - Pesan channel/grup menggunakan ID percakapan: + - `agent::msteams:channel:` + - `agent::msteams:group:` + +## Gaya Balasan: Threads vs Posts + +Teams baru-baru ini memperkenalkan dua gaya UI channel di atas model data dasar yang sama: + +| Gaya | Deskripsi | `replyStyle` yang direkomendasikan | +| ----------------------- | ------------------------------------------------------ | ---------------------------------- | +| **Posts** (klasik) | Pesan muncul sebagai kartu dengan balasan ber-thread di bawahnya | `thread` (default) | +| **Threads** (mirip Slack) | Pesan mengalir secara linear, lebih mirip Slack | `top-level` | + +**Masalahnya:** API Teams tidak mengekspos gaya UI channel yang digunakan. Jika Anda menggunakan `replyStyle` yang salah: + +- `thread` di channel bergaya Threads → balasan muncul bertingkat secara janggal +- `top-level` di channel bergaya Posts → balasan muncul sebagai post top-level terpisah, bukan di dalam thread + +**Solusi:** Konfigurasikan `replyStyle` per-channel berdasarkan cara channel disiapkan: + +```json5 +{ + channels: { + msteams: { + replyStyle: "thread", + teams: { + "19:abc...@thread.tacv2": { + channels: { + "19:xyz...@thread.tacv2": { + replyStyle: "top-level", + }, + }, + }, + }, + }, + }, +} +``` + +## Lampiran & Gambar + +**Keterbatasan saat ini:** + +- **DM:** Gambar dan lampiran file berfungsi melalui API file bot Teams. +- **Channel/grup:** Lampiran berada di penyimpanan M365 (SharePoint/OneDrive). Payload webhook hanya menyertakan stub HTML, bukan byte file yang sebenarnya. **Izin Graph API diperlukan** untuk mengunduh lampiran channel. +- Untuk pengiriman eksplisit yang mengutamakan file, gunakan `action=upload-file` dengan `media` / `filePath` / `path`; `message` opsional menjadi teks/komentar pendamping, dan `filename` menimpa nama yang diunggah. + +Tanpa izin Graph, pesan channel dengan gambar akan diterima sebagai teks saja (konten gambar tidak dapat diakses bot). +Secara default, OpenClaw hanya mengunduh media dari hostname Microsoft/Teams. Timpa dengan `channels.msteams.mediaAllowHosts` (gunakan `["*"]` untuk mengizinkan host mana pun). +Header Authorization hanya dilampirkan untuk host dalam `channels.msteams.mediaAuthAllowHosts` (default ke host Graph + Bot Framework). Jaga daftar ini tetap ketat (hindari suffix multi-tenant). + +## Mengirim file di obrolan grup + +Bot dapat mengirim file di DM menggunakan alur FileConsentCard (bawaan). Namun, **mengirim file di obrolan grup/channel** memerlukan setup tambahan: + +| Konteks | Cara file dikirim | Setup yang diperlukan | +| ------------------------ | -------------------------------------------- | -------------------------------------------------- | +| **DM** | FileConsentCard → pengguna menerima → bot mengunggah | Langsung berfungsi | +| **Obrolan grup/channel** | Unggah ke SharePoint → bagikan tautan | Memerlukan `sharePointSiteId` + izin Graph | +| **Gambar (konteks apa pun)** | Inline berkode Base64 | Langsung berfungsi | + +### Mengapa obrolan grup memerlukan SharePoint + +Bot tidak memiliki drive OneDrive personal (endpoint Graph API `/me/drive` tidak berfungsi untuk identitas aplikasi). Untuk mengirim file di obrolan grup/channel, bot mengunggah ke **situs SharePoint** dan membuat tautan berbagi. + +### Setup + +1. **Tambahkan izin Graph API** di Entra ID (Azure AD) → App Registration: + - `Sites.ReadWrite.All` (Application) - unggah file ke SharePoint + - `Chat.Read.All` (Application) - opsional, mengaktifkan tautan berbagi per-pengguna + +2. **Berikan admin consent** untuk tenant. + +3. **Dapatkan ID situs SharePoint Anda:** + + ```bash + # Via Graph Explorer atau curl dengan token yang valid: + curl -H "Authorization: Bearer $TOKEN" \ + "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}" + + # Contoh: untuk situs di "contoso.sharepoint.com/sites/BotFiles" + curl -H "Authorization: Bearer $TOKEN" \ + "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles" + + # Respons mencakup: "id": "contoso.sharepoint.com,guid1,guid2" + ``` + +4. **Konfigurasikan OpenClaw:** + + ```json5 + { + channels: { + msteams: { + // ... config lain ... + sharePointSiteId: "contoso.sharepoint.com,guid1,guid2", + }, + }, + } + ``` + +### Perilaku berbagi + +| Izin | Perilaku berbagi | +| --------------------------------------- | --------------------------------------------------------- | +| `Sites.ReadWrite.All` saja | Tautan berbagi ke seluruh organisasi (siapa pun di org dapat mengakses) | +| `Sites.ReadWrite.All` + `Chat.Read.All` | Tautan berbagi per-pengguna (hanya anggota chat yang dapat mengakses) | + +Berbagi per-pengguna lebih aman karena hanya peserta chat yang dapat mengakses file. Jika izin `Chat.Read.All` tidak ada, bot fallback ke berbagi seluruh organisasi. + +### Perilaku fallback + +| Skenario | Hasil | +| ------------------------------------------------- | -------------------------------------------------- | +| Obrolan grup + file + `sharePointSiteId` dikonfigurasi | Unggah ke SharePoint, kirim tautan berbagi | +| Obrolan grup + file + tanpa `sharePointSiteId` | Coba unggah ke OneDrive (mungkin gagal), kirim teks saja | +| Obrolan personal + file | Alur FileConsentCard (berfungsi tanpa SharePoint) | +| Konteks apa pun + gambar | Inline berkode Base64 (berfungsi tanpa SharePoint) | + +### Lokasi penyimpanan file + +File yang diunggah disimpan di folder `/OpenClawShared/` di pustaka dokumen default situs SharePoint yang dikonfigurasi. + +## Poll (Adaptive Cards) + +OpenClaw mengirim poll Teams sebagai Adaptive Cards (tidak ada API poll Teams bawaan). + +- CLI: `openclaw message poll --channel msteams --target conversation: ...` +- Suara dicatat oleh gateway di `~/.openclaw/msteams-polls.json`. +- Gateway harus tetap online untuk mencatat suara. +- Poll belum otomatis mem-posting ringkasan hasil (periksa file penyimpanan jika perlu). + +## Adaptive Cards (arbitrer) + +Kirim JSON Adaptive Card apa pun ke pengguna atau percakapan Teams menggunakan tool `message` atau CLI. + +Parameter `card` menerima objek JSON Adaptive Card. Saat `card` disediakan, teks pesan bersifat opsional. + +**Tool agen:** + +```json5 +{ + action: "send", + channel: "msteams", + target: "user:", + card: { + type: "AdaptiveCard", + version: "1.5", + body: [{ type: "TextBlock", text: "Hello!" }], + }, +} +``` + +**CLI:** + +```bash +openclaw message send --channel msteams \ + --target "conversation:19:abc...@thread.tacv2" \ + --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}' +``` + +Lihat [dokumentasi Adaptive Cards](https://adaptivecards.io/) untuk skema card dan contoh. Untuk detail format target, lihat [Format target](#target-formats) di bawah. + +## Format target + +Target MSTeams menggunakan prefiks untuk membedakan pengguna dan percakapan: + +| Jenis target | Format | Contoh | +| -------------------- | -------------------------------- | --------------------------------------------------- | +| Pengguna (berdasarkan ID) | `user:` | `user:40a1a0ed-4ff2-4164-a219-55518990c197` | +| Pengguna (berdasarkan nama) | `user:` | `user:John Smith` (memerlukan Graph API) | +| Grup/channel | `conversation:` | `conversation:19:abc123...@thread.tacv2` | +| Grup/channel (mentah) | `` | `19:abc123...@thread.tacv2` (jika mengandung `@thread`) | + +**Contoh CLI:** + +```bash +# Kirim ke pengguna berdasarkan ID +openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello" + +# Kirim ke pengguna berdasarkan nama tampilan (memicu lookup Graph API) +openclaw message send --channel msteams --target "user:John Smith" --message "Hello" + +# Kirim ke obrolan grup atau channel +openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello" + +# Kirim Adaptive Card ke percakapan +openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \ + --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}' +``` + +**Contoh tool agen:** + +```json5 +{ + action: "send", + channel: "msteams", + target: "user:John Smith", + message: "Hello!", +} +``` + +```json5 +{ + action: "send", + channel: "msteams", + target: "conversation:19:abc...@thread.tacv2", + card: { + type: "AdaptiveCard", + version: "1.5", + body: [{ type: "TextBlock", text: "Hello" }], + }, +} +``` + +Catatan: Tanpa prefiks `user:`, nama secara default di-resolve sebagai grup/team. Selalu gunakan `user:` saat menargetkan orang berdasarkan nama tampilan. + +## Pesan proaktif + +- Pesan proaktif hanya dimungkinkan **setelah** pengguna berinteraksi, karena saat itulah kami menyimpan referensi percakapan. +- Lihat `/gateway/configuration` untuk gating `dmPolicy` dan allowlist. + +## ID Team dan Channel (Jebakan Umum) + +Parameter kueri `groupId` di URL Teams **BUKAN** team ID yang digunakan untuk konfigurasi. Ekstrak ID dari path URL sebagai gantinya: + +**URL Team:** + +``` +https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=... + └────────────────────────────┘ + Team ID (URL-decode ini) +``` + +**URL Channel:** + +``` +https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=... + └─────────────────────────┘ + Channel ID (URL-decode ini) +``` + +**Untuk config:** + +- Team ID = segmen path setelah `/team/` (URL-decoded, mis. `19:Bk4j...@thread.tacv2`) +- Channel ID = segmen path setelah `/channel/` (URL-decoded) +- **Abaikan** parameter kueri `groupId` + +## Channel Privat + +Bot memiliki dukungan terbatas di channel privat: + +| Fitur | Channel Standar | Channel Privat | +| ---------------------------- | --------------- | --------------------- | +| Instalasi bot | Ya | Terbatas | +| Pesan real-time (webhook) | Ya | Mungkin tidak berfungsi | +| Izin RSC | Ya | Dapat berperilaku berbeda | +| @mentions | Ya | Jika bot dapat diakses | +| Riwayat Graph API | Ya | Ya (dengan izin) | + +**Solusi sementara jika channel privat tidak berfungsi:** + +1. Gunakan channel standar untuk interaksi bot +2. Gunakan DM - pengguna selalu dapat mengirim pesan langsung ke bot +3. Gunakan Graph API untuk akses historis (memerlukan `ChannelMessage.Read.All`) + +## Pemecahan masalah + +### Masalah umum + +- **Gambar tidak muncul di channel:** izin Graph atau admin consent belum ada. Instal ulang aplikasi Teams dan keluar/buka kembali Teams sepenuhnya. +- **Tidak ada respons di channel:** mention diwajibkan secara default; set `channels.msteams.requireMention=false` atau konfigurasikan per team/channel. +- **Ketidakcocokan versi (Teams masih menampilkan manifest lama):** hapus + tambahkan kembali aplikasi dan keluar sepenuhnya dari Teams untuk refresh. +- **401 Unauthorized dari webhook:** Wajar saat menguji manual tanpa Azure JWT - artinya endpoint dapat dijangkau tetapi autentikasi gagal. Gunakan Azure Web Chat untuk menguji dengan benar. + +### Error upload manifest + +- **"Icon file cannot be empty":** Manifest merujuk file ikon yang berukuran 0 byte. Buat ikon PNG yang valid (32x32 untuk `outline.png`, 192x192 untuk `color.png`). +- **"webApplicationInfo.Id already in use":** Aplikasi masih terinstal di team/chat lain. Temukan dan uninstall terlebih dahulu, atau tunggu 5-10 menit untuk propagasi. +- **"Something went wrong" saat upload:** Unggah melalui [https://admin.teams.microsoft.com](https://admin.teams.microsoft.com), lalu buka browser DevTools (F12) → tab Network, dan periksa body respons untuk error sebenarnya. +- **Sideload gagal:** Coba "Upload an app to your org's app catalog" alih-alih "Upload a custom app" - ini sering melewati pembatasan sideload. + +### Izin RSC tidak berfungsi + +1. Verifikasi `webApplicationInfo.id` cocok persis dengan App ID bot Anda +2. Unggah ulang aplikasi dan instal ulang di team/chat +3. Periksa apakah admin organisasi Anda memblokir izin RSC +4. Pastikan Anda menggunakan scope yang benar: `ChannelMessage.Read.Group` untuk teams, `ChatMessage.Read.Chat` untuk obrolan grup + +## Referensi + +- [Create Azure Bot](https://learn.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) - panduan setup Azure Bot +- [Teams Developer Portal](https://dev.teams.microsoft.com/apps) - membuat/mengelola aplikasi Teams +- [Skema manifest aplikasi Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/schema/manifest-schema) +- [Menerima pesan channel dengan RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-messages-with-rsc) +- [Referensi izin RSC](https://learn.microsoft.com/en-us/microsoftteams/platform/graph-api/rsc/resource-specific-consent) +- [Penanganan file bot Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bots-filesv4) (channel/grup memerlukan Graph) +- [Pesan proaktif](https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/send-proactive-messages) + +## Terkait + +- [Ringkasan Channel](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan gating mention +- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/nextcloud-talk.md b/docs/id/channels/nextcloud-talk.md new file mode 100644 index 000000000..35ebe86c4 --- /dev/null +++ b/docs/id/channels/nextcloud-talk.md @@ -0,0 +1,156 @@ +--- +read_when: + - Sedang mengerjakan fitur channel Nextcloud Talk +summary: Status dukungan, kapabilitas, dan konfigurasi Nextcloud Talk +title: Nextcloud Talk +x-i18n: + generated_at: "2026-04-05T13:43:40Z" + model: gpt-5.4 + provider: openai + source_hash: 900402afe67cf3ce96103d55158eb28cffb29c9845b77248e70d7653b12ae810 + source_path: channels/nextcloud-talk.md + workflow: 15 +--- + +# Nextcloud Talk + +Status: plugin bawaan (bot webhook). Direct message, room, reactions, dan pesan markdown didukung. + +## Plugin bawaan + +Nextcloud Talk dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi +build terpaket normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Nextcloud Talk, +instal secara manual: + +Instal melalui CLI (registry npm): + +```bash +openclaw plugins install @openclaw/nextcloud-talk +``` + +Checkout lokal (saat berjalan dari repo git): + +```bash +openclaw plugins install ./path/to/local/nextcloud-talk-plugin +``` + +Detail: [Plugins](/tools/plugin) + +## Penyiapan cepat (pemula) + +1. Pastikan plugin Nextcloud Talk tersedia. + - Rilis OpenClaw terpaket saat ini sudah menyertakannya. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Di server Nextcloud Anda, buat bot: + + ```bash + ./occ talk:bot:install "OpenClaw" "" "" --feature reaction + ``` + +3. Aktifkan bot di pengaturan room target. +4. Konfigurasikan OpenClaw: + - Config: `channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret` + - Atau env: `NEXTCLOUD_TALK_BOT_SECRET` (hanya akun default) +5. Mulai ulang gateway (atau selesaikan penyiapan). + +Config minimal: + +```json5 +{ + channels: { + "nextcloud-talk": { + enabled: true, + baseUrl: "https://cloud.example.com", + botSecret: "shared-secret", + dmPolicy: "pairing", + }, + }, +} +``` + +## Catatan + +- Bot tidak dapat memulai DM. Pengguna harus mengirim pesan ke bot terlebih dahulu. +- URL webhook harus dapat dijangkau oleh Gateway; atur `webhookPublicUrl` jika berada di balik proxy. +- Unggahan media tidak didukung oleh API bot; media dikirim sebagai URL. +- Payload webhook tidak membedakan DM vs room; atur `apiUser` + `apiPassword` untuk mengaktifkan lookup tipe room (jika tidak, DM diperlakukan sebagai room). + +## Kontrol akses (DM) + +- Default: `channels.nextcloud-talk.dmPolicy = "pairing"`. Pengirim yang tidak dikenal mendapatkan kode pairing. +- Setujui melalui: + - `openclaw pairing list nextcloud-talk` + - `openclaw pairing approve nextcloud-talk ` +- DM publik: `channels.nextcloud-talk.dmPolicy="open"` ditambah `channels.nextcloud-talk.allowFrom=["*"]`. +- `allowFrom` hanya cocok dengan ID pengguna Nextcloud; nama tampilan diabaikan. + +## Room (grup) + +- Default: `channels.nextcloud-talk.groupPolicy = "allowlist"` (dibatasi mention). +- Masukkan room ke allowlist dengan `channels.nextcloud-talk.rooms`: + +```json5 +{ + channels: { + "nextcloud-talk": { + rooms: { + "room-token": { requireMention: true }, + }, + }, + }, +} +``` + +- Untuk tidak mengizinkan room apa pun, biarkan allowlist kosong atau atur `channels.nextcloud-talk.groupPolicy="disabled"`. + +## Kapabilitas + +| Fitur | Status | +| --------------- | ----------------- | +| Direct message | Didukung | +| Room | Didukung | +| Thread | Tidak didukung | +| Media | Hanya URL | +| Reactions | Didukung | +| Perintah native | Tidak didukung | + +## Referensi konfigurasi (Nextcloud Talk) + +Konfigurasi lengkap: [Configuration](/gateway/configuration) + +Opsi provider: + +- `channels.nextcloud-talk.enabled`: aktifkan/nonaktifkan startup channel. +- `channels.nextcloud-talk.baseUrl`: URL instance Nextcloud. +- `channels.nextcloud-talk.botSecret`: rahasia bersama bot. +- `channels.nextcloud-talk.botSecretFile`: path rahasia file reguler. Symlink ditolak. +- `channels.nextcloud-talk.apiUser`: pengguna API untuk lookup room (deteksi DM). +- `channels.nextcloud-talk.apiPassword`: kata sandi API/aplikasi untuk lookup room. +- `channels.nextcloud-talk.apiPasswordFile`: path file kata sandi API. +- `channels.nextcloud-talk.webhookPort`: port listener webhook (default: 8788). +- `channels.nextcloud-talk.webhookHost`: host webhook (default: 0.0.0.0). +- `channels.nextcloud-talk.webhookPath`: path webhook (default: /nextcloud-talk-webhook). +- `channels.nextcloud-talk.webhookPublicUrl`: URL webhook yang dapat dijangkau secara eksternal. +- `channels.nextcloud-talk.dmPolicy`: `pairing | allowlist | open | disabled`. +- `channels.nextcloud-talk.allowFrom`: allowlist DM (ID pengguna). `open` memerlukan `"*"`. +- `channels.nextcloud-talk.groupPolicy`: `allowlist | open | disabled`. +- `channels.nextcloud-talk.groupAllowFrom`: allowlist grup (ID pengguna). +- `channels.nextcloud-talk.rooms`: pengaturan per-room dan allowlist. +- `channels.nextcloud-talk.historyLimit`: batas riwayat grup (0 menonaktifkan). +- `channels.nextcloud-talk.dmHistoryLimit`: batas riwayat DM (0 menonaktifkan). +- `channels.nextcloud-talk.dms`: override per-DM (`historyLimit`). +- `channels.nextcloud-talk.textChunkLimit`: ukuran potongan teks keluar (karakter). +- `channels.nextcloud-talk.chunkMode`: `length` (default) atau `newline` untuk membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang. +- `channels.nextcloud-talk.blockStreaming`: nonaktifkan block streaming untuk channel ini. +- `channels.nextcloud-talk.blockStreamingCoalesce`: tuning penggabungan block streaming. +- `channels.nextcloud-talk.mediaMaxMb`: batas media masuk (MB). + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention +- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan +- [Security](/gateway/security) — model akses dan penguatan diff --git a/docs/id/channels/nostr.md b/docs/id/channels/nostr.md new file mode 100644 index 000000000..5035b432d --- /dev/null +++ b/docs/id/channels/nostr.md @@ -0,0 +1,259 @@ +--- +read_when: + - Anda ingin OpenClaw menerima DM melalui Nostr + - Anda sedang menyiapkan pesan terdesentralisasi +summary: Channel DM Nostr melalui pesan terenkripsi NIP-04 +title: Nostr +x-i18n: + generated_at: "2026-04-05T13:43:44Z" + model: gpt-5.4 + provider: openai + source_hash: f82829ee66fbeb3367007af343797140049ea49f2e842a695fa56acea0c80728 + source_path: channels/nostr.md + workflow: 15 +--- + +# Nostr + +**Status:** Plugin bawaan opsional (dinonaktifkan secara default sampai dikonfigurasi). + +Nostr adalah protokol terdesentralisasi untuk jejaring sosial. Channel ini memungkinkan OpenClaw menerima dan merespons pesan langsung terenkripsi (DM) melalui NIP-04. + +## Plugin bawaan + +Rilis OpenClaw saat ini mengirimkan Nostr sebagai plugin bawaan, jadi build paket normal +tidak memerlukan instalasi terpisah. + +### Instalasi lama/kustom + +- Onboarding (`openclaw onboard`) dan `openclaw channels add` tetap menampilkan + Nostr dari katalog channel bersama. +- Jika build Anda tidak menyertakan Nostr bawaan, instal secara manual. + +```bash +openclaw plugins install @openclaw/nostr +``` + +Gunakan checkout lokal (workflow dev): + +```bash +openclaw plugins install --link +``` + +Restart Gateway setelah menginstal atau mengaktifkan plugin. + +### Setup non-interaktif + +```bash +openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" +openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net" +``` + +Gunakan `--use-env` agar `NOSTR_PRIVATE_KEY` tetap berada di environment alih-alih menyimpan key di config. + +## Setup cepat + +1. Buat keypair Nostr (jika perlu): + +```bash +# Using nak +nak key generate +``` + +2. Tambahkan ke config: + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + }, + }, +} +``` + +3. Ekspor key: + +```bash +export NOSTR_PRIVATE_KEY="nsec1..." +``` + +4. Restart Gateway. + +## Referensi konfigurasi + +| Key | Tipe | Default | Deskripsi | +| ------------ | -------- | ------------------------------------------- | ------------------------------------ | +| `privateKey` | string | wajib | Private key dalam format `nsec` atau hex | +| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | URL relay (WebSocket) | +| `dmPolicy` | string | `pairing` | Kebijakan akses DM | +| `allowFrom` | string[] | `[]` | Pubkey pengirim yang diizinkan | +| `enabled` | boolean | `true` | Aktifkan/nonaktifkan channel | +| `name` | string | - | Nama tampilan | +| `profile` | object | - | Metadata profil NIP-01 | + +## Metadata profil + +Data profil dipublikasikan sebagai peristiwa NIP-01 `kind:0`. Anda dapat mengelolanya dari UI Control (Channels -> Nostr -> Profile) atau menyetelnya langsung di config. + +Contoh: + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + profile: { + name: "openclaw", + displayName: "OpenClaw", + about: "Personal assistant DM bot", + picture: "https://example.com/avatar.png", + banner: "https://example.com/banner.png", + website: "https://example.com", + nip05: "openclaw@example.com", + lud16: "openclaw@example.com", + }, + }, + }, +} +``` + +Catatan: + +- URL profil harus menggunakan `https://`. +- Mengimpor dari relay akan menggabungkan field dan mempertahankan override lokal. + +## Kontrol akses + +### Kebijakan DM + +- **pairing** (default): pengirim yang tidak dikenal mendapatkan kode pairing. +- **allowlist**: hanya pubkey dalam `allowFrom` yang dapat mengirim DM. +- **open**: DM masuk publik (memerlukan `allowFrom: ["*"]`). +- **disabled**: abaikan DM masuk. + +Catatan penegakan: + +- Tanda tangan peristiwa masuk diverifikasi sebelum kebijakan pengirim dan dekripsi NIP-04, sehingga peristiwa palsu ditolak lebih awal. +- Balasan pairing dikirim tanpa memproses isi DM asli. +- DM masuk dibatasi lajunya dan payload yang terlalu besar dibuang sebelum dekripsi. + +### Contoh allowlist + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + dmPolicy: "allowlist", + allowFrom: ["npub1abc...", "npub1xyz..."], + }, + }, +} +``` + +## Format key + +Format yang diterima: + +- **Private key:** `nsec...` atau hex 64 karakter +- **Pubkey (`allowFrom`):** `npub...` atau hex + +## Relay + +Default: `relay.damus.io` dan `nos.lol`. + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + relays: ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"], + }, + }, +} +``` + +Tips: + +- Gunakan 2-3 relay untuk redundansi. +- Hindari terlalu banyak relay (latensi, duplikasi). +- Relay berbayar dapat meningkatkan keandalan. +- Relay lokal cocok untuk pengujian (`ws://localhost:7777`). + +## Dukungan protokol + +| NIP | Status | Deskripsi | +| ------ | ------------ | ----------------------------------- | +| NIP-01 | Didukung | Format peristiwa dasar + metadata profil | +| NIP-04 | Didukung | DM terenkripsi (`kind:4`) | +| NIP-17 | Direncanakan | DM gift-wrapped | +| NIP-44 | Direncanakan | Enkripsi berversi | + +## Pengujian + +### Relay lokal + +```bash +# Start strfry +docker run -p 7777:7777 ghcr.io/hoytech/strfry +``` + +```json5 +{ + channels: { + nostr: { + privateKey: "${NOSTR_PRIVATE_KEY}", + relays: ["ws://localhost:7777"], + }, + }, +} +``` + +### Pengujian manual + +1. Catat pubkey bot (npub) dari log. +2. Buka klien Nostr (Damus, Amethyst, dll.). +3. Kirim DM ke pubkey bot. +4. Verifikasi responsnya. + +## Pemecahan masalah + +### Tidak menerima pesan + +- Verifikasi bahwa private key valid. +- Pastikan URL relay dapat dijangkau dan menggunakan `wss://` (atau `ws://` untuk lokal). +- Konfirmasi `enabled` bukan `false`. +- Periksa log Gateway untuk error koneksi relay. + +### Tidak mengirim respons + +- Periksa apakah relay menerima penulisan. +- Verifikasi konektivitas keluar. +- Perhatikan rate limit relay. + +### Respons duplikat + +- Ini normal saat menggunakan beberapa relay. +- Pesan dideduplikasi berdasarkan ID peristiwa; hanya pengiriman pertama yang memicu respons. + +## Keamanan + +- Jangan pernah meng-commit private key. +- Gunakan variabel environment untuk key. +- Pertimbangkan `allowlist` untuk bot produksi. +- Tanda tangan diverifikasi sebelum kebijakan pengirim, dan kebijakan pengirim diberlakukan sebelum dekripsi, sehingga peristiwa palsu ditolak lebih awal dan pengirim yang tidak dikenal tidak dapat memaksa kerja kripto penuh. + +## Keterbatasan (MVP) + +- Hanya pesan langsung (tanpa obrolan grup). +- Tidak ada lampiran media. +- Hanya NIP-04 (gift-wrap NIP-17 direncanakan). + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Grup](/channels/groups) — perilaku obrolan grup dan gating mention +- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/pairing.md b/docs/id/channels/pairing.md new file mode 100644 index 000000000..16b145194 --- /dev/null +++ b/docs/id/channels/pairing.md @@ -0,0 +1,136 @@ +--- +read_when: + - Menyiapkan kontrol akses DM + - Melakukan pairing node iOS/Android baru + - Meninjau postur keamanan OpenClaw +summary: 'Ikhtisar pairing: setujui siapa yang dapat mengirimi Anda DM + node mana yang dapat bergabung' +title: Pairing +x-i18n: + generated_at: "2026-04-05T13:43:46Z" + model: gpt-5.4 + provider: openai + source_hash: 2bd99240b3530def23c05a26915d07cf8b730565c2822c6338437f8fb3f285c9 + source_path: channels/pairing.md + workflow: 15 +--- + +# Pairing + +“Pairing” adalah langkah **persetujuan pemilik** eksplisit OpenClaw. +Ini digunakan di dua tempat: + +1. **Pairing DM** (siapa yang diizinkan berbicara dengan bot) +2. **Pairing node** (perangkat/node mana yang diizinkan bergabung ke jaringan gateway) + +Konteks keamanan: [Keamanan](/gateway/security) + +## 1) Pairing DM (akses chat masuk) + +Saat sebuah channel dikonfigurasi dengan kebijakan DM `pairing`, pengirim yang tidak dikenal akan mendapatkan kode singkat dan pesan mereka **tidak diproses** sampai Anda menyetujuinya. + +Kebijakan DM default didokumentasikan di: [Keamanan](/gateway/security) + +Kode pairing: + +- 8 karakter, huruf besar, tanpa karakter ambigu (`0O1I`). +- **Kedaluwarsa setelah 1 jam**. Bot hanya mengirim pesan pairing saat permintaan baru dibuat (kurang lebih sekali per jam per pengirim). +- Permintaan pairing DM yang tertunda dibatasi maksimal **3 per channel** secara default; permintaan tambahan diabaikan sampai salah satunya kedaluwarsa atau disetujui. + +### Menyetujui pengirim + +```bash +openclaw pairing list telegram +openclaw pairing approve telegram +``` + +Channel yang didukung: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`. + +### Tempat status disimpan + +Disimpan di bawah `~/.openclaw/credentials/`: + +- Permintaan tertunda: `-pairing.json` +- Penyimpanan allowlist yang disetujui: + - Akun default: `-allowFrom.json` + - Akun non-default: `--allowFrom.json` + +Perilaku cakupan akun: + +- Akun non-default hanya membaca/menulis file allowlist dalam cakupannya. +- Akun default menggunakan file allowlist tanpa cakupan yang dicakup per channel. + +Anggap ini sensitif (karena menentukan akses ke asisten Anda). + +Penting: penyimpanan ini untuk akses DM. Otorisasi grup terpisah. +Menyetujui kode pairing DM tidak secara otomatis mengizinkan pengirim tersebut menjalankan perintah grup atau mengontrol bot di grup. Untuk akses grup, konfigurasikan allowlist grup eksplisit milik channel tersebut (misalnya `groupAllowFrom`, `groups`, atau override per grup/per topik tergantung channel). + +## 2) Pairing perangkat node (node iOS/Android/macOS/headless) + +Node terhubung ke Gateway sebagai **perangkat** dengan `role: node`. Gateway +membuat permintaan pairing perangkat yang harus disetujui. + +### Pair melalui Telegram (direkomendasikan untuk iOS) + +Jika Anda menggunakan plugin `device-pair`, Anda dapat melakukan pairing perangkat pertama kali sepenuhnya dari Telegram: + +1. Di Telegram, kirim pesan ke bot Anda: `/pair` +2. Bot membalas dengan dua pesan: pesan instruksi dan pesan **kode penyiapan** terpisah (mudah untuk disalin/ditempel di Telegram). +3. Di ponsel Anda, buka aplikasi OpenClaw iOS → Settings → Gateway. +4. Tempel kode penyiapan lalu sambungkan. +5. Kembali ke Telegram: `/pair pending` (tinjau ID permintaan, role, dan scope), lalu setujui. + +Kode penyiapan adalah payload JSON terenkripsi base64 yang berisi: + +- `url`: URL WebSocket Gateway (`ws://...` atau `wss://...`) +- `bootstrapToken`: token bootstrap satu perangkat yang berumur pendek dan digunakan untuk handshake pairing awal + +Token bootstrap tersebut membawa profil bootstrap pairing bawaan: + +- token `node` utama yang diserahkan tetap `scopes: []` +- token `operator` yang diserahkan tetap dibatasi ke allowlist bootstrap: + `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` +- pemeriksaan scope bootstrap diberi awalan role, bukan satu kumpulan scope datar: + entri scope operator hanya memenuhi permintaan operator, dan role non-operator + tetap harus meminta scope di bawah awalan role mereka sendiri + +Perlakukan kode penyiapan seperti kata sandi selama masih berlaku. + +### Menyetujui perangkat node + +```bash +openclaw devices list +openclaw devices approve +openclaw devices reject +``` + +Jika perangkat yang sama mencoba lagi dengan detail autentikasi berbeda (misalnya +role/scope/public key yang berbeda), permintaan tertunda sebelumnya akan digantikan dan +`requestId` baru akan dibuat. + +### Penyimpanan status pairing node + +Disimpan di bawah `~/.openclaw/devices/`: + +- `pending.json` (berumur pendek; permintaan tertunda akan kedaluwarsa) +- `paired.json` (perangkat yang sudah dipairing + token) + +### Catatan + +- API `node.pair.*` lama (CLI: `openclaw nodes pending|approve|reject|rename`) adalah + penyimpanan pairing terpisah milik gateway. Node WS tetap memerlukan pairing perangkat. +- Rekaman pairing adalah sumber kebenaran tahan lama untuk role yang disetujui. Token + perangkat aktif tetap dibatasi ke kumpulan role yang disetujui tersebut; entri token + liar di luar role yang disetujui tidak menciptakan akses baru. + +## Dokumen terkait + +- Model keamanan + prompt injection: [Keamanan](/gateway/security) +- Memperbarui dengan aman (jalankan doctor): [Memperbarui](/install/updating) +- Konfigurasi channel: + - Telegram: [Telegram](/channels/telegram) + - WhatsApp: [WhatsApp](/channels/whatsapp) + - Signal: [Signal](/channels/signal) + - BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles) + - iMessage (lama): [iMessage](/channels/imessage) + - Discord: [Discord](/channels/discord) + - Slack: [Slack](/channels/slack) diff --git a/docs/id/channels/qqbot.md b/docs/id/channels/qqbot.md new file mode 100644 index 000000000..82775e5b9 --- /dev/null +++ b/docs/id/channels/qqbot.md @@ -0,0 +1,200 @@ +--- +read_when: + - Anda ingin menghubungkan OpenClaw ke QQ + - Anda memerlukan penyiapan kredensial QQ Bot + - Anda ingin dukungan grup atau obrolan pribadi QQ Bot +summary: Penyiapan, konfigurasi, dan penggunaan QQ Bot +title: QQ Bot +x-i18n: + generated_at: "2026-04-05T13:43:54Z" + model: gpt-5.4 + provider: openai + source_hash: 0e58fb7b07c59ecbf80a1276368c4a007b45d84e296ed40cffe9845e0953696c + source_path: channels/qqbot.md + workflow: 15 +--- + +# QQ Bot + +QQ Bot terhubung ke OpenClaw melalui API resmi QQ Bot (gateway WebSocket). Plugin +ini mendukung obrolan pribadi C2C, @message grup, dan pesan channel guild dengan +media kaya (gambar, suara, video, file). + +Status: plugin bawaan. Pesan langsung, obrolan grup, channel guild, dan +media didukung. Reaksi dan thread tidak didukung. + +## Plugin bawaan + +Rilis OpenClaw saat ini menyertakan QQ Bot, jadi build paket normal tidak memerlukan +langkah `openclaw plugins install` terpisah. + +## Penyiapan + +1. Buka [QQ Open Platform](https://q.qq.com/) dan pindai kode QR dengan + QQ di ponsel Anda untuk mendaftar / masuk. +2. Klik **Create Bot** untuk membuat bot QQ baru. +3. Temukan **AppID** dan **AppSecret** di halaman pengaturan bot dan salin. + +> AppSecret tidak disimpan dalam plaintext — jika Anda meninggalkan halaman tanpa menyimpannya, +> Anda harus membuat ulang yang baru. + +4. Tambahkan channel: + +```bash +openclaw channels add --channel qqbot --token "AppID:AppSecret" +``` + +5. Mulai ulang Gateway. + +Path penyiapan interaktif: + +```bash +openclaw channels add +openclaw configure --section channels +``` + +## Konfigurasi + +Konfigurasi minimal: + +```json5 +{ + channels: { + qqbot: { + enabled: true, + appId: "YOUR_APP_ID", + clientSecret: "YOUR_APP_SECRET", + }, + }, +} +``` + +Variabel lingkungan akun default: + +- `QQBOT_APP_ID` +- `QQBOT_CLIENT_SECRET` + +AppSecret berbasis file: + +```json5 +{ + channels: { + qqbot: { + enabled: true, + appId: "YOUR_APP_ID", + clientSecretFile: "/path/to/qqbot-secret.txt", + }, + }, +} +``` + +Catatan: + +- Fallback env hanya berlaku untuk akun default QQ Bot. +- `openclaw channels add --channel qqbot --token-file ...` hanya menyediakan + AppSecret; AppID harus sudah ditetapkan di konfigurasi atau `QQBOT_APP_ID`. +- `clientSecret` juga menerima input SecretRef, bukan hanya string plaintext. + +### Penyiapan multi-akun + +Jalankan beberapa bot QQ dalam satu instance OpenClaw: + +```json5 +{ + channels: { + qqbot: { + enabled: true, + appId: "111111111", + clientSecret: "secret-of-bot-1", + accounts: { + bot2: { + enabled: true, + appId: "222222222", + clientSecret: "secret-of-bot-2", + }, + }, + }, + }, +} +``` + +Setiap akun meluncurkan koneksi WebSocket-nya sendiri dan mempertahankan cache +token yang independen (diisolasi berdasarkan `appId`). + +Tambahkan bot kedua melalui CLI: + +```bash +openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2" +``` + +### Suara (STT / TTS) + +Dukungan STT dan TTS menggunakan konfigurasi dua tingkat dengan fallback prioritas: + +| Pengaturan | Khusus plugin | Fallback framework | +| ---------- | --------------------- | ----------------------------- | +| STT | `channels.qqbot.stt` | `tools.media.audio.models[0]` | +| TTS | `channels.qqbot.tts` | `messages.tts` | + +```json5 +{ + channels: { + qqbot: { + stt: { + provider: "your-provider", + model: "your-stt-model", + }, + tts: { + provider: "your-provider", + model: "your-tts-model", + voice: "your-voice", + }, + }, + }, +} +``` + +Tetapkan `enabled: false` pada salah satu untuk menonaktifkannya. + +Perilaku upload/transcode audio outbound juga dapat disetel dengan +`channels.qqbot.audioFormatPolicy`: + +- `sttDirectFormats` +- `uploadDirectFormats` +- `transcodeEnabled` + +## Format target + +| Format | Deskripsi | +| -------------------------- | ------------------- | +| `qqbot:c2c:OPENID` | Obrolan pribadi (C2C) | +| `qqbot:group:GROUP_OPENID` | Obrolan grup | +| `qqbot:channel:CHANNEL_ID` | Channel guild | + +> Setiap bot memiliki kumpulan OpenID penggunanya sendiri. OpenID yang diterima oleh Bot A **tidak dapat** +> digunakan untuk mengirim pesan melalui Bot B. + +## Slash command + +Perintah bawaan yang dicegat sebelum antrean AI: + +| Perintah | Deskripsi | +| -------------- | -------------------------------------- | +| `/bot-ping` | Uji latensi | +| `/bot-version` | Tampilkan versi framework OpenClaw | +| `/bot-help` | Daftarkan semua perintah | +| `/bot-upgrade` | Tampilkan tautan panduan upgrade QQBot | +| `/bot-logs` | Ekspor log gateway terbaru sebagai file | + +Tambahkan `?` ke perintah apa pun untuk bantuan penggunaan (misalnya `/bot-upgrade ?`). + +## Pemecahan masalah + +- **Bot membalas "gone to Mars":** kredensial belum dikonfigurasi atau Gateway belum dijalankan. +- **Tidak ada pesan masuk:** verifikasi bahwa `appId` dan `clientSecret` benar, dan + bot diaktifkan di QQ Open Platform. +- **Penyiapan dengan `--token-file` masih menunjukkan belum dikonfigurasi:** `--token-file` hanya menetapkan + AppSecret. Anda tetap memerlukan `appId` di konfigurasi atau `QQBOT_APP_ID`. +- **Pesan proaktif tidak sampai:** QQ dapat mencegat pesan yang diprakarsai bot jika + pengguna belum berinteraksi baru-baru ini. +- **Suara tidak ditranskripsikan:** pastikan STT sudah dikonfigurasi dan provider dapat dijangkau. diff --git a/docs/id/channels/signal.md b/docs/id/channels/signal.md new file mode 100644 index 000000000..ef252a86f --- /dev/null +++ b/docs/id/channels/signal.md @@ -0,0 +1,344 @@ +--- +read_when: + - Menyiapkan dukungan Signal + - Men-debug kirim/terima Signal +summary: Dukungan Signal melalui signal-cli (JSON-RPC + SSE), jalur penyiapan, dan model nomor +title: Signal +x-i18n: + generated_at: "2026-04-05T13:44:20Z" + model: gpt-5.4 + provider: openai + source_hash: cdd855eb353aca6a1c2b04d14af0e3da079349297b54fa8243562c52b29118d9 + source_path: channels/signal.md + workflow: 15 +--- + +# Signal (signal-cli) + +Status: integrasi CLI eksternal. Gateway berkomunikasi dengan `signal-cli` melalui HTTP JSON-RPC + SSE. + +## Prasyarat + +- OpenClaw terinstal di server Anda (alur Linux di bawah telah diuji pada Ubuntu 24). +- `signal-cli` tersedia di host tempat gateway berjalan. +- Nomor telepon yang dapat menerima satu SMS verifikasi (untuk jalur pendaftaran SMS). +- Akses browser untuk captcha Signal (`signalcaptchas.org`) selama pendaftaran. + +## Penyiapan cepat (pemula) + +1. Gunakan **nomor Signal terpisah** untuk bot (direkomendasikan). +2. Instal `signal-cli` (Java diperlukan jika Anda menggunakan build JVM). +3. Pilih salah satu jalur penyiapan: + - **Jalur A (tautan QR):** `signal-cli link -n "OpenClaw"` lalu pindai dengan Signal. + - **Jalur B (daftar SMS):** daftarkan nomor khusus dengan captcha + verifikasi SMS. +4. Konfigurasikan OpenClaw dan mulai ulang gateway. +5. Kirim DM pertama dan setujui pairing (`openclaw pairing approve signal `). + +Config minimal: + +```json5 +{ + channels: { + signal: { + enabled: true, + account: "+15551234567", + cliPath: "signal-cli", + dmPolicy: "pairing", + allowFrom: ["+15557654321"], + }, + }, +} +``` + +Referensi bidang: + +| Bidang | Deskripsi | +| ----------- | -------------------------------------------------- | +| `account` | Nomor telepon bot dalam format E.164 (`+15551234567`) | +| `cliPath` | Path ke `signal-cli` (`signal-cli` jika ada di `PATH`) | +| `dmPolicy` | Kebijakan akses DM (`pairing` direkomendasikan) | +| `allowFrom` | Nomor telepon atau nilai `uuid:` yang diizinkan untuk DM | + +## Apa itu + +- Channel Signal melalui `signal-cli` (bukan libsignal tertanam). +- Perutean deterministik: balasan selalu kembali ke Signal. +- DM berbagi sesi utama agen; grup diisolasi (`agent::signal:group:`). + +## Penulisan config + +Secara default, Signal diizinkan menulis pembaruan config yang dipicu oleh `/config set|unset` (memerlukan `commands.config: true`). + +Nonaktifkan dengan: + +```json5 +{ + channels: { signal: { configWrites: false } }, +} +``` + +## Model nomor (penting) + +- Gateway terhubung ke **perangkat Signal** (akun `signal-cli`). +- Jika Anda menjalankan bot pada **akun Signal pribadi Anda**, bot akan mengabaikan pesan Anda sendiri (perlindungan loop). +- Untuk "saya mengirim pesan ke bot dan bot membalas," gunakan **nomor bot terpisah**. + +## Jalur penyiapan A: tautkan akun Signal yang ada (QR) + +1. Instal `signal-cli` (build JVM atau native). +2. Tautkan akun bot: + - `signal-cli link -n "OpenClaw"` lalu pindai QR di Signal. +3. Konfigurasikan Signal dan mulai gateway. + +Contoh: + +```json5 +{ + channels: { + signal: { + enabled: true, + account: "+15551234567", + cliPath: "signal-cli", + dmPolicy: "pairing", + allowFrom: ["+15557654321"], + }, + }, +} +``` + +Dukungan multi-akun: gunakan `channels.signal.accounts` dengan config per akun dan `name` opsional. Lihat [`gateway/configuration`](/gateway/configuration-reference#multi-account-all-channels) untuk pola bersama. + +## Jalur penyiapan B: daftarkan nomor bot khusus (SMS, Linux) + +Gunakan ini jika Anda ingin nomor bot khusus alih-alih menautkan akun aplikasi Signal yang sudah ada. + +1. Dapatkan nomor yang dapat menerima SMS (atau verifikasi suara untuk telepon rumah). + - Gunakan nomor bot khusus untuk menghindari konflik akun/sesi. +2. Instal `signal-cli` di host gateway: + +```bash +VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//') +curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}-Linux-native.tar.gz" +sudo tar xf "signal-cli-${VERSION}-Linux-native.tar.gz" -C /opt +sudo ln -sf /opt/signal-cli /usr/local/bin/ +signal-cli --version +``` + +Jika Anda menggunakan build JVM (`signal-cli-${VERSION}.tar.gz`), instal JRE 25+ terlebih dahulu. +Pastikan `signal-cli` tetap diperbarui; upstream mencatat bahwa rilis lama dapat rusak saat API server Signal berubah. + +3. Daftarkan dan verifikasi nomor: + +```bash +signal-cli -a + register +``` + +Jika captcha diperlukan: + +1. Buka `https://signalcaptchas.org/registration/generate.html`. +2. Selesaikan captcha, salin target tautan `signalcaptcha://...` dari "Open Signal". +3. Jalankan dari IP eksternal yang sama dengan sesi browser jika memungkinkan. +4. Jalankan pendaftaran lagi segera (token captcha cepat kedaluwarsa): + +```bash +signal-cli -a + register --captcha '' +signal-cli -a + verify +``` + +4. Konfigurasikan OpenClaw, mulai ulang gateway, verifikasi channel: + +```bash +# Jika Anda menjalankan gateway sebagai layanan systemd pengguna: +systemctl --user restart openclaw-gateway.service + +# Lalu verifikasi: +openclaw doctor +openclaw channels status --probe +``` + +5. Pair pengirim DM Anda: + - Kirim pesan apa pun ke nomor bot. + - Setujui kode di server: `openclaw pairing approve signal `. + - Simpan nomor bot sebagai kontak di ponsel Anda untuk menghindari "Unknown contact". + +Penting: mendaftarkan akun nomor telepon dengan `signal-cli` dapat menghapus autentikasi sesi aplikasi Signal utama untuk nomor tersebut. Sebaiknya gunakan nomor bot khusus, atau gunakan mode tautan QR jika Anda perlu mempertahankan penyiapan aplikasi ponsel yang ada. + +Referensi upstream: + +- README `signal-cli`: `https://github.com/AsamK/signal-cli` +- Alur captcha: `https://github.com/AsamK/signal-cli/wiki/Registration-with-captcha` +- Alur penautan: `https://github.com/AsamK/signal-cli/wiki/Linking-other-devices-(Provisioning)` + +## Mode daemon eksternal (httpUrl) + +Jika Anda ingin mengelola `signal-cli` sendiri (cold start JVM lambat, inisialisasi container, atau CPU bersama), jalankan daemon secara terpisah dan arahkan OpenClaw ke sana: + +```json5 +{ + channels: { + signal: { + httpUrl: "http://127.0.0.1:8080", + autoStart: false, + }, + }, +} +``` + +Ini melewati auto-spawn dan waktu tunggu startup di dalam OpenClaw. Untuk startup lambat saat auto-spawn, atur `channels.signal.startupTimeoutMs`. + +## Kontrol akses (DM + grup) + +DM: + +- Default: `channels.signal.dmPolicy = "pairing"`. +- Pengirim yang tidak dikenal menerima kode pairing; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam). +- Setujui melalui: + - `openclaw pairing list signal` + - `openclaw pairing approve signal ` +- Pairing adalah pertukaran token default untuk DM Signal. Detail: [Pairing](/channels/pairing) +- Pengirim khusus UUID (dari `sourceUuid`) disimpan sebagai `uuid:` di `channels.signal.allowFrom`. + +Grup: + +- `channels.signal.groupPolicy = open | allowlist | disabled`. +- `channels.signal.groupAllowFrom` mengontrol siapa yang dapat memicu di grup saat `allowlist` diatur. +- `channels.signal.groups["" | "*"]` dapat mengganti perilaku grup dengan `requireMention`, `tools`, dan `toolsBySender`. +- Gunakan `channels.signal.accounts..groups` untuk override per akun dalam penyiapan multi-akun. +- Catatan runtime: jika `channels.signal` tidak ada sama sekali, runtime akan fallback ke `groupPolicy="allowlist"` untuk pemeriksaan grup (bahkan jika `channels.defaults.groupPolicy` diatur). + +## Cara kerjanya (perilaku) + +- `signal-cli` berjalan sebagai daemon; gateway membaca peristiwa melalui SSE. +- Pesan masuk dinormalisasi ke dalam envelope channel bersama. +- Balasan selalu dirutekan kembali ke nomor atau grup yang sama. + +## Media + batas + +- Teks keluar dipotong menurut `channels.signal.textChunkLimit` (default 4000). +- Pemotongan newline opsional: atur `channels.signal.chunkMode="newline"` untuk membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang. +- Lampiran didukung (base64 diambil dari `signal-cli`). +- Batas media default: `channels.signal.mediaMaxMb` (default 8). +- Gunakan `channels.signal.ignoreAttachments` untuk melewati unduhan media. +- Konteks riwayat grup menggunakan `channels.signal.historyLimit` (atau `channels.signal.accounts.*.historyLimit`), fallback ke `messages.groupChat.historyLimit`. Atur `0` untuk menonaktifkan (default 50). + +## Tanda mengetik + tanda baca + +- **Indikator mengetik**: OpenClaw mengirim sinyal mengetik melalui `signal-cli sendTyping` dan menyegarkannya saat balasan sedang berlangsung. +- **Tanda baca**: saat `channels.signal.sendReadReceipts` bernilai true, OpenClaw meneruskan tanda baca untuk DM yang diizinkan. +- Signal-cli tidak mengekspos tanda baca untuk grup. + +## Reactions (alat pesan) + +- Gunakan `message action=react` dengan `channel=signal`. +- Target: pengirim E.164 atau UUID (gunakan `uuid:` dari output pairing; UUID polos juga berfungsi). +- `messageId` adalah timestamp Signal untuk pesan yang Anda beri reaction. +- Reaction grup memerlukan `targetAuthor` atau `targetAuthorUuid`. + +Contoh: + +``` +message action=react channel=signal target=uuid:123e4567-e89b-12d3-a456-426614174000 messageId=1737630212345 emoji=🔥 +message action=react channel=signal target=+15551234567 messageId=1737630212345 emoji=🔥 remove=true +message action=react channel=signal target=signal:group: targetAuthor=uuid: messageId=1737630212345 emoji=✅ +``` + +Config: + +- `channels.signal.actions.reactions`: aktifkan/nonaktifkan action reaction (default true). +- `channels.signal.reactionLevel`: `off | ack | minimal | extensive`. + - `off`/`ack` menonaktifkan reaction agen (alat pesan `react` akan menghasilkan error). + - `minimal`/`extensive` mengaktifkan reaction agen dan menetapkan tingkat panduan. +- Override per akun: `channels.signal.accounts..actions.reactions`, `channels.signal.accounts..reactionLevel`. + +## Target pengiriman (CLI/cron) + +- DM: `signal:+15551234567` (atau E.164 polos). +- DM UUID: `uuid:` (atau UUID polos). +- Grup: `signal:group:`. +- Nama pengguna: `username:` (jika didukung oleh akun Signal Anda). + +## Pemecahan masalah + +Jalankan langkah ini terlebih dahulu: + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +Lalu konfirmasi status pairing DM jika diperlukan: + +```bash +openclaw pairing list signal +``` + +Kegagalan umum: + +- Daemon dapat dijangkau tetapi tidak ada balasan: verifikasi pengaturan akun/daemon (`httpUrl`, `account`) dan mode penerimaan. +- DM diabaikan: pengirim masih menunggu persetujuan pairing. +- Pesan grup diabaikan: pembatasan pengirim/mention grup memblokir pengiriman. +- Error validasi config setelah pengeditan: jalankan `openclaw doctor --fix`. +- Signal tidak muncul dalam diagnostik: pastikan `channels.signal.enabled: true`. + +Pemeriksaan tambahan: + +```bash +openclaw pairing list signal +pgrep -af signal-cli +grep -i "signal" "/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log" | tail -20 +``` + +Untuk alur triase: [/channels/troubleshooting](/channels/troubleshooting). + +## Catatan keamanan + +- `signal-cli` menyimpan kunci akun secara lokal (biasanya `~/.local/share/signal-cli/data/`). +- Cadangkan status akun Signal sebelum migrasi atau rebuild server. +- Pertahankan `channels.signal.dmPolicy: "pairing"` kecuali Anda memang ingin akses DM yang lebih luas. +- Verifikasi SMS hanya diperlukan untuk alur pendaftaran atau pemulihan, tetapi kehilangan kendali atas nomor/akun dapat mempersulit pendaftaran ulang. + +## Referensi konfigurasi (Signal) + +Konfigurasi lengkap: [Configuration](/gateway/configuration) + +Opsi provider: + +- `channels.signal.enabled`: aktifkan/nonaktifkan startup channel. +- `channels.signal.account`: E.164 untuk akun bot. +- `channels.signal.cliPath`: path ke `signal-cli`. +- `channels.signal.httpUrl`: URL daemon lengkap (menggantikan host/port). +- `channels.signal.httpHost`, `channels.signal.httpPort`: bind daemon (default 127.0.0.1:8080). +- `channels.signal.autoStart`: auto-spawn daemon (default true jika `httpUrl` tidak diatur). +- `channels.signal.startupTimeoutMs`: batas waktu tunggu startup dalam ms (maksimum 120000). +- `channels.signal.receiveMode`: `on-start | manual`. +- `channels.signal.ignoreAttachments`: lewati unduhan lampiran. +- `channels.signal.ignoreStories`: abaikan story dari daemon. +- `channels.signal.sendReadReceipts`: teruskan tanda baca. +- `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing). +- `channels.signal.allowFrom`: allowlist DM (E.164 atau `uuid:`). `open` memerlukan `"*"`. Signal tidak memiliki username; gunakan ID telepon/UUID. +- `channels.signal.groupPolicy`: `open | allowlist | disabled` (default: allowlist). +- `channels.signal.groupAllowFrom`: allowlist pengirim grup. +- `channels.signal.groups`: override per grup yang dikunci dengan id grup Signal (atau `"*"`). Bidang yang didukung: `requireMention`, `tools`, `toolsBySender`. +- `channels.signal.accounts..groups`: versi per akun dari `channels.signal.groups` untuk penyiapan multi-akun. +- `channels.signal.historyLimit`: jumlah maksimum pesan grup yang disertakan sebagai konteks (0 menonaktifkan). +- `channels.signal.dmHistoryLimit`: batas riwayat DM dalam giliran pengguna. Override per pengguna: `channels.signal.dms[""].historyLimit`. +- `channels.signal.textChunkLimit`: ukuran potongan keluar (karakter). +- `channels.signal.chunkMode`: `length` (default) atau `newline` untuk membagi pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang. +- `channels.signal.mediaMaxMb`: batas media masuk/keluar (MB). + +Opsi global terkait: + +- `agents.list[].groupChat.mentionPatterns` (Signal tidak mendukung mention native). +- `messages.groupChat.mentionPatterns` (fallback global). +- `messages.responsePrefix`. + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention +- [Channel Routing](/channels/channel-routing) — perutean sesi untuk pesan +- [Security](/gateway/security) — model akses dan penguatan diff --git a/docs/id/channels/slack.md b/docs/id/channels/slack.md new file mode 100644 index 000000000..e7ca3aaeb --- /dev/null +++ b/docs/id/channels/slack.md @@ -0,0 +1,688 @@ +--- +read_when: + - Menyiapkan Slack atau men-debug mode socket/HTTP Slack +summary: Setup Slack dan perilaku runtime (Socket Mode + HTTP Events API) +title: Slack +x-i18n: + generated_at: "2026-04-05T13:44:44Z" + model: gpt-5.4 + provider: openai + source_hash: efb37e1f04e1ac8ac3786c36ffc20013dacdc654bfa61e7f6e8df89c4902d2ab + source_path: channels/slack.md + workflow: 15 +--- + +# Slack + +Status: siap produksi untuk DM + channel melalui integrasi aplikasi Slack. Mode default adalah Socket Mode; mode HTTP Events API juga didukung. + + + + DM Slack secara default menggunakan mode pairing. + + + Perilaku perintah native dan katalog perintah. + + + Diagnostik lintas channel dan playbook perbaikan. + + + +## Setup cepat + + + + + + Di pengaturan aplikasi Slack: + + - aktifkan **Socket Mode** + - buat **App Token** (`xapp-...`) dengan `connections:write` + - instal aplikasi dan salin **Bot Token** (`xoxb-...`) + + + + +```json5 +{ + channels: { + slack: { + enabled: true, + mode: "socket", + appToken: "xapp-...", + botToken: "xoxb-...", + }, + }, +} +``` + + Fallback env (hanya akun default): + +```bash +SLACK_APP_TOKEN=xapp-... +SLACK_BOT_TOKEN=xoxb-... +``` + + + + + Subscribe event bot untuk: + + - `app_mention` + - `message.channels`, `message.groups`, `message.im`, `message.mpim` + - `reaction_added`, `reaction_removed` + - `member_joined_channel`, `member_left_channel` + - `channel_rename` + - `pin_added`, `pin_removed` + + Aktifkan juga App Home **Messages Tab** untuk DM. + + + + +```bash +openclaw gateway +``` + + + + + + + + + + + - setel mode ke HTTP (`channels.slack.mode="http"`) + - salin Slack **Signing Secret** + - setel Request URL untuk Event Subscriptions + Interactivity + Slash command ke path webhook yang sama (default `/slack/events`) + + + + + +```json5 +{ + channels: { + slack: { + enabled: true, + mode: "http", + botToken: "xoxb-...", + signingSecret: "your-signing-secret", + webhookPath: "/slack/events", + }, + }, +} +``` + + + + + Mode HTTP per akun didukung. + + Berikan `webhookPath` yang berbeda untuk setiap akun agar pendaftaran tidak saling bertabrakan. + + + + + + +## Checklist manifest dan scope + + + + +```json +{ + "display_information": { + "name": "OpenClaw", + "description": "Slack connector for OpenClaw" + }, + "features": { + "bot_user": { + "display_name": "OpenClaw", + "always_online": true + }, + "app_home": { + "messages_tab_enabled": true, + "messages_tab_read_only_enabled": false + }, + "slash_commands": [ + { + "command": "/openclaw", + "description": "Send a message to OpenClaw", + "should_escape": false + } + ] + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "assistant:write", + "channels:history", + "channels:read", + "chat:write", + "commands", + "emoji:read", + "files:read", + "files:write", + "groups:history", + "groups:read", + "im:history", + "im:read", + "im:write", + "mpim:history", + "mpim:read", + "mpim:write", + "pins:read", + "pins:write", + "reactions:read", + "reactions:write", + "users:read" + ] + } + }, + "settings": { + "socket_mode_enabled": true, + "event_subscriptions": { + "bot_events": [ + "app_mention", + "channel_rename", + "member_joined_channel", + "member_left_channel", + "message.channels", + "message.groups", + "message.im", + "message.mpim", + "pin_added", + "pin_removed", + "reaction_added", + "reaction_removed" + ] + } + } +} +``` + + + + + Jika Anda mengonfigurasi `channels.slack.userToken`, scope baca yang umum adalah: + + - `channels:history`, `groups:history`, `im:history`, `mpim:history` + - `channels:read`, `groups:read`, `im:read`, `mpim:read` + - `users:read` + - `reactions:read` + - `pins:read` + - `emoji:read` + - `search:read` (jika Anda bergantung pada pembacaan pencarian Slack) + + + + +## Model token + +- `botToken` + `appToken` wajib untuk Socket Mode. +- Mode HTTP memerlukan `botToken` + `signingSecret`. +- `botToken`, `appToken`, `signingSecret`, dan `userToken` menerima + string plaintext atau objek SecretRef. +- Token config menimpa fallback env. +- Fallback env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` hanya berlaku untuk akun default. +- `userToken` (`xoxp-...`) hanya config-only (tanpa fallback env) dan default ke perilaku read-only (`userTokenReadOnly: true`). +- Opsional: tambahkan `chat:write.customize` jika Anda ingin pesan keluar menggunakan identitas agen aktif (`username` dan ikon kustom). `icon_emoji` menggunakan sintaks `:emoji_name:`. + +Perilaku snapshot status: + +- Inspeksi akun Slack melacak field `*Source` dan `*Status` + per kredensial (`botToken`, `appToken`, `signingSecret`, `userToken`). +- Status bernilai `available`, `configured_unavailable`, atau `missing`. +- `configured_unavailable` berarti akun dikonfigurasi melalui SecretRef + atau sumber secret non-inline lain, tetapi jalur perintah/runtime saat ini + tidak dapat menyelesaikan nilai sebenarnya. +- Dalam mode HTTP, `signingSecretStatus` disertakan; dalam Socket Mode, + pasangan yang wajib adalah `botTokenStatus` + `appTokenStatus`. + + +Untuk tindakan/pembacaan direktori, user token dapat diprioritaskan jika dikonfigurasi. Untuk penulisan, bot token tetap diprioritaskan; penulisan dengan user token hanya diizinkan saat `userTokenReadOnly: false` dan bot token tidak tersedia. + + +## Tindakan dan gate + +Tindakan Slack dikendalikan oleh `channels.slack.actions.*`. + +Grup tindakan yang tersedia dalam tooling Slack saat ini: + +| Grup | Default | +| ---------- | ------- | +| messages | enabled | +| reactions | enabled | +| pins | enabled | +| memberInfo | enabled | +| emojiList | enabled | + +Tindakan pesan Slack saat ini mencakup `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info`, dan `emoji-list`. + +## Kontrol akses dan routing + + + + `channels.slack.dmPolicy` mengendalikan akses DM (legacy: `channels.slack.dm.policy`): + + - `pairing` (default) + - `allowlist` + - `open` (memerlukan `channels.slack.allowFrom` mencakup `"*"`; legacy: `channels.slack.dm.allowFrom`) + - `disabled` + + Flag DM: + + - `dm.enabled` (default true) + - `channels.slack.allowFrom` (disarankan) + - `dm.allowFrom` (legacy) + - `dm.groupEnabled` (group DM default false) + - `dm.groupChannels` (allowlist MPIM opsional) + + Prioritas multi-akun: + + - `channels.slack.accounts.default.allowFrom` hanya berlaku untuk akun `default`. + - Akun bernama mewarisi `channels.slack.allowFrom` saat `allowFrom` miliknya sendiri tidak disetel. + - Akun bernama tidak mewarisi `channels.slack.accounts.default.allowFrom`. + + Pairing di DM menggunakan `openclaw pairing approve slack `. + + + + + `channels.slack.groupPolicy` mengendalikan penanganan channel: + + - `open` + - `allowlist` + - `disabled` + + Allowlist channel berada di bawah `channels.slack.channels` dan sebaiknya menggunakan ID channel yang stabil. + + Catatan runtime: jika `channels.slack` sama sekali tidak ada (setup hanya env), runtime akan fallback ke `groupPolicy="allowlist"` dan mencatat peringatan (bahkan jika `channels.defaults.groupPolicy` disetel). + + Resolusi nama/ID: + + - entri allowlist channel dan entri allowlist DM diselesaikan saat startup jika akses token memungkinkan + - entri nama channel yang tidak dapat diselesaikan tetap disimpan seperti dikonfigurasi tetapi diabaikan untuk routing secara default + - otorisasi masuk dan routing channel secara default berbasis ID; pencocokan langsung username/slug memerlukan `channels.slack.dangerouslyAllowNameMatching: true` + + + + + Pesan channel secara default di-gate oleh mention. + + Sumber mention: + + - mention aplikasi eksplisit (`<@botId>`) + - pola regex mention (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) + - perilaku thread reply-to-bot implisit + + Kontrol per channel (`channels.slack.channels.`; nama hanya melalui resolusi startup atau `dangerouslyAllowNameMatching`): + + - `requireMention` + - `users` (allowlist) + - `allowBots` + - `skills` + - `systemPrompt` + - `tools`, `toolsBySender` + - format key `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, atau wildcard `"*"` + (key legacy tanpa prefiks masih dipetakan hanya ke `id:`) + + + + +## Threading, sesi, dan tag balasan + +- DM dirutekan sebagai `direct`; channel sebagai `channel`; MPIM sebagai `group`. +- Dengan default `session.dmScope=main`, DM Slack digabungkan ke sesi utama agen. +- Sesi channel: `agent::slack:channel:`. +- Balasan thread dapat membuat sufiks sesi thread (`:thread:`) jika berlaku. +- Default `channels.slack.thread.historyScope` adalah `thread`; default `thread.inheritParent` adalah `false`. +- `channels.slack.thread.initialHistoryLimit` mengendalikan berapa banyak pesan thread yang sudah ada diambil saat sesi thread baru dimulai (default `20`; set `0` untuk menonaktifkan). + +Kontrol reply threading: + +- `channels.slack.replyToMode`: `off|first|all` (default `off`) +- `channels.slack.replyToModeByChatType`: per `direct|group|channel` +- fallback legacy untuk obrolan langsung: `channels.slack.dm.replyToMode` + +Tag balasan manual didukung: + +- `[[reply_to_current]]` +- `[[reply_to:]]` + +Catatan: `replyToMode="off"` menonaktifkan **semua** reply threading di Slack, termasuk tag `[[reply_to_*]]` yang eksplisit. Ini berbeda dari Telegram, di mana tag eksplisit tetap dihormati dalam mode `"off"`. Perbedaan ini mencerminkan model threading platform: thread Slack menyembunyikan pesan dari channel, sedangkan balasan Telegram tetap terlihat di alur chat utama. + +## Reaksi ack + +`ackReaction` mengirim emoji tanda terima saat OpenClaw sedang memproses pesan masuk. + +Urutan resolusi: + +- `channels.slack.accounts..ackReaction` +- `channels.slack.ackReaction` +- `messages.ackReaction` +- fallback emoji identitas agen (`agents.list[].identity.emoji`, jika tidak ada gunakan "👀") + +Catatan: + +- Slack mengharapkan shortcode (misalnya `"eyes"`). +- Gunakan `""` untuk menonaktifkan reaksi untuk akun Slack atau secara global. + +## Streaming teks + +`channels.slack.streaming` mengendalikan perilaku pratinjau live: + +- `off`: nonaktifkan streaming pratinjau live. +- `partial` (default): ganti teks pratinjau dengan output parsial terbaru. +- `block`: tambahkan pembaruan pratinjau bertahap. +- `progress`: tampilkan teks status progres saat menghasilkan, lalu kirim teks akhir. + +`channels.slack.nativeStreaming` mengendalikan streaming teks native Slack saat `streaming` adalah `partial` (default: `true`). + +- Thread balasan harus tersedia agar streaming teks native muncul. Pemilihan thread tetap mengikuti `replyToMode`. Tanpanya, pratinjau draf normal akan digunakan. +- Media dan payload non-teks akan fallback ke pengiriman normal. +- Jika streaming gagal di tengah balasan, OpenClaw akan fallback ke pengiriman normal untuk payload yang tersisa. + +Gunakan pratinjau draf alih-alih streaming teks native Slack: + +```json5 +{ + channels: { + slack: { + streaming: "partial", + nativeStreaming: false, + }, + }, +} +``` + +Key legacy: + +- `channels.slack.streamMode` (`replace | status_final | append`) dimigrasikan otomatis ke `channels.slack.streaming`. +- boolean `channels.slack.streaming` dimigrasikan otomatis ke `channels.slack.nativeStreaming`. + +## Fallback reaksi mengetik + +`typingReaction` menambahkan reaksi sementara ke pesan Slack masuk saat OpenClaw sedang memproses balasan, lalu menghapusnya saat eksekusi selesai. Ini paling berguna di luar balasan thread, yang menggunakan indikator status default "is typing...". + +Urutan resolusi: + +- `channels.slack.accounts..typingReaction` +- `channels.slack.typingReaction` + +Catatan: + +- Slack mengharapkan shortcode (misalnya `"hourglass_flowing_sand"`). +- Reaksi ini bersifat best-effort dan pembersihannya dicoba secara otomatis setelah jalur balasan atau kegagalan selesai. + +## Media, chunking, dan pengiriman + + + + Lampiran file Slack diunduh dari URL privat yang di-host Slack (alur permintaan terautentikasi token) dan ditulis ke penyimpanan media saat pengambilan berhasil dan batas ukuran mengizinkan. + + Batas ukuran masuk runtime default adalah `20MB` kecuali ditimpa oleh `channels.slack.mediaMaxMb`. + + + + + - potongan teks menggunakan `channels.slack.textChunkLimit` (default 4000) + - `channels.slack.chunkMode="newline"` mengaktifkan pemisahan dengan prioritas paragraf + - pengiriman file menggunakan API upload Slack dan dapat menyertakan balasan thread (`thread_ts`) + - batas media keluar mengikuti `channels.slack.mediaMaxMb` saat dikonfigurasi; jika tidak, pengiriman channel menggunakan default jenis MIME dari pipeline media + + + + Target eksplisit yang disarankan: + + - `user:` untuk DM + - `channel:` untuk channel + + DM Slack dibuka melalui API percakapan Slack saat mengirim ke target pengguna. + + + + +## Perintah dan perilaku slash + +- Auto-mode perintah native adalah **off** untuk Slack (`commands.native: "auto"` tidak mengaktifkan perintah native Slack). +- Aktifkan handler perintah Slack native dengan `channels.slack.commands.native: true` (atau global `commands.native: true`). +- Saat perintah native diaktifkan, daftarkan slash command yang sesuai di Slack (nama `/`), dengan satu pengecualian: + - daftarkan `/agentstatus` untuk perintah status (Slack mencadangkan `/status`) +- Jika perintah native tidak diaktifkan, Anda dapat menjalankan satu slash command yang dikonfigurasi melalui `channels.slack.slashCommand`. +- Menu argumen native kini menyesuaikan strategi rendering-nya: + - hingga 5 opsi: blok tombol + - 6-100 opsi: menu select statis + - lebih dari 100 opsi: external select dengan penyaringan opsi async saat handler opsi interaktivitas tersedia + - jika nilai opsi yang dikodekan melebihi batas Slack, alur akan fallback ke tombol +- Untuk payload opsi yang panjang, menu argumen Slash command menggunakan dialog konfirmasi sebelum mengirim nilai yang dipilih. + +Pengaturan default slash command: + +- `enabled: false` +- `name: "openclaw"` +- `sessionPrefix: "slack:slash"` +- `ephemeral: true` + +Sesi slash menggunakan key terisolasi: + +- `agent::slack:slash:` + +dan tetap merutekan eksekusi perintah terhadap sesi percakapan target (`CommandTargetSessionKey`). + +## Balasan interaktif + +Slack dapat merender kontrol balasan interaktif yang ditulis agen, tetapi fitur ini dinonaktifkan secara default. + +Aktifkan secara global: + +```json5 +{ + channels: { + slack: { + capabilities: { + interactiveReplies: true, + }, + }, + }, +} +``` + +Atau aktifkan hanya untuk satu akun Slack: + +```json5 +{ + channels: { + slack: { + accounts: { + ops: { + capabilities: { + interactiveReplies: true, + }, + }, + }, + }, + }, +} +``` + +Saat diaktifkan, agen dapat mengeluarkan directive balasan khusus Slack: + +- `[[slack_buttons: Approve:approve, Reject:reject]]` +- `[[slack_select: Choose a target | Canary:canary, Production:production]]` + +Directive ini dikompilasi menjadi Slack Block Kit dan merutekan klik atau pilihan kembali melalui jalur event interaksi Slack yang ada. + +Catatan: + +- Ini adalah UI khusus Slack. Channel lain tidak menerjemahkan directive Slack Block Kit ke sistem tombol mereka sendiri. +- Nilai callback interaktif adalah token opak yang dibuat OpenClaw, bukan nilai mentah yang ditulis agen. +- Jika blok interaktif yang dihasilkan melebihi batas Slack Block Kit, OpenClaw akan fallback ke balasan teks asli alih-alih mengirim payload blocks yang tidak valid. + +## Persetujuan exec di Slack + +Slack dapat bertindak sebagai klien persetujuan native dengan tombol interaktif dan interaksi, alih-alih fallback ke UI Web atau terminal. + +- Persetujuan exec menggunakan `channels.slack.execApprovals.*` untuk routing DM/channel native. +- Persetujuan plugin tetap dapat diselesaikan melalui surface tombol native Slack yang sama saat permintaan sudah sampai di Slack dan jenis approval id adalah `plugin:`. +- Otorisasi approver tetap diberlakukan: hanya pengguna yang diidentifikasi sebagai approver yang dapat menyetujui atau menolak permintaan melalui Slack. + +Ini menggunakan surface tombol persetujuan bersama yang sama seperti channel lain. Saat `interactivity` diaktifkan di pengaturan aplikasi Slack Anda, prompt persetujuan dirender sebagai tombol Block Kit langsung di percakapan. +Saat tombol tersebut ada, itu menjadi UX persetujuan utama; OpenClaw +hanya boleh menyertakan perintah manual `/approve` saat hasil tool menyatakan persetujuan chat +tidak tersedia atau persetujuan manual adalah satu-satunya jalur. + +Path config: + +- `channels.slack.execApprovals.enabled` +- `channels.slack.execApprovals.approvers` (opsional; fallback ke `commands.ownerAllowFrom` jika memungkinkan) +- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`) +- `agentFilter`, `sessionFilter` + +Slack otomatis mengaktifkan persetujuan exec native saat `enabled` tidak disetel atau `"auto"` dan setidaknya satu +approver berhasil diselesaikan. Set `enabled: false` untuk menonaktifkan Slack sebagai klien persetujuan native secara eksplisit. +Set `enabled: true` untuk memaksa persetujuan native aktif saat approver berhasil diselesaikan. + +Perilaku default tanpa config persetujuan exec Slack eksplisit: + +```json5 +{ + commands: { + ownerAllowFrom: ["slack:U12345678"], + }, +} +``` + +Config native Slack eksplisit hanya diperlukan saat Anda ingin menimpa approver, menambahkan filter, atau +memilih pengiriman ke chat asal: + +```json5 +{ + channels: { + slack: { + execApprovals: { + enabled: true, + approvers: ["U12345678"], + target: "both", + }, + }, + }, +} +``` + +Forwarding bersama `approvals.exec` bersifat terpisah. Gunakan hanya saat prompt persetujuan exec juga harus +dirutekan ke chat lain atau target out-of-band eksplisit. Forwarding bersama `approvals.plugin` juga +terpisah; tombol native Slack tetap dapat menyelesaikan persetujuan plugin saat permintaan tersebut sudah sampai +di Slack. + +`/approve` pada chat yang sama juga berfungsi di channel dan DM Slack yang sudah mendukung perintah. Lihat [Exec approvals](/tools/exec-approvals) untuk model forwarding persetujuan lengkap. + +## Event dan perilaku operasional + +- Edit/hapus pesan/thread broadcast dipetakan ke peristiwa sistem. +- Event tambah/hapus reaksi dipetakan ke peristiwa sistem. +- Event anggota masuk/keluar, channel dibuat/diubah namanya, dan tambah/hapus pin dipetakan ke peristiwa sistem. +- `channel_id_changed` dapat memigrasikan key config channel saat `configWrites` diaktifkan. +- Metadata topik/tujuan channel diperlakukan sebagai konteks yang tidak tepercaya dan dapat disuntikkan ke konteks routing. +- Konteks awal thread starter dan riwayat thread awal difilter oleh allowlist pengirim yang dikonfigurasi jika berlaku. +- Tindakan blok dan interaksi modal menghasilkan peristiwa sistem terstruktur `Slack interaction: ...` dengan field payload kaya: + - block actions: nilai terpilih, label, nilai picker, dan metadata `workflow_*` + - event modal `view_submission` dan `view_closed` dengan metadata channel yang dirutekan dan input formulir + +## Petunjuk referensi konfigurasi + +Referensi utama: + +- [Referensi konfigurasi - Slack](/gateway/configuration-reference#slack) + + Field Slack dengan sinyal tinggi: + - mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` + - akses DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` + - toggle kompatibilitas: `dangerouslyAllowNameMatching` (break-glass; biarkan off kecuali diperlukan) + - akses channel: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` + - threading/history: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` + - pengiriman: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming` + - ops/fitur: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` + +## Pemecahan masalah + + + + Periksa, secara berurutan: + + - `groupPolicy` + - allowlist channel (`channels.slack.channels`) + - `requireMention` + - allowlist `users` per channel + + Perintah yang berguna: + +```bash +openclaw channels status --probe +openclaw logs --follow +openclaw doctor +``` + + + + + Periksa: + + - `channels.slack.dm.enabled` + - `channels.slack.dmPolicy` (atau legacy `channels.slack.dm.policy`) + - persetujuan pairing / entri allowlist + +```bash +openclaw pairing list slack +``` + + + + + Validasi token bot + aplikasi dan pengaktifan Socket Mode di pengaturan aplikasi Slack. + + Jika `openclaw channels status --probe --json` menampilkan `botTokenStatus` atau + `appTokenStatus: "configured_unavailable"`, akun Slack + telah dikonfigurasi tetapi runtime saat ini tidak dapat menyelesaikan nilai + yang didukung SecretRef. + + + + + Validasi: + + - signing secret + - path webhook + - Slack Request URL (Events + Interactivity + Slash Commands) + - `webhookPath` unik per akun HTTP + + Jika `signingSecretStatus: "configured_unavailable"` muncul di snapshot akun, + akun HTTP telah dikonfigurasi tetapi runtime saat ini tidak dapat + menyelesaikan signing secret yang didukung SecretRef. + + + + + Verifikasi apakah yang Anda maksud adalah: + + - mode perintah native (`channels.slack.commands.native: true`) dengan slash command yang sesuai terdaftar di Slack + - atau mode single slash command (`channels.slack.slashCommand.enabled: true`) + + Periksa juga `commands.useAccessGroups` dan allowlist channel/pengguna. + + + + +## Terkait + +- [Pairing](/channels/pairing) +- [Grup](/channels/groups) +- [Keamanan](/gateway/security) +- [Channel routing](/channels/channel-routing) +- [Pemecahan masalah](/channels/troubleshooting) +- [Konfigurasi](/gateway/configuration) +- [Slash commands](/tools/slash-commands) diff --git a/docs/id/channels/synology-chat.md b/docs/id/channels/synology-chat.md new file mode 100644 index 000000000..e2ce1c3fa --- /dev/null +++ b/docs/id/channels/synology-chat.md @@ -0,0 +1,192 @@ +--- +read_when: + - Menyiapkan Synology Chat dengan OpenClaw + - Men-debug perutean webhook Synology Chat +summary: Penyiapan webhook Synology Chat dan konfigurasi OpenClaw +title: Synology Chat +x-i18n: + generated_at: "2026-04-05T13:44:08Z" + model: gpt-5.4 + provider: openai + source_hash: ddb25fc6b53f896f15f43b4936d69ea071a29a91838a5b662819377271e89d81 + source_path: channels/synology-chat.md + workflow: 15 +--- + +# Synology Chat + +Status: channel pesan langsung plugin bawaan yang menggunakan webhook Synology Chat. +Plugin ini menerima pesan masuk dari webhook keluar Synology Chat dan mengirim balasan +melalui webhook masuk Synology Chat. + +## Plugin bawaan + +Synology Chat tersedia sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build +paket normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Synology Chat, +instal secara manual: + +Instal dari checkout lokal: + +```bash +openclaw plugins install ./path/to/local/synology-chat-plugin +``` + +Detail: [Plugins](/tools/plugin) + +## Penyiapan cepat + +1. Pastikan plugin Synology Chat tersedia. + - Rilis OpenClaw paket saat ini sudah menyertakan plugin ini. + - Instalasi lama/kustom dapat menambahkannya secara manual dari checkout sumber dengan perintah di atas. + - `openclaw onboard` sekarang menampilkan Synology Chat dalam daftar penyiapan channel yang sama seperti `openclaw channels add`. + - Penyiapan non-interaktif: `openclaw channels add --channel synology-chat --token --url ` +2. Di integrasi Synology Chat: + - Buat webhook masuk dan salin URL-nya. + - Buat webhook keluar dengan token rahasia Anda. +3. Arahkan URL webhook keluar ke gateway OpenClaw Anda: + - `https://gateway-host/webhook/synology` secara default. + - Atau `channels.synology-chat.webhookPath` kustom Anda. +4. Selesaikan penyiapan di OpenClaw. + - Terpandu: `openclaw onboard` + - Langsung: `openclaw channels add --channel synology-chat --token --url ` +5. Mulai ulang gateway dan kirim DM ke bot Synology Chat. + +Detail autentikasi webhook: + +- OpenClaw menerima token webhook keluar dari `body.token`, lalu + `?token=...`, lalu header. +- Bentuk header yang diterima: + - `x-synology-token` + - `x-webhook-token` + - `x-openclaw-token` + - `Authorization: Bearer ` +- Token yang kosong atau tidak ada akan gagal secara fail-closed. + +Konfigurasi minimal: + +```json5 +{ + channels: { + "synology-chat": { + enabled: true, + token: "synology-outgoing-token", + incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...", + webhookPath: "/webhook/synology", + dmPolicy: "allowlist", + allowedUserIds: ["123456"], + rateLimitPerMinute: 30, + allowInsecureSsl: false, + }, + }, +} +``` + +## Variabel lingkungan + +Untuk akun default, Anda dapat menggunakan variabel lingkungan: + +- `SYNOLOGY_CHAT_TOKEN` +- `SYNOLOGY_CHAT_INCOMING_URL` +- `SYNOLOGY_NAS_HOST` +- `SYNOLOGY_ALLOWED_USER_IDS` (dipisahkan koma) +- `SYNOLOGY_RATE_LIMIT` +- `OPENCLAW_BOT_NAME` + +Nilai konfigurasi menimpa variabel lingkungan. + +## Kebijakan DM dan kontrol akses + +- `dmPolicy: "allowlist"` adalah default yang direkomendasikan. +- `allowedUserIds` menerima daftar (atau string yang dipisahkan koma) ID pengguna Synology. +- Dalam mode `allowlist`, daftar `allowedUserIds` yang kosong dianggap sebagai salah konfigurasi dan rute webhook tidak akan dimulai (gunakan `dmPolicy: "open"` untuk mengizinkan semua). +- `dmPolicy: "open"` mengizinkan pengirim mana pun. +- `dmPolicy: "disabled"` memblokir DM. +- Binding penerima balasan tetap menggunakan `user_id` numerik yang stabil secara default. `channels.synology-chat.dangerouslyAllowNameMatching: true` adalah mode kompatibilitas darurat yang mengaktifkan kembali pencocokan username/nickname yang dapat berubah untuk pengiriman balasan. +- Persetujuan pairing berfungsi dengan: + - `openclaw pairing list synology-chat` + - `openclaw pairing approve synology-chat ` + +## Pengiriman keluar + +Gunakan ID pengguna Synology Chat numerik sebagai target. + +Contoh: + +```bash +openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw" +openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again" +``` + +Pengiriman media didukung melalui pengiriman file berbasis URL. + +## Multi-akun + +Beberapa akun Synology Chat didukung di bawah `channels.synology-chat.accounts`. +Setiap akun dapat menimpa token, URL masuk, path webhook, kebijakan DM, dan batasan. +Sesi pesan langsung diisolasi per akun dan pengguna, sehingga `user_id` numerik yang sama +pada dua akun Synology yang berbeda tidak berbagi status transkrip. +Berikan setiap akun aktif `webhookPath` yang berbeda. OpenClaw sekarang menolak path persis yang duplikat +dan menolak memulai akun bernama yang hanya mewarisi satu path webhook bersama dalam penyiapan multi-akun. +Jika Anda sengaja memerlukan pewarisan lama untuk akun bernama, atur +`dangerouslyAllowInheritedWebhookPath: true` pada akun tersebut atau di `channels.synology-chat`, +tetapi path persis yang duplikat tetap ditolak secara fail-closed. Lebih baik gunakan path eksplisit per akun. + +```json5 +{ + channels: { + "synology-chat": { + enabled: true, + accounts: { + default: { + token: "token-a", + incomingUrl: "https://nas-a.example.com/...token=...", + }, + alerts: { + token: "token-b", + incomingUrl: "https://nas-b.example.com/...token=...", + webhookPath: "/webhook/synology-alerts", + dmPolicy: "allowlist", + allowedUserIds: ["987654"], + }, + }, + }, + }, +} +``` + +## Catatan keamanan + +- Jaga kerahasiaan `token` dan rotasi jika bocor. +- Pertahankan `allowInsecureSsl: false` kecuali Anda secara eksplisit memercayai sertifikat NAS lokal self-signed. +- Permintaan webhook masuk diverifikasi token dan dibatasi lajunya per pengirim. +- Pemeriksaan token tidak valid menggunakan perbandingan rahasia waktu konstan dan fail-closed. +- Gunakan `dmPolicy: "allowlist"` untuk produksi. +- Biarkan `dangerouslyAllowNameMatching` nonaktif kecuali Anda benar-benar memerlukan pengiriman balasan berbasis username lama. +- Biarkan `dangerouslyAllowInheritedWebhookPath` nonaktif kecuali Anda secara eksplisit menerima risiko perutean path bersama dalam penyiapan multi-akun. + +## Pemecahan masalah + +- `Missing required fields (token, user_id, text)`: + - payload webhook keluar tidak memiliki salah satu field wajib + - jika Synology mengirim token di header, pastikan gateway/proxy mempertahankan header tersebut +- `Invalid token`: + - rahasia webhook keluar tidak cocok dengan `channels.synology-chat.token` + - permintaan mengenai akun/path webhook yang salah + - reverse proxy menghapus header token sebelum permintaan mencapai OpenClaw +- `Rate limit exceeded`: + - terlalu banyak percobaan token tidak valid dari sumber yang sama dapat mengunci sementara sumber tersebut + - pengirim yang terautentikasi juga memiliki batas laju pesan terpisah per pengguna +- `Allowlist is empty. Configure allowedUserIds or use dmPolicy=open.`: + - `dmPolicy="allowlist"` aktif tetapi tidak ada pengguna yang dikonfigurasi +- `User not authorized`: + - `user_id` numerik pengirim tidak ada dalam `allowedUserIds` + +## Terkait + +- [Ikhtisar Channel](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Grup](/channels/groups) — perilaku chat grup dan penyaringan mention +- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/telegram.md b/docs/id/channels/telegram.md new file mode 100644 index 000000000..3732b7a29 --- /dev/null +++ b/docs/id/channels/telegram.md @@ -0,0 +1,1075 @@ +--- +read_when: + - Sedang mengerjakan fitur Telegram atau webhook +summary: Status dukungan bot Telegram, kemampuan, dan konfigurasi +title: Telegram +x-i18n: + generated_at: "2026-04-05T13:52:08Z" + model: gpt-5.4 + provider: openai + source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e + source_path: channels/telegram.md + workflow: 15 +--- + +# Telegram (Bot API) + +Status: siap produksi untuk DM bot + grup melalui grammY. Long polling adalah mode default; mode webhook bersifat opsional. + + + + Kebijakan DM default untuk Telegram adalah pairing. + + + Diagnostik lintas-channel dan panduan perbaikan. + + + Pola dan contoh konfigurasi channel lengkap. + + + +## Penyiapan cepat + + + + Buka Telegram dan chat dengan **@BotFather** (pastikan handle-nya persis `@BotFather`). + + Jalankan `/newbot`, ikuti petunjuknya, lalu simpan token-nya. + + + + + +```json5 +{ + channels: { + telegram: { + enabled: true, + botToken: "123:abc", + dmPolicy: "pairing", + groups: { "*": { requireMention: true } }, + }, + }, +} +``` + + Fallback env: `TELEGRAM_BOT_TOKEN=...` (hanya akun default). + Telegram **tidak** menggunakan `openclaw channels login telegram`; konfigurasikan token di config/env, lalu mulai gateway. + + + + + +```bash +openclaw gateway +openclaw pairing list telegram +openclaw pairing approve telegram +``` + + Kode pairing kedaluwarsa setelah 1 jam. + + + + + Tambahkan bot ke grup Anda, lalu atur `channels.telegram.groups` dan `groupPolicy` agar sesuai dengan model akses Anda. + + + + +Urutan resolusi token memperhitungkan akun. Dalam praktiknya, nilai config lebih diutamakan daripada fallback env, dan `TELEGRAM_BOT_TOKEN` hanya berlaku untuk akun default. + + +## Pengaturan di sisi Telegram + + + + Bot Telegram secara default menggunakan **Privacy Mode**, yang membatasi pesan grup yang mereka terima. + + Jika bot harus dapat melihat semua pesan grup, lakukan salah satu dari berikut ini: + + - nonaktifkan privacy mode melalui `/setprivacy`, atau + - jadikan bot sebagai admin grup. + + Saat mengubah privacy mode, keluarkan lalu tambahkan kembali bot di setiap grup agar Telegram menerapkan perubahan tersebut. + + + + + Status admin dikendalikan dalam pengaturan grup Telegram. + + Bot admin menerima semua pesan grup, yang berguna untuk perilaku grup yang selalu aktif. + + + + + + - `/setjoingroups` untuk mengizinkan/menolak penambahan ke grup + - `/setprivacy` untuk perilaku visibilitas grup + + + + +## Kontrol akses dan aktivasi + + + + `channels.telegram.dmPolicy` mengontrol akses pesan langsung: + + - `pairing` (default) + - `allowlist` (memerlukan setidaknya satu ID pengirim di `allowFrom`) + - `open` (mengharuskan `allowFrom` menyertakan `"*"`) + - `disabled` + + `channels.telegram.allowFrom` menerima ID pengguna Telegram numerik. Prefiks `telegram:` / `tg:` diterima dan dinormalisasi. + `dmPolicy: "allowlist"` dengan `allowFrom` kosong memblokir semua DM dan ditolak oleh validasi config. + Onboarding menerima input `@username` dan meresolusikannya ke ID numerik. + Jika Anda melakukan upgrade dan config Anda berisi entri allowlist `@username`, jalankan `openclaw doctor --fix` untuk meresolusikannya (best-effort; memerlukan token bot Telegram). + Jika sebelumnya Anda mengandalkan file allowlist pairing-store, `openclaw doctor --fix` dapat memulihkan entri ke `channels.telegram.allowFrom` dalam alur allowlist (misalnya saat `dmPolicy: "allowlist"` belum memiliki ID eksplisit). + + Untuk bot dengan satu pemilik, gunakan `dmPolicy: "allowlist"` dengan ID `allowFrom` numerik yang eksplisit agar kebijakan akses tetap tahan lama di config (alih-alih bergantung pada persetujuan pairing sebelumnya). + + Kebingungan umum: persetujuan pairing DM tidak berarti "pengirim ini diotorisasi di mana saja". + Pairing hanya memberikan akses DM. Otorisasi pengirim grup tetap berasal dari allowlist config yang eksplisit. + Jika Anda ingin "saya diotorisasi sekali lalu baik DM maupun perintah grup berfungsi", masukkan ID pengguna Telegram numerik Anda ke `channels.telegram.allowFrom`. + + ### Menemukan ID pengguna Telegram Anda + + Lebih aman (tanpa bot pihak ketiga): + + 1. Kirim DM ke bot Anda. + 2. Jalankan `openclaw logs --follow`. + 3. Baca `from.id`. + + Metode resmi Bot API: + +```bash +curl "https://api.telegram.org/bot/getUpdates" +``` + + Metode pihak ketiga (kurang privat): `@userinfobot` atau `@getidsbot`. + + + + + Dua kontrol diterapkan bersamaan: + + 1. **Grup mana yang diizinkan** (`channels.telegram.groups`) + - tanpa config `groups`: + - dengan `groupPolicy: "open"`: grup mana pun dapat lolos pemeriksaan ID grup + - dengan `groupPolicy: "allowlist"` (default): grup diblokir sampai Anda menambahkan entri `groups` (atau `"*"`) + - `groups` dikonfigurasi: bertindak sebagai allowlist (ID eksplisit atau `"*"`) + + 2. **Pengirim mana yang diizinkan di grup** (`channels.telegram.groupPolicy`) + - `open` + - `allowlist` (default) + - `disabled` + + `groupAllowFrom` digunakan untuk pemfilteran pengirim grup. Jika tidak diatur, Telegram akan fallback ke `allowFrom`. + Entri `groupAllowFrom` harus berupa ID pengguna Telegram numerik (prefiks `telegram:` / `tg:` dinormalisasi). + Jangan masukkan ID chat grup atau supergroup Telegram ke dalam `groupAllowFrom`. ID chat negatif harus ditempatkan di bawah `channels.telegram.groups`. + Entri non-numerik diabaikan untuk otorisasi pengirim. + Batas keamanan (`2026.2.25+`): auth pengirim grup **tidak** mewarisi persetujuan pairing-store DM. + Pairing tetap hanya untuk DM. Untuk grup, atur `groupAllowFrom` atau `allowFrom` per-grup/per-topik. + Jika `groupAllowFrom` tidak diatur, Telegram fallback ke config `allowFrom`, bukan pairing store. + Pola praktis untuk bot satu pemilik: atur ID pengguna Anda di `channels.telegram.allowFrom`, biarkan `groupAllowFrom` tidak diatur, dan izinkan grup target di bawah `channels.telegram.groups`. + Catatan runtime: jika `channels.telegram` sama sekali tidak ada, default runtime adalah fail-closed `groupPolicy="allowlist"` kecuali `channels.defaults.groupPolicy` diatur secara eksplisit. + + Contoh: izinkan anggota mana pun di satu grup tertentu: + +```json5 +{ + channels: { + telegram: { + groups: { + "-1001234567890": { + groupPolicy: "open", + requireMention: false, + }, + }, + }, + }, +} +``` + + Contoh: izinkan hanya pengguna tertentu di dalam satu grup tertentu: + +```json5 +{ + channels: { + telegram: { + groups: { + "-1001234567890": { + requireMention: true, + allowFrom: ["8734062810", "745123456"], + }, + }, + }, + }, +} +``` + + + Kesalahan umum: `groupAllowFrom` bukan allowlist grup Telegram. + + - Tempatkan ID chat grup atau supergroup Telegram negatif seperti `-1001234567890` di bawah `channels.telegram.groups`. + - Tempatkan ID pengguna Telegram seperti `8734062810` di bawah `groupAllowFrom` saat Anda ingin membatasi orang mana di dalam grup yang diizinkan dapat memicu bot. + - Gunakan `groupAllowFrom: ["*"]` hanya ketika Anda ingin anggota mana pun dari grup yang diizinkan dapat berbicara dengan bot. + + + + + + Balasan grup secara default memerlukan mention. + + Mention dapat berasal dari: + + - mention native `@botusername`, atau + - pola mention di: + - `agents.list[].groupChat.mentionPatterns` + - `messages.groupChat.mentionPatterns` + + Toggle perintah tingkat sesi: + + - `/activation always` + - `/activation mention` + + Ini hanya memperbarui state sesi. Gunakan config untuk persistensi. + + Contoh config persisten: + +```json5 +{ + channels: { + telegram: { + groups: { + "*": { requireMention: false }, + }, + }, + }, +} +``` + + Mendapatkan ID chat grup: + + - teruskan pesan grup ke `@userinfobot` / `@getidsbot` + - atau baca `chat.id` dari `openclaw logs --follow` + - atau periksa `getUpdates` Bot API + + + + +## Perilaku runtime + +- Telegram dimiliki oleh proses gateway. +- Routing bersifat deterministik: balasan inbound Telegram kembali ke Telegram (model tidak memilih channel). +- Pesan inbound dinormalisasi ke envelope channel bersama dengan metadata balasan dan placeholder media. +- Sesi grup diisolasi berdasarkan ID grup. Topik forum menambahkan `:topic:` agar topik tetap terisolasi. +- Pesan DM dapat membawa `message_thread_id`; OpenClaw merutekannya dengan kunci sesi yang sadar thread dan mempertahankan ID thread untuk balasan. +- Long polling menggunakan grammY runner dengan pengurutan per-chat/per-thread. Sink runner secara keseluruhan menggunakan konkurensi `agents.defaults.maxConcurrent`. +- Telegram Bot API tidak memiliki dukungan tanda terima baca (`sendReadReceipts` tidak berlaku). + +## Referensi fitur + + + + OpenClaw dapat melakukan streaming balasan parsial secara real time: + + - chat langsung: pesan pratinjau + `editMessageText` + - grup/topik: pesan pratinjau + `editMessageText` + + Syarat: + + - `channels.telegram.streaming` adalah `off | partial | block | progress` (default: `partial`) + - `progress` dipetakan ke `partial` di Telegram (kompatibel dengan penamaan lintas-channel) + - nilai lama `channels.telegram.streamMode` dan nilai boolean `streaming` dipetakan otomatis + + Untuk balasan teks saja: + + - DM: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan edit final di tempatnya (tanpa pesan kedua) + - grup/topik: OpenClaw mempertahankan pesan pratinjau yang sama dan melakukan edit final di tempatnya (tanpa pesan kedua) + + Untuk balasan kompleks (misalnya payload media), OpenClaw fallback ke pengiriman final normal lalu membersihkan pesan pratinjau. + + Preview streaming terpisah dari block streaming. Saat block streaming diaktifkan secara eksplisit untuk Telegram, OpenClaw melewati preview stream untuk menghindari double-streaming. + + Jika transport draf native tidak tersedia/ditolak, OpenClaw otomatis fallback ke `sendMessage` + `editMessageText`. + + Streaming reasoning khusus Telegram: + + - `/reasoning stream` mengirim reasoning ke pratinjau live saat sedang menghasilkan + - jawaban final dikirim tanpa teks reasoning + + + + + Teks outbound menggunakan Telegram `parse_mode: "HTML"`. + + - Teks bergaya Markdown dirender menjadi HTML aman untuk Telegram. + - HTML model mentah di-escape untuk mengurangi kegagalan parse Telegram. + - Jika Telegram menolak HTML yang telah diparse, OpenClaw mencoba ulang sebagai teks biasa. + + Pratinjau tautan aktif secara default dan dapat dinonaktifkan dengan `channels.telegram.linkPreview: false`. + + + + + Registrasi menu perintah Telegram ditangani saat startup dengan `setMyCommands`. + + Default perintah native: + + - `commands.native: "auto"` mengaktifkan perintah native untuk Telegram + + Tambahkan entri menu perintah kustom: + +```json5 +{ + channels: { + telegram: { + customCommands: [ + { command: "backup", description: "Git backup" }, + { command: "generate", description: "Create an image" }, + ], + }, + }, +} +``` + + Aturan: + + - nama dinormalisasi (hapus `/` di depan, huruf kecil) + - pola valid: `a-z`, `0-9`, `_`, panjang `1..32` + - perintah kustom tidak dapat menimpa perintah native + - konflik/duplikasi dilewati dan dicatat di log + + Catatan: + + - perintah kustom hanya entri menu; tidak otomatis mengimplementasikan perilaku + - perintah plugin/skill tetap dapat berfungsi saat diketik meskipun tidak ditampilkan di menu Telegram + + Jika perintah native dinonaktifkan, built-in akan dihapus. Perintah kustom/plugin mungkin tetap terdaftar jika dikonfigurasi. + + Kegagalan penyiapan umum: + + - `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu Telegram masih meluap setelah dipangkas; kurangi perintah plugin/skill/kustom atau nonaktifkan `channels.telegram.commands.native`. + - `setMyCommands failed` dengan kesalahan jaringan/fetch biasanya berarti DNS/HTTPS outbound ke `api.telegram.org` diblokir. + + ### Perintah pairing perangkat (plugin `device-pair`) + + Saat plugin `device-pair` terpasang: + + 1. `/pair` menghasilkan kode penyiapan + 2. tempelkan kode di aplikasi iOS + 3. `/pair pending` mencantumkan permintaan yang tertunda (termasuk role/scopes) + 4. setujui permintaannya: + - `/pair approve ` untuk persetujuan eksplisit + - `/pair approve` saat hanya ada satu permintaan tertunda + - `/pair approve latest` untuk yang paling baru + + Kode penyiapan membawa token bootstrap berumur pendek. Built-in bootstrap handoff menjaga token node utama pada `scopes: []`; token operator apa pun yang diserahkan tetap dibatasi pada `operator.approvals`, `operator.read`, `operator.talk.secrets`, dan `operator.write`. Pemeriksaan scope bootstrap berawalan role, sehingga allowlist operator tersebut hanya memenuhi permintaan operator; role non-operator tetap memerlukan scope di bawah prefiks role mereka sendiri. + + Jika perangkat mencoba lagi dengan detail auth yang berubah (misalnya role/scopes/public key), permintaan tertunda sebelumnya akan digantikan dan permintaan baru menggunakan `requestId` yang berbeda. Jalankan kembali `/pair pending` sebelum menyetujui. + + Detail selengkapnya: [Pairing](/id/channels/pairing#pair-via-telegram-recommended-for-ios). + + + + + Konfigurasikan cakupan keyboard inline: + +```json5 +{ + channels: { + telegram: { + capabilities: { + inlineButtons: "allowlist", + }, + }, + }, +} +``` + + Override per akun: + +```json5 +{ + channels: { + telegram: { + accounts: { + main: { + capabilities: { + inlineButtons: "allowlist", + }, + }, + }, + }, + }, +} +``` + + Cakupan: + + - `off` + - `dm` + - `group` + - `all` + - `allowlist` (default) + + `capabilities: ["inlineButtons"]` lama dipetakan ke `inlineButtons: "all"`. + + Contoh aksi pesan: + +```json5 +{ + action: "send", + channel: "telegram", + to: "123456789", + message: "Choose an option:", + buttons: [ + [ + { text: "Yes", callback_data: "yes" }, + { text: "No", callback_data: "no" }, + ], + [{ text: "Cancel", callback_data: "cancel" }], + ], +} +``` + + Klik callback diteruskan ke agent sebagai teks: + `callback_data: ` + + + + + Aksi tool Telegram meliputi: + + - `sendMessage` (`to`, `content`, opsional `mediaUrl`, `replyToMessageId`, `messageThreadId`) + - `react` (`chatId`, `messageId`, `emoji`) + - `deleteMessage` (`chatId`, `messageId`) + - `editMessage` (`chatId`, `messageId`, `content`) + - `createForumTopic` (`chatId`, `name`, opsional `iconColor`, `iconCustomEmojiId`) + + Aksi pesan channel menyediakan alias ergonomis (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + + Kontrol gating: + + - `channels.telegram.actions.sendMessage` + - `channels.telegram.actions.deleteMessage` + - `channels.telegram.actions.reactions` + - `channels.telegram.actions.sticker` (default: dinonaktifkan) + + Catatan: `edit` dan `topic-create` saat ini diaktifkan secara default dan tidak memiliki toggle `channels.telegram.actions.*` terpisah. + Pengiriman runtime menggunakan snapshot config/secret yang aktif (startup/reload), sehingga jalur aksi tidak melakukan resolusi ulang SecretRef ad-hoc untuk setiap pengiriman. + + Semantik penghapusan reaction: [/tools/reactions](/tools/reactions) + + + + + Telegram mendukung tag reply threading eksplisit dalam output yang dihasilkan: + + - `[[reply_to_current]]` membalas pesan yang memicu + - `[[reply_to:]]` membalas ID pesan Telegram tertentu + + `channels.telegram.replyToMode` mengontrol penanganannya: + + - `off` (default) + - `first` + - `all` + + Catatan: `off` menonaktifkan reply threading implisit. Tag `[[reply_to_*]]` eksplisit tetap dihormati. + + + + + Supergroup forum: + + - kunci sesi topik menambahkan `:topic:` + - balasan dan typing menargetkan thread topik + - jalur config topik: + `channels.telegram.groups..topics.` + + Kasus khusus topik umum (`threadId=1`): + + - pengiriman pesan menghilangkan `message_thread_id` (Telegram menolak `sendMessage(...thread_id=1)`) + - aksi mengetik tetap menyertakan `message_thread_id` + + Pewarisan topik: entri topik mewarisi pengaturan grup kecuali dioverride (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` hanya untuk topik dan tidak mewarisi dari default grup. + + **Routing agent per-topik**: Setiap topik dapat dirutekan ke agent yang berbeda dengan menetapkan `agentId` di config topik. Ini memberi setiap topik workspace, memori, dan sesi terisolasi sendiri. Contoh: + + ```json5 + { + channels: { + telegram: { + groups: { + "-1001234567890": { + topics: { + "1": { agentId: "main" }, // Topik umum → agent utama + "3": { agentId: "zu" }, // Topik dev → agent zu + "5": { agentId: "coder" } // Review kode → agent coder + } + } + } + } + } + } + ``` + + Setiap topik kemudian memiliki kunci sesi sendiri: `agent:zu:telegram:group:-1001234567890:topic:3` + + **Binding topik ACP persisten**: Topik forum dapat menyematkan sesi harness ACP melalui binding ACP bertipe tingkat atas: + + - `bindings[]` dengan `type: "acp"` dan `match.channel: "telegram"` + + Contoh: + + ```json5 + { + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { + agent: "codex", + backend: "acpx", + mode: "persistent", + cwd: "/workspace/openclaw", + }, + }, + }, + ], + }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "telegram", + accountId: "default", + peer: { kind: "group", id: "-1001234567890:topic:42" }, + }, + }, + ], + channels: { + telegram: { + groups: { + "-1001234567890": { + topics: { + "42": { + requireMention: false, + }, + }, + }, + }, + }, + }, + } + ``` + + Ini saat ini dibatasi untuk topik forum di grup dan supergroup. + + **Spawn ACP terikat thread dari chat**: + + - `/acp spawn --thread here|auto` dapat membinding topik Telegram saat ini ke sesi ACP baru. + - Pesan topik lanjutan dirutekan langsung ke sesi ACP yang terikat (tidak perlu `/acp steer`). + - OpenClaw menyematkan pesan konfirmasi spawn di dalam topik setelah binding berhasil. + - Memerlukan `channels.telegram.threadBindings.spawnAcpSessions=true`. + + Konteks template meliputi: + + - `MessageThreadId` + - `IsForum` + + Perilaku thread DM: + + - chat privat dengan `message_thread_id` tetap menggunakan routing DM tetapi memakai kunci sesi/target balasan yang sadar thread. + + + + + ### Pesan audio + + Telegram membedakan voice note dan file audio. + + - default: perilaku file audio + - tag `[[audio_as_voice]]` di balasan agent untuk memaksa pengiriman sebagai voice note + + Contoh aksi pesan: + +```json5 +{ + action: "send", + channel: "telegram", + to: "123456789", + media: "https://example.com/voice.ogg", + asVoice: true, +} +``` + + ### Pesan video + + Telegram membedakan file video dan video note. + + Contoh aksi pesan: + +```json5 +{ + action: "send", + channel: "telegram", + to: "123456789", + media: "https://example.com/video.mp4", + asVideoNote: true, +} +``` + + Video note tidak mendukung caption; teks pesan yang diberikan dikirim secara terpisah. + + ### Stiker + + Penanganan stiker inbound: + + - WEBP statis: diunduh dan diproses (placeholder ``) + - TGS animasi: dilewati + - WEBM video: dilewati + + Field konteks stiker: + + - `Sticker.emoji` + - `Sticker.setName` + - `Sticker.fileId` + - `Sticker.fileUniqueId` + - `Sticker.cachedDescription` + + File cache stiker: + + - `~/.openclaw/telegram/sticker-cache.json` + + Stiker dideskripsikan sekali (jika memungkinkan) dan di-cache untuk mengurangi panggilan vision berulang. + + Aktifkan aksi stiker: + +```json5 +{ + channels: { + telegram: { + actions: { + sticker: true, + }, + }, + }, +} +``` + + Aksi kirim stiker: + +```json5 +{ + action: "sticker", + channel: "telegram", + to: "123456789", + fileId: "CAACAgIAAxkBAAI...", +} +``` + + Cari stiker yang di-cache: + +```json5 +{ + action: "sticker-search", + channel: "telegram", + query: "cat waving", + limit: 5, +} +``` + + + + + Reaction Telegram datang sebagai update `message_reaction` (terpisah dari payload pesan). + + Saat diaktifkan, OpenClaw mengantrikan event sistem seperti: + + - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` + + Config: + + - `channels.telegram.reactionNotifications`: `off | own | all` (default: `own`) + - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (default: `minimal`) + + Catatan: + + - `own` berarti hanya reaction pengguna terhadap pesan yang dikirim bot (best-effort melalui cache pesan terkirim). + - Event reaction tetap mematuhi kontrol akses Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); pengirim yang tidak diotorisasi dibuang. + - Telegram tidak menyediakan ID thread dalam update reaction. + - grup non-forum dirutekan ke sesi chat grup + - grup forum dirutekan ke sesi topik umum grup (`:topic:1`), bukan ke topik asal yang tepat + + `allowed_updates` untuk polling/webhook otomatis menyertakan `message_reaction`. + + + + + `ackReaction` mengirim emoji pengakuan saat OpenClaw sedang memproses pesan inbound. + + Urutan resolusi: + + - `channels.telegram.accounts..ackReaction` + - `channels.telegram.ackReaction` + - `messages.ackReaction` + - fallback emoji identitas agent (`agents.list[].identity.emoji`, jika tidak "👀") + + Catatan: + + - Telegram mengharapkan emoji unicode (misalnya "👀"). + - Gunakan `""` untuk menonaktifkan reaction bagi suatu channel atau akun. + + + + + Penulisan config channel diaktifkan secara default (`configWrites !== false`). + + Penulisan yang dipicu Telegram meliputi: + + - event migrasi grup (`migrate_to_chat_id`) untuk memperbarui `channels.telegram.groups` + - `/config set` dan `/config unset` (memerlukan enablement perintah) + + Nonaktifkan: + +```json5 +{ + channels: { + telegram: { + configWrites: false, + }, + }, +} +``` + + + + + Default: long polling. + + Mode webhook: + + - atur `channels.telegram.webhookUrl` + - atur `channels.telegram.webhookSecret` (wajib saat webhook URL diatur) + - opsional `channels.telegram.webhookPath` (default `/telegram-webhook`) + - opsional `channels.telegram.webhookHost` (default `127.0.0.1`) + - opsional `channels.telegram.webhookPort` (default `8787`) + + Listener lokal default untuk mode webhook bind ke `127.0.0.1:8787`. + + Jika endpoint publik Anda berbeda, tempatkan reverse proxy di depan dan arahkan `webhookUrl` ke URL publik. + Atur `webhookHost` (misalnya `0.0.0.0`) saat Anda memang membutuhkan ingress eksternal. + + + + + - default `channels.telegram.textChunkLimit` adalah 4000. + - `channels.telegram.chunkMode="newline"` lebih memilih batas paragraf (baris kosong) sebelum pemisahan berdasarkan panjang. + - `channels.telegram.mediaMaxMb` (default 100) membatasi ukuran media Telegram inbound dan outbound. + - `channels.telegram.timeoutSeconds` menimpa timeout klien API Telegram (jika tidak diatur, default grammY berlaku). + - riwayat konteks grup menggunakan `channels.telegram.historyLimit` atau `messages.groupChat.historyLimit` (default 50); `0` menonaktifkan. + - konteks tambahan reply/quote/forward saat ini diteruskan sebagaimana diterima. + - allowlist Telegram terutama membatasi siapa yang dapat memicu agent, bukan batas penyuntingan penuh untuk konteks tambahan. + - kontrol riwayat DM: + - `channels.telegram.dmHistoryLimit` + - `channels.telegram.dms[""].historyLimit` + - config `channels.telegram.retry` berlaku untuk helper pengiriman Telegram (CLI/tools/actions) pada kesalahan API outbound yang dapat dipulihkan. + + Target pengiriman CLI dapat berupa ID chat numerik atau username: + +```bash +openclaw message send --channel telegram --target 123456789 --message "hi" +openclaw message send --channel telegram --target @name --message "hi" +``` + + Poll Telegram menggunakan `openclaw message poll` dan mendukung topik forum: + +```bash +openclaw message poll --channel telegram --target 123456789 \ + --poll-question "Ship it?" --poll-option "Yes" --poll-option "No" +openclaw message poll --channel telegram --target -1001234567890:topic:42 \ + --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \ + --poll-duration-seconds 300 --poll-public +``` + + Flag poll khusus Telegram: + + - `--poll-duration-seconds` (5-600) + - `--poll-anonymous` + - `--poll-public` + - `--thread-id` untuk topik forum (atau gunakan target `:topic:`) + + Pengiriman Telegram juga mendukung: + + - `--buttons` untuk keyboard inline saat `channels.telegram.capabilities.inlineButtons` mengizinkannya + - `--force-document` untuk mengirim gambar dan GIF outbound sebagai dokumen alih-alih unggahan foto terkompresi atau media animasi + + Gating aksi: + + - `channels.telegram.actions.sendMessage=false` menonaktifkan pesan Telegram outbound, termasuk poll + - `channels.telegram.actions.poll=false` menonaktifkan pembuatan poll Telegram sambil tetap membiarkan pengiriman reguler aktif + + + + + Telegram mendukung persetujuan exec di DM approver dan secara opsional dapat memposting prompt persetujuan di chat atau topik asal. + + Jalur config: + + - `channels.telegram.execApprovals.enabled` + - `channels.telegram.execApprovals.approvers` (opsional; fallback ke ID pemilik numerik yang diinferensikan dari `allowFrom` dan `defaultTo` langsung jika memungkinkan) + - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, default: `dm`) + - `agentFilter`, `sessionFilter` + + Approver harus berupa ID pengguna Telegram numerik. Telegram otomatis mengaktifkan persetujuan exec native ketika `enabled` tidak diatur atau `"auto"` dan setidaknya satu approver dapat diresolusikan, baik dari `execApprovals.approvers` maupun dari config pemilik numerik akun (`allowFrom` dan `defaultTo` direct-message). Atur `enabled: false` untuk menonaktifkan Telegram sebagai klien persetujuan native secara eksplisit. Jika tidak, permintaan persetujuan akan fallback ke rute persetujuan terkonfigurasi lainnya atau kebijakan fallback persetujuan exec. + + Telegram juga merender tombol persetujuan bersama yang digunakan oleh channel chat lain. Adapter Telegram native terutama menambahkan routing DM approver, fanout channel/topik, dan petunjuk mengetik sebelum pengiriman. + Saat tombol tersebut ada, itulah UX persetujuan utama; OpenClaw + seharusnya hanya menyertakan perintah `/approve` manual ketika hasil tool menyatakan + persetujuan chat tidak tersedia atau persetujuan manual adalah satu-satunya jalur. + + Aturan pengiriman: + + - `target: "dm"` hanya mengirim prompt persetujuan ke DM approver yang teresolusikan + - `target: "channel"` mengirim prompt kembali ke chat/topik Telegram asal + - `target: "both"` mengirim ke DM approver dan chat/topik asal + + Hanya approver yang teresolusikan yang dapat menyetujui atau menolak. Non-approver tidak dapat menggunakan `/approve` dan tidak dapat menggunakan tombol persetujuan Telegram. + + Perilaku resolusi persetujuan: + + - ID berprefiks `plugin:` selalu diresolusikan melalui persetujuan plugin. + - ID persetujuan lainnya mencoba `exec.approval.resolve` terlebih dahulu. + - Jika Telegram juga diotorisasi untuk persetujuan plugin dan gateway mengatakan + persetujuan exec tidak dikenal/kedaluwarsa, Telegram mencoba ulang satu kali melalui + `plugin.approval.resolve`. + - Penolakan/kesalahan persetujuan exec yang nyata tidak diam-diam diteruskan ke resolusi + persetujuan plugin. + + Pengiriman channel menampilkan teks perintah di chat, jadi aktifkan `channel` atau `both` hanya di grup/topik tepercaya. Saat prompt mendarat di topik forum, OpenClaw mempertahankan topik tersebut baik untuk prompt persetujuan maupun tindak lanjut pasca-persetujuan. Persetujuan exec kedaluwarsa setelah 30 menit secara default. + + Tombol persetujuan inline juga bergantung pada `channels.telegram.capabilities.inlineButtons` yang mengizinkan permukaan target (`dm`, `group`, atau `all`). + + Dokumentasi terkait: [Persetujuan exec](/tools/exec-approvals) + + + + +## Kontrol balasan error + +Saat agent mengalami error pengiriman atau provider, Telegram dapat membalas dengan teks error tersebut atau menekannya. Dua kunci config mengontrol perilaku ini: + +| Key | Values | Default | Description | +| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` mengirim pesan error yang ramah ke chat. `silent` sepenuhnya menekan balasan error. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Waktu minimum antar balasan error ke chat yang sama. Mencegah spam error selama gangguan. | + +Override per-akun, per-grup, dan per-topik didukung (pewarisan yang sama seperti kunci config Telegram lainnya). + +```json5 +{ + channels: { + telegram: { + errorPolicy: "reply", + errorCooldownMs: 120000, + groups: { + "-1001234567890": { + errorPolicy: "silent", // tekan error di grup ini + }, + }, + }, + }, +} +``` + +## Pemecahan masalah + + + + + - Jika `requireMention=false`, mode privasi Telegram harus mengizinkan visibilitas penuh. + - BotFather: `/setprivacy` -> Disable + - lalu keluarkan + tambahkan kembali bot ke grup + - `openclaw channels status` memberi peringatan saat config mengharapkan pesan grup tanpa mention. + - `openclaw channels status --probe` dapat memeriksa ID grup numerik eksplisit; wildcard `"*"` tidak dapat diperiksa keanggotaannya. + - tes sesi cepat: `/activation always`. + + + + + + - saat `channels.telegram.groups` ada, grup harus tercantum (atau menyertakan `"*"`) + - verifikasi keanggotaan bot di grup + - tinjau log: `openclaw logs --follow` untuk alasan dilewati + + + + + + - otorisasi identitas pengirim Anda (pairing dan/atau `allowFrom` numerik) + - otorisasi perintah tetap berlaku meskipun kebijakan grup adalah `open` + - `setMyCommands failed` dengan `BOT_COMMANDS_TOO_MUCH` berarti menu native memiliki terlalu banyak entri; kurangi perintah plugin/skill/kustom atau nonaktifkan menu native + - `setMyCommands failed` dengan kesalahan jaringan/fetch biasanya menunjukkan masalah keterjangkauan DNS/HTTPS ke `api.telegram.org` + + + + + + - Node 22+ + fetch/proxy kustom dapat memicu perilaku abort langsung jika tipe AbortSignal tidak cocok. + - Beberapa host meresolusikan `api.telegram.org` ke IPv6 terlebih dahulu; egress IPv6 yang rusak dapat menyebabkan kegagalan API Telegram yang intermiten. + - Jika log menyertakan `TypeError: fetch failed` atau `Network request for 'getUpdates' failed!`, OpenClaw kini mencoba ulang ini sebagai kesalahan jaringan yang dapat dipulihkan. + - Pada host VPS dengan egress/TLS langsung yang tidak stabil, rute panggilan API Telegram melalui `channels.telegram.proxy`: + +```yaml +channels: + telegram: + proxy: socks5://:@proxy-host:1080 +``` + + - Default Node 22+ adalah `autoSelectFamily=true` (kecuali WSL2) dan `dnsResultOrder=ipv4first`. + - Jika host Anda adalah WSL2 atau memang bekerja lebih baik dengan perilaku hanya-IPv4, paksa pemilihan family: + +```yaml +channels: + telegram: + network: + autoSelectFamily: false +``` + + - Jawaban rentang benchmark RFC 2544 (`198.18.0.0/15`) sudah diizinkan + untuk unduhan media Telegram secara default. Jika proxy IP palsu atau + transparan tepercaya menulis ulang `api.telegram.org` ke alamat + private/internal/special-use lain saat unduhan media, Anda dapat memilih + bypass khusus Telegram berikut: + +```yaml +channels: + telegram: + network: + dangerouslyAllowPrivateNetwork: true +``` + + - Opsi ikut serta yang sama juga tersedia per akun di + `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. + - Jika proxy Anda meresolusikan host media Telegram ke `198.18.x.x`, biarkan + flag berbahaya itu nonaktif terlebih dahulu. Media Telegram sudah mengizinkan rentang benchmark RFC 2544 + secara default. + + + `channels.telegram.network.dangerouslyAllowPrivateNetwork` melemahkan perlindungan SSRF media Telegram. Gunakan hanya untuk lingkungan proxy tepercaya yang dikendalikan operator seperti routing fake-IP Clash, Mihomo, atau Surge ketika mereka mensintesis jawaban private atau special-use di luar rentang benchmark RFC 2544 default. Biarkan tetap nonaktif untuk akses Telegram internet publik normal. + + + - Override environment (sementara): + - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` + - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` + - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` + - Validasi jawaban DNS: + +```bash +dig +short api.telegram.org A +dig +short api.telegram.org AAAA +``` + + + + +Bantuan lebih lanjut: [Pemecahan masalah channel](/id/channels/troubleshooting). + +## Penunjuk referensi config Telegram + +Referensi utama: + +- `channels.telegram.enabled`: aktifkan/nonaktifkan startup channel. +- `channels.telegram.botToken`: token bot (BotFather). +- `channels.telegram.tokenFile`: baca token dari path file reguler. Symlink ditolak. +- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing). +- `channels.telegram.allowFrom`: allowlist DM (ID pengguna Telegram numerik). `allowlist` memerlukan setidaknya satu ID pengirim. `open` mengharuskan `"*"`. `openclaw doctor --fix` dapat meresolusikan entri `@username` lama ke ID dan dapat memulihkan entri allowlist dari file pairing-store dalam alur migrasi allowlist. +- `channels.telegram.actions.poll`: aktifkan atau nonaktifkan pembuatan poll Telegram (default: aktif; tetap memerlukan `sendMessage`). +- `channels.telegram.defaultTo`: target Telegram default yang digunakan CLI `--deliver` ketika tidak ada `--reply-to` eksplisit. +- `channels.telegram.groupPolicy`: `open | allowlist | disabled` (default: allowlist). +- `channels.telegram.groupAllowFrom`: allowlist pengirim grup (ID pengguna Telegram numerik). `openclaw doctor --fix` dapat meresolusikan entri `@username` lama ke ID. Entri non-numerik diabaikan saat auth. Auth grup tidak menggunakan fallback pairing-store DM (`2026.2.25+`). +- Prioritas multi-akun: + - Saat dua atau lebih ID akun dikonfigurasi, atur `channels.telegram.defaultAccount` (atau sertakan `channels.telegram.accounts.default`) untuk membuat routing default menjadi eksplisit. + - Jika keduanya tidak diatur, OpenClaw fallback ke ID akun pertama yang dinormalisasi dan `openclaw doctor` memberi peringatan. + - `channels.telegram.accounts.default.allowFrom` dan `channels.telegram.accounts.default.groupAllowFrom` hanya berlaku untuk akun `default`. + - Akun bernama mewarisi `channels.telegram.allowFrom` dan `channels.telegram.groupAllowFrom` saat nilai tingkat akun tidak diatur. + - Akun bernama tidak mewarisi `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`. +- `channels.telegram.groups`: default per-grup + allowlist (gunakan `"*"` untuk default global). + - `channels.telegram.groups..groupPolicy`: override per-grup untuk groupPolicy (`open | allowlist | disabled`). + - `channels.telegram.groups..requireMention`: default gating mention. + - `channels.telegram.groups..skills`: filter skill (hilangkan = semua skill, kosong = tidak ada). + - `channels.telegram.groups..allowFrom`: override allowlist pengirim per-grup. + - `channels.telegram.groups..systemPrompt`: system prompt tambahan untuk grup. + - `channels.telegram.groups..enabled`: nonaktifkan grup saat `false`. + - `channels.telegram.groups..topics..*`: override per-topik (field grup + `agentId` khusus topik). + - `channels.telegram.groups..topics..agentId`: rute topik ini ke agent tertentu (menimpa routing tingkat grup dan binding). +- `channels.telegram.groups..topics..groupPolicy`: override per-topik untuk groupPolicy (`open | allowlist | disabled`). +- `channels.telegram.groups..topics..requireMention`: override gating mention per-topik. +- `bindings[]` tingkat atas dengan `type: "acp"` dan ID topik kanonis `chatId:topic:topicId` di `match.peer.id`: field binding topik ACP persisten (lihat [ACP Agents](/tools/acp-agents#channel-specific-settings)). +- `channels.telegram.direct..topics..agentId`: rute topik DM ke agent tertentu (perilaku sama seperti topik forum). +- `channels.telegram.execApprovals.enabled`: aktifkan Telegram sebagai klien persetujuan exec berbasis chat untuk akun ini. +- `channels.telegram.execApprovals.approvers`: ID pengguna Telegram yang diizinkan untuk menyetujui atau menolak permintaan exec. Opsional saat `channels.telegram.allowFrom` atau `channels.telegram.defaultTo` langsung sudah mengidentifikasi pemilik. +- `channels.telegram.execApprovals.target`: `dm | channel | both` (default: `dm`). `channel` dan `both` mempertahankan topik Telegram asal jika ada. +- `channels.telegram.execApprovals.agentFilter`: filter ID agent opsional untuk prompt persetujuan yang diteruskan. +- `channels.telegram.execApprovals.sessionFilter`: filter kunci sesi opsional (substring atau regex) untuk prompt persetujuan yang diteruskan. +- `channels.telegram.accounts..execApprovals`: override per-akun untuk routing persetujuan exec Telegram dan otorisasi approver. +- `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (default: allowlist). +- `channels.telegram.accounts..capabilities.inlineButtons`: override per-akun. +- `channels.telegram.commands.nativeSkills`: aktifkan/nonaktifkan perintah native skills Telegram. +- `channels.telegram.replyToMode`: `off | first | all` (default: `off`). +- `channels.telegram.textChunkLimit`: ukuran potongan outbound (karakter). +- `channels.telegram.chunkMode`: `length` (default) atau `newline` untuk memisah pada baris kosong (batas paragraf) sebelum pemotongan berdasarkan panjang. +- `channels.telegram.linkPreview`: toggle pratinjau tautan untuk pesan outbound (default: true). +- `channels.telegram.streaming`: `off | partial | block | progress` (pratinjau live stream; default: `partial`; `progress` dipetakan ke `partial`; `block` adalah kompatibilitas mode pratinjau lama). Preview streaming Telegram menggunakan satu pesan pratinjau yang diedit di tempat. +- `channels.telegram.mediaMaxMb`: batas media Telegram inbound/outbound (MB, default: 100). +- `channels.telegram.retry`: kebijakan retry untuk helper pengiriman Telegram (CLI/tools/actions) pada kesalahan API outbound yang dapat dipulihkan (attempts, minDelayMs, maxDelayMs, jitter). +- `channels.telegram.network.autoSelectFamily`: timpa autoSelectFamily Node (true=aktifkan, false=nonaktifkan). Default aktif di Node 22+, dengan WSL2 default nonaktif. +- `channels.telegram.network.dnsResultOrder`: timpa urutan hasil DNS (`ipv4first` atau `verbatim`). Default `ipv4first` di Node 22+. +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opsi berbahaya untuk lingkungan fake-IP atau proxy transparan tepercaya di mana unduhan media Telegram meresolusikan `api.telegram.org` ke alamat private/internal/special-use di luar izin rentang benchmark RFC 2544 default. +- `channels.telegram.proxy`: URL proxy untuk panggilan Bot API (SOCKS/HTTP). +- `channels.telegram.webhookUrl`: aktifkan mode webhook (memerlukan `channels.telegram.webhookSecret`). +- `channels.telegram.webhookSecret`: secret webhook (wajib saat webhookUrl diatur). +- `channels.telegram.webhookPath`: path webhook lokal (default `/telegram-webhook`). +- `channels.telegram.webhookHost`: host bind webhook lokal (default `127.0.0.1`). +- `channels.telegram.webhookPort`: port bind webhook lokal (default `8787`). +- `channels.telegram.actions.reactions`: gate reaction tool Telegram. +- `channels.telegram.actions.sendMessage`: gate pengiriman pesan tool Telegram. +- `channels.telegram.actions.deleteMessage`: gate penghapusan pesan tool Telegram. +- `channels.telegram.actions.sticker`: gate aksi stiker Telegram — kirim dan cari (default: false). +- `channels.telegram.reactionNotifications`: `off | own | all` — kontrol reaction mana yang memicu event sistem (default: `own` saat tidak diatur). +- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — kontrol kemampuan reaction agent (default: `minimal` saat tidak diatur). +- `channels.telegram.errorPolicy`: `reply | silent` — kontrol perilaku balasan error (default: `reply`). Override per-akun/grup/topik didukung. +- `channels.telegram.errorCooldownMs`: minimum ms antar balasan error ke chat yang sama (default: `60000`). Mencegah spam error selama gangguan. + +- [Referensi konfigurasi - Telegram](/gateway/configuration-reference#telegram) + +Field Telegram khusus dengan sinyal tinggi: + +- startup/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` harus menunjuk ke file reguler; symlink ditolak) +- kontrol akses: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` tingkat atas (`type: "acp"`) +- persetujuan exec: `execApprovals`, `accounts.*.execApprovals` +- perintah/menu: `commands.native`, `commands.nativeSkills`, `customCommands` +- threading/balasan: `replyToMode` +- streaming: `streaming` (pratinjau), `blockStreaming` +- pemformatan/pengiriman: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` +- media/jaringan: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` +- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- aksi/kapabilitas: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` +- reaction: `reactionNotifications`, `reactionLevel` +- error: `errorPolicy`, `errorCooldownMs` +- penulisan/riwayat: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` + +## Terkait + +- [Pairing](/id/channels/pairing) +- [Grup](/id/channels/groups) +- [Keamanan](/gateway/security) +- [Routing channel](/id/channels/channel-routing) +- [Routing multi-agent](/concepts/multi-agent) +- [Pemecahan masalah](/id/channels/troubleshooting) diff --git a/docs/id/channels/tlon.md b/docs/id/channels/tlon.md new file mode 100644 index 000000000..0b92dfe4b --- /dev/null +++ b/docs/id/channels/tlon.md @@ -0,0 +1,297 @@ +--- +read_when: + - Mengerjakan fitur channel Tlon/Urbit +summary: Status dukungan Tlon/Urbit, kemampuan, dan konfigurasi +title: Tlon +x-i18n: + generated_at: "2026-04-05T13:44:35Z" + model: gpt-5.4 + provider: openai + source_hash: 289cffb3c1b2d450a5f41e0d67117dfb5c192cec956d82039caac9df9f07496d + source_path: channels/tlon.md + workflow: 15 +--- + +# Tlon + +Tlon adalah messenger terdesentralisasi yang dibangun di atas Urbit. OpenClaw terhubung ke ship Urbit Anda dan dapat +merespons DM serta pesan chat grup. Balasan grup secara default memerlukan mention @ dan dapat +dibatasi lebih lanjut melalui allowlist. + +Status: plugin bawaan. DM, mention grup, balasan thread, pemformatan rich text, dan +unggahan gambar didukung. Reaksi dan polling belum didukung. + +## Plugin bawaan + +Tlon tersedia sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build paket +normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Tlon, instal secara +manual: + +Instal melalui CLI (registri npm): + +```bash +openclaw plugins install @openclaw/tlon +``` + +Checkout lokal (saat berjalan dari repositori git): + +```bash +openclaw plugins install ./path/to/local/tlon-plugin +``` + +Detail: [Plugins](/tools/plugin) + +## Penyiapan + +1. Pastikan plugin Tlon tersedia. + - Rilis OpenClaw paket saat ini sudah menyertakan plugin ini. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Siapkan URL ship dan kode login Anda. +3. Konfigurasikan `channels.tlon`. +4. Mulai ulang gateway. +5. Kirim DM ke bot atau mention bot di channel grup. + +Konfigurasi minimal (akun tunggal): + +```json5 +{ + channels: { + tlon: { + enabled: true, + ship: "~sampel-palnet", + url: "https://your-ship-host", + code: "lidlut-tabwed-pillex-ridrup", + ownerShip: "~your-main-ship", // direkomendasikan: ship Anda, selalu diizinkan + }, + }, +} +``` + +## Ship privat/LAN + +Secara default, OpenClaw memblokir hostname dan rentang IP privat/internal untuk perlindungan SSRF. +Jika ship Anda berjalan di jaringan privat (localhost, IP LAN, atau hostname internal), +Anda harus mengaktifkannya secara eksplisit: + +```json5 +{ + channels: { + tlon: { + url: "http://localhost:8080", + allowPrivateNetwork: true, + }, + }, +} +``` + +Ini berlaku untuk URL seperti: + +- `http://localhost:8080` +- `http://192.168.x.x:8080` +- `http://my-ship.local:8080` + +⚠️ Aktifkan ini hanya jika Anda memercayai jaringan lokal Anda. Pengaturan ini menonaktifkan perlindungan SSRF +untuk permintaan ke URL ship Anda. + +## Channel grup + +Penemuan otomatis diaktifkan secara default. Anda juga dapat menyematkan channel secara manual: + +```json5 +{ + channels: { + tlon: { + groupChannels: ["chat/~host-ship/general", "chat/~host-ship/support"], + }, + }, +} +``` + +Nonaktifkan penemuan otomatis: + +```json5 +{ + channels: { + tlon: { + autoDiscoverChannels: false, + }, + }, +} +``` + +## Kontrol akses + +Allowlist DM (kosong = tidak ada DM yang diizinkan, gunakan `ownerShip` untuk alur persetujuan): + +```json5 +{ + channels: { + tlon: { + dmAllowlist: ["~zod", "~nec"], + }, + }, +} +``` + +Otorisasi grup (dibatasi secara default): + +```json5 +{ + channels: { + tlon: { + defaultAuthorizedShips: ["~zod"], + authorization: { + channelRules: { + "chat/~host-ship/general": { + mode: "restricted", + allowedShips: ["~zod", "~nec"], + }, + "chat/~host-ship/announcements": { + mode: "open", + }, + }, + }, + }, + }, +} +``` + +## Sistem owner dan persetujuan + +Atur ship owner untuk menerima permintaan persetujuan saat pengguna yang tidak diotorisasi mencoba berinteraksi: + +```json5 +{ + channels: { + tlon: { + ownerShip: "~your-main-ship", + }, + }, +} +``` + +Ship owner **secara otomatis diotorisasi di mana saja** — undangan DM diterima otomatis dan +pesan channel selalu diizinkan. Anda tidak perlu menambahkan owner ke `dmAllowlist` atau +`defaultAuthorizedShips`. + +Saat diatur, owner menerima notifikasi DM untuk: + +- permintaan DM dari ship yang tidak ada di allowlist +- mention di channel tanpa otorisasi +- permintaan undangan grup + +## Pengaturan terima otomatis + +Terima otomatis undangan DM (untuk ship di `dmAllowlist`): + +```json5 +{ + channels: { + tlon: { + autoAcceptDmInvites: true, + }, + }, +} +``` + +Terima otomatis undangan grup: + +```json5 +{ + channels: { + tlon: { + autoAcceptGroupInvites: true, + }, + }, +} +``` + +## Target pengiriman (CLI/cron) + +Gunakan ini dengan `openclaw message send` atau pengiriman cron: + +- DM: `~sampel-palnet` atau `dm/~sampel-palnet` +- Grup: `chat/~host-ship/channel` atau `group:~host-ship/channel` + +## Skill bawaan + +Plugin Tlon menyertakan skill bawaan ([`@tloncorp/tlon-skill`](https://github.com/tloncorp/tlon-skill)) +yang menyediakan akses CLI ke operasi Tlon: + +- **Kontak**: dapatkan/perbarui profil, daftar kontak +- **Channel**: daftar, buat, kirim pesan, ambil riwayat +- **Grup**: daftar, buat, kelola anggota +- **DM**: kirim pesan, beri reaksi pada pesan +- **Reaksi**: tambahkan/hapus reaksi emoji ke post dan DM +- **Pengaturan**: kelola izin plugin melalui perintah slash + +Skill ini otomatis tersedia saat plugin diinstal. + +## Kemampuan + +| Fitur | Status | +| --------------- | --------------------------------------- | +| Pesan langsung | ✅ Didukung | +| Grup/channel | ✅ Didukung (secara default dibatasi mention) | +| Thread | ✅ Didukung (balasan otomatis di thread) | +| Rich text | ✅ Markdown dikonversi ke format Tlon | +| Gambar | ✅ Diunggah ke penyimpanan Tlon | +| Reaksi | ✅ Melalui [skill bawaan](#skill-bawaan) | +| Polling | ❌ Belum didukung | +| Perintah native | ✅ Didukung (secara default hanya owner) | + +## Pemecahan masalah + +Jalankan urutan ini terlebih dahulu: + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +``` + +Kegagalan umum: + +- **DM diabaikan**: pengirim tidak ada di `dmAllowlist` dan tidak ada `ownerShip` yang dikonfigurasi untuk alur persetujuan. +- **Pesan grup diabaikan**: channel tidak ditemukan atau pengirim tidak diotorisasi. +- **Error koneksi**: periksa apakah URL ship dapat dijangkau; aktifkan `allowPrivateNetwork` untuk ship lokal. +- **Error autentikasi**: pastikan kode login masih berlaku (kode berotasi). + +## Referensi konfigurasi + +Konfigurasi lengkap: [Konfigurasi](/gateway/configuration) + +Opsi provider: + +- `channels.tlon.enabled`: aktifkan/nonaktifkan startup channel. +- `channels.tlon.ship`: nama ship Urbit bot (mis. `~sampel-palnet`). +- `channels.tlon.url`: URL ship (mis. `https://sampel-palnet.tlon.network`). +- `channels.tlon.code`: kode login ship. +- `channels.tlon.allowPrivateNetwork`: izinkan URL localhost/LAN (melewati SSRF). +- `channels.tlon.ownerShip`: ship owner untuk sistem persetujuan (selalu diotorisasi). +- `channels.tlon.dmAllowlist`: ship yang diizinkan mengirim DM (kosong = tidak ada). +- `channels.tlon.autoAcceptDmInvites`: terima otomatis DM dari ship yang ada di allowlist. +- `channels.tlon.autoAcceptGroupInvites`: terima otomatis semua undangan grup. +- `channels.tlon.autoDiscoverChannels`: temukan channel grup secara otomatis (default: true). +- `channels.tlon.groupChannels`: nest channel yang disematkan secara manual. +- `channels.tlon.defaultAuthorizedShips`: ship yang diotorisasi untuk semua channel. +- `channels.tlon.authorization.channelRules`: aturan otorisasi per channel. +- `channels.tlon.showModelSignature`: tambahkan nama model ke pesan. + +## Catatan + +- Balasan grup memerlukan mention (mis. `~your-bot-ship`) agar merespons. +- Balasan thread: jika pesan masuk berada di thread, OpenClaw akan membalas di thread. +- Rich text: pemformatan Markdown (tebal, miring, kode, header, daftar) dikonversi ke format native Tlon. +- Gambar: URL diunggah ke penyimpanan Tlon dan disematkan sebagai blok gambar. + +## Terkait + +- [Ikhtisar Channel](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Grup](/channels/groups) — perilaku chat grup dan penyaringan mention +- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/troubleshooting.md b/docs/id/channels/troubleshooting.md new file mode 100644 index 000000000..420e913ff --- /dev/null +++ b/docs/id/channels/troubleshooting.md @@ -0,0 +1,140 @@ +--- +read_when: + - Transport channel menunjukkan terhubung tetapi balasan gagal + - Anda memerlukan pemeriksaan khusus channel sebelum dokumentasi provider yang lebih mendalam +summary: Pemecahan masalah level channel dengan cepat menggunakan signature kegagalan dan perbaikan per channel +title: Channel Troubleshooting +x-i18n: + generated_at: "2026-04-05T13:44:43Z" + model: gpt-5.4 + provider: openai + source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f + source_path: channels/troubleshooting.md + workflow: 15 +--- + +# Pemecahan masalah channel + +Gunakan halaman ini saat sebuah channel terhubung tetapi perilakunya salah. + +## Urutan perintah + +Jalankan ini terlebih dahulu secara berurutan: + +```bash +openclaw status +openclaw gateway status +openclaw logs --follow +openclaw doctor +openclaw channels status --probe +``` + +Baseline sehat: + +- `Runtime: running` +- `RPC probe: ok` +- Probe channel menunjukkan transport terhubung dan, jika didukung, `works` atau `audit ok` + +## WhatsApp + +### Signature kegagalan WhatsApp + +| Gejala | Pemeriksaan tercepat | Perbaikan | +| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------- | +| Terhubung tetapi tidak ada balasan DM | `openclaw pairing list whatsapp` | Setujui pengirim atau ubah kebijakan/allowlist DM. | +| Pesan grup diabaikan | Periksa `requireMention` + pola mention di konfigurasi | Mention bot atau longgarkan kebijakan mention untuk grup itu. | +| Putus sambung acak/loop login ulang | `openclaw channels status --probe` + log | Login ulang dan verifikasi direktori kredensial sehat. | + +Pemecahan masalah lengkap: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting) + +## Telegram + +### Signature kegagalan Telegram + +| Gejala | Pemeriksaan tercepat | Perbaikan | +| ----------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- | +| `/start` tetapi tidak ada alur balasan yang dapat digunakan | `openclaw pairing list telegram` | Setujui pairing atau ubah kebijakan DM. | +| Bot online tetapi grup tetap diam | Verifikasi persyaratan mention dan mode privasi bot | Nonaktifkan mode privasi untuk visibilitas grup atau mention bot. | +| Kegagalan kirim dengan kesalahan jaringan | Periksa log untuk kegagalan panggilan Telegram API | Perbaiki routing DNS/IPv6/proxy ke `api.telegram.org`. | +| `setMyCommands` ditolak saat startup | Periksa log untuk `BOT_COMMANDS_TOO_MUCH` | Kurangi perintah Telegram plugin/Skills/kustom atau nonaktifkan menu native. | +| Sudah upgrade dan allowlist memblokir Anda | `openclaw security audit` dan allowlist konfigurasi | Jalankan `openclaw doctor --fix` atau ganti `@username` dengan ID pengirim numerik. | + +Pemecahan masalah lengkap: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) + +## Discord + +### Signature kegagalan Discord + +| Gejala | Pemeriksaan tercepat | Perbaikan | +| ----------------------------- | --------------------------------- | --------------------------------------------------------- | +| Bot online tetapi tidak ada balasan guild | `openclaw channels status --probe` | Izinkan guild/channel dan verifikasi message content intent. | +| Pesan grup diabaikan | Periksa log untuk drop mention gating | Mention bot atau setel guild/channel `requireMention: false`. | +| Balasan DM tidak ada | `openclaw pairing list discord` | Setujui pairing DM atau sesuaikan kebijakan DM. | + +Pemecahan masalah lengkap: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) + +## Slack + +### Signature kegagalan Slack + +| Gejala | Pemeriksaan tercepat | Perbaikan | +| -------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| Socket mode terhubung tetapi tidak ada respons | `openclaw channels status --probe` | Verifikasi app token + bot token dan scope yang diperlukan; perhatikan `botTokenStatus` / `appTokenStatus = configured_unavailable` pada penyiapan berbasis SecretRef. | +| DM diblokir | `openclaw pairing list slack` | Setujui pairing atau longgarkan kebijakan DM. | +| Pesan channel diabaikan | Periksa `groupPolicy` dan allowlist channel | Izinkan channel atau ubah kebijakan menjadi `open`. | + +Pemecahan masalah lengkap: [/channels/slack#troubleshooting](/channels/slack#troubleshooting) + +## iMessage dan BlueBubbles + +### Signature kegagalan iMessage dan BlueBubbles + +| Gejala | Pemeriksaan tercepat | Perbaikan | +| ------------------------------ | ------------------------------------------------------------------------- | ----------------------------------------------------- | +| Tidak ada event masuk | Verifikasi keterjangkauan webhook/server dan izin aplikasi | Perbaiki URL webhook atau status server BlueBubbles. | +| Bisa mengirim tetapi tidak menerima di macOS | Periksa izin privasi macOS untuk otomasi Messages | Berikan ulang izin TCC dan restart proses channel. | +| Pengirim DM diblokir | `openclaw pairing list imessage` atau `openclaw pairing list bluebubbles` | Setujui pairing atau perbarui allowlist. | + +Pemecahan masalah lengkap: + +- [/channels/imessage#troubleshooting](/channels/imessage#troubleshooting) +- [/channels/bluebubbles#troubleshooting](/channels/bluebubbles#troubleshooting) + +## Signal + +### Signature kegagalan Signal + +| Gejala | Pemeriksaan tercepat | Perbaikan | +| ----------------------------- | ---------------------------------------- | -------------------------------------------------------- | +| Daemon dapat dijangkau tetapi bot diam | `openclaw channels status --probe` | Verifikasi URL/akun daemon `signal-cli` dan mode receive. | +| DM diblokir | `openclaw pairing list signal` | Setujui pengirim atau sesuaikan kebijakan DM. | +| Balasan grup tidak terpicu | Periksa allowlist grup dan pola mention | Tambahkan pengirim/grup atau longgarkan gating. | + +Pemecahan masalah lengkap: [/channels/signal#troubleshooting](/channels/signal#troubleshooting) + +## QQ Bot + +### Signature kegagalan QQ Bot + +| Gejala | Pemeriksaan tercepat | Perbaikan | +| ----------------------------- | ------------------------------------------------- | ---------------------------------------------------------------- | +| Bot membalas "gone to Mars" | Verifikasi `appId` dan `clientSecret` di konfigurasi | Setel kredensial atau restart gateway. | +| Tidak ada pesan masuk | `openclaw channels status --probe` | Verifikasi kredensial di QQ Open Platform. | +| Suara tidak ditranskripsikan | Periksa konfigurasi provider STT | Konfigurasikan `channels.qqbot.stt` atau `tools.media.audio`. | +| Pesan proaktif tidak sampai | Periksa persyaratan interaksi platform QQ | QQ mungkin memblokir pesan yang diprakarsai bot tanpa interaksi baru-baru ini. | + +Pemecahan masalah lengkap: [/channels/qqbot#troubleshooting](/channels/qqbot#troubleshooting) + +## Matrix + +### Signature kegagalan Matrix + +| Gejala | Pemeriksaan tercepat | Perbaikan | +| ----------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- | +| Sudah login tetapi mengabaikan pesan room | `openclaw channels status --probe` | Periksa `groupPolicy`, allowlist room, dan mention gating. | +| DM tidak diproses | `openclaw pairing list matrix` | Setujui pengirim atau sesuaikan kebijakan DM. | +| Room terenkripsi gagal | `openclaw matrix verify status` | Verifikasi ulang device, lalu periksa `openclaw matrix verify backup status`. | +| Pemulihan backup tertunda/rusak | `openclaw matrix verify backup status` | Jalankan `openclaw matrix verify backup restore` atau jalankan ulang dengan recovery key. | +| Cross-signing/bootstrap tampak salah | `openclaw matrix verify bootstrap` | Perbaiki status secret storage, cross-signing, dan backup dalam satu langkah. | + +Penyiapan dan konfigurasi lengkap: [Matrix](/channels/matrix) diff --git a/docs/id/channels/twitch.md b/docs/id/channels/twitch.md new file mode 100644 index 000000000..ffd50cfea --- /dev/null +++ b/docs/id/channels/twitch.md @@ -0,0 +1,401 @@ +--- +read_when: + - Menyiapkan integrasi chat Twitch untuk OpenClaw +summary: Konfigurasi dan penyiapan bot chat Twitch +title: Twitch +x-i18n: + generated_at: "2026-04-05T13:44:54Z" + model: gpt-5.4 + provider: openai + source_hash: 47af9fb6edb1f462c5919850ee9d05e500a1914ddd0d64a41608fbe960e77cd6 + source_path: channels/twitch.md + workflow: 15 +--- + +# Twitch + +Dukungan chat Twitch melalui koneksi IRC. OpenClaw terhubung sebagai pengguna Twitch (akun bot) untuk menerima dan mengirim pesan di channel. + +## Plugin bawaan + +Twitch dikirim sebagai plugin bawaan di rilis OpenClaw saat ini, jadi build +paket normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Twitch, instal +secara manual: + +Instal melalui CLI (registry npm): + +```bash +openclaw plugins install @openclaw/twitch +``` + +Checkout lokal (saat berjalan dari repo git): + +```bash +openclaw plugins install ./path/to/local/twitch-plugin +``` + +Detail: [Plugins](/tools/plugin) + +## Penyiapan cepat (pemula) + +1. Pastikan plugin Twitch tersedia. + - Rilis OpenClaw terpaket saat ini sudah menyertakannya. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Buat akun Twitch khusus untuk bot (atau gunakan akun yang sudah ada). +3. Buat kredensial: [Twitch Token Generator](https://twitchtokengenerator.com/) + - Pilih **Bot Token** + - Pastikan scope `chat:read` dan `chat:write` dipilih + - Salin **Client ID** dan **Access Token** +4. Temukan ID pengguna Twitch Anda: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) +5. Konfigurasikan token: + - Env: `OPENCLAW_TWITCH_ACCESS_TOKEN=...` (hanya akun default) + - Atau config: `channels.twitch.accessToken` + - Jika keduanya ditetapkan, config lebih diutamakan (fallback env hanya untuk akun default). +6. Mulai gateway. + +**⚠️ Penting:** Tambahkan kontrol akses (`allowFrom` atau `allowedRoles`) untuk mencegah pengguna yang tidak berwenang memicu bot. `requireMention` default ke `true`. + +Config minimal: + +```json5 +{ + channels: { + twitch: { + enabled: true, + username: "openclaw", // Akun Twitch bot + accessToken: "oauth:abc123...", // OAuth Access Token (atau gunakan env var OPENCLAW_TWITCH_ACCESS_TOKEN) + clientId: "xyz789...", // Client ID dari Token Generator + channel: "vevisk", // Chat channel Twitch yang akan diikuti (wajib) + allowFrom: ["123456789"], // (disarankan) Hanya ID pengguna Twitch Anda - dapatkan dari https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/ + }, + }, +} +``` + +## Apa ini + +- Channel Twitch yang dimiliki oleh Gateway. +- Routing deterministik: balasan selalu kembali ke Twitch. +- Setiap akun dipetakan ke kunci sesi terisolasi `agent::twitch:`. +- `username` adalah akun bot (yang melakukan autentikasi), `channel` adalah ruang chat yang akan diikuti. + +## Penyiapan (detail) + +### Buat kredensial + +Gunakan [Twitch Token Generator](https://twitchtokengenerator.com/): + +- Pilih **Bot Token** +- Pastikan scope `chat:read` dan `chat:write` dipilih +- Salin **Client ID** dan **Access Token** + +Tidak perlu pendaftaran aplikasi manual. Token kedaluwarsa setelah beberapa jam. + +### Konfigurasikan bot + +**Env var (hanya akun default):** + +```bash +OPENCLAW_TWITCH_ACCESS_TOKEN=oauth:abc123... +``` + +**Atau config:** + +```json5 +{ + channels: { + twitch: { + enabled: true, + username: "openclaw", + accessToken: "oauth:abc123...", + clientId: "xyz789...", + channel: "vevisk", + }, + }, +} +``` + +Jika env dan config sama-sama ditetapkan, config lebih diutamakan. + +### Kontrol akses (disarankan) + +```json5 +{ + channels: { + twitch: { + allowFrom: ["123456789"], // (disarankan) Hanya ID pengguna Twitch Anda + }, + }, +} +``` + +Utamakan `allowFrom` untuk allowlist yang ketat. Gunakan `allowedRoles` jika Anda menginginkan akses berbasis peran. + +**Peran yang tersedia:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`. + +**Mengapa ID pengguna?** Nama pengguna dapat berubah, sehingga memungkinkan penyamaran. ID pengguna bersifat permanen. + +Temukan ID pengguna Twitch Anda: [https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/](https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/) (Konversi nama pengguna Twitch Anda ke ID) + +## Penyegaran token (opsional) + +Token dari [Twitch Token Generator](https://twitchtokengenerator.com/) tidak dapat disegarkan secara otomatis - buat ulang saat kedaluwarsa. + +Untuk penyegaran token otomatis, buat aplikasi Twitch Anda sendiri di [Twitch Developer Console](https://dev.twitch.tv/console) lalu tambahkan ke config: + +```json5 +{ + channels: { + twitch: { + clientSecret: "your_client_secret", + refreshToken: "your_refresh_token", + }, + }, +} +``` + +Bot secara otomatis menyegarkan token sebelum kedaluwarsa dan mencatat event penyegaran. + +## Dukungan multi-akun + +Gunakan `channels.twitch.accounts` dengan token per akun. Lihat [`gateway/configuration`](/gateway/configuration) untuk pola bersama. + +Contoh (satu akun bot di dua channel): + +```json5 +{ + channels: { + twitch: { + accounts: { + channel1: { + username: "openclaw", + accessToken: "oauth:abc123...", + clientId: "xyz789...", + channel: "vevisk", + }, + channel2: { + username: "openclaw", + accessToken: "oauth:def456...", + clientId: "uvw012...", + channel: "secondchannel", + }, + }, + }, + }, +} +``` + +**Catatan:** Setiap akun memerlukan tokennya sendiri (satu token per channel). + +## Kontrol akses + +### Pembatasan berbasis peran + +```json5 +{ + channels: { + twitch: { + accounts: { + default: { + allowedRoles: ["moderator", "vip"], + }, + }, + }, + }, +} +``` + +### Allowlist berdasarkan ID Pengguna (paling aman) + +```json5 +{ + channels: { + twitch: { + accounts: { + default: { + allowFrom: ["123456789", "987654321"], + }, + }, + }, + }, +} +``` + +### Akses berbasis peran (alternatif) + +`allowFrom` adalah allowlist yang ketat. Jika ditetapkan, hanya ID pengguna tersebut yang diizinkan. +Jika Anda menginginkan akses berbasis peran, biarkan `allowFrom` tidak ditetapkan dan konfigurasi `allowedRoles` sebagai gantinya: + +```json5 +{ + channels: { + twitch: { + accounts: { + default: { + allowedRoles: ["moderator"], + }, + }, + }, + }, +} +``` + +### Nonaktifkan persyaratan @mention + +Secara default, `requireMention` adalah `true`. Untuk menonaktifkannya dan merespons semua pesan: + +```json5 +{ + channels: { + twitch: { + accounts: { + default: { + requireMention: false, + }, + }, + }, + }, +} +``` + +## Troubleshooting + +Pertama, jalankan perintah diagnostik: + +```bash +openclaw doctor +openclaw channels status --probe +``` + +### Bot tidak merespons pesan + +**Periksa kontrol akses:** Pastikan ID pengguna Anda ada di `allowFrom`, atau hapus sementara +`allowFrom` dan tetapkan `allowedRoles: ["all"]` untuk pengujian. + +**Periksa apakah bot ada di channel:** Bot harus bergabung ke channel yang ditentukan di `channel`. + +### Masalah token + +**"Failed to connect" atau error autentikasi:** + +- Pastikan `accessToken` adalah nilai token akses OAuth (biasanya diawali prefiks `oauth:`) +- Pastikan token memiliki scope `chat:read` dan `chat:write` +- Jika menggunakan penyegaran token, pastikan `clientSecret` dan `refreshToken` ditetapkan + +### Penyegaran token tidak berfungsi + +**Periksa log untuk event penyegaran:** + +``` +Using env token source for mybot +Access token refreshed for user 123456 (expires in 14400s) +``` + +Jika Anda melihat "token refresh disabled (no refresh token)": + +- Pastikan `clientSecret` disediakan +- Pastikan `refreshToken` disediakan + +## Config + +**Config akun:** + +- `username` - Nama pengguna bot +- `accessToken` - Token akses OAuth dengan `chat:read` dan `chat:write` +- `clientId` - Twitch Client ID (dari Token Generator atau aplikasi Anda) +- `channel` - Channel yang akan diikuti (wajib) +- `enabled` - Aktifkan akun ini (default: `true`) +- `clientSecret` - Opsional: Untuk penyegaran token otomatis +- `refreshToken` - Opsional: Untuk penyegaran token otomatis +- `expiresIn` - Masa berlaku token dalam detik +- `obtainmentTimestamp` - Stempel waktu saat token diperoleh +- `allowFrom` - Allowlist ID pengguna +- `allowedRoles` - Kontrol akses berbasis peran (`"moderator" | "owner" | "vip" | "subscriber" | "all"`) +- `requireMention` - Wajibkan @mention (default: `true`) + +**Opsi penyedia:** + +- `channels.twitch.enabled` - Aktifkan/nonaktifkan startup channel +- `channels.twitch.username` - Nama pengguna bot (config satu akun yang disederhanakan) +- `channels.twitch.accessToken` - Token akses OAuth (config satu akun yang disederhanakan) +- `channels.twitch.clientId` - Twitch Client ID (config satu akun yang disederhanakan) +- `channels.twitch.channel` - Channel yang akan diikuti (config satu akun yang disederhanakan) +- `channels.twitch.accounts.` - Config multi-akun (semua field akun di atas) + +Contoh lengkap: + +```json5 +{ + channels: { + twitch: { + enabled: true, + username: "openclaw", + accessToken: "oauth:abc123...", + clientId: "xyz789...", + channel: "vevisk", + clientSecret: "secret123...", + refreshToken: "refresh456...", + allowFrom: ["123456789"], + allowedRoles: ["moderator", "vip"], + accounts: { + default: { + username: "mybot", + accessToken: "oauth:abc123...", + clientId: "xyz789...", + channel: "your_channel", + enabled: true, + clientSecret: "secret123...", + refreshToken: "refresh456...", + expiresIn: 14400, + obtainmentTimestamp: 1706092800000, + allowFrom: ["123456789", "987654321"], + allowedRoles: ["moderator"], + }, + }, + }, + }, +} +``` + +## Aksi tool + +Agen dapat memanggil `twitch` dengan aksi: + +- `send` - Mengirim pesan ke channel + +Contoh: + +```json5 +{ + action: "twitch", + params: { + message: "Hello Twitch!", + to: "#mychannel", + }, +} +``` + +## Keamanan & operasi + +- **Perlakukan token seperti kata sandi** - Jangan pernah mengomit token ke git +- **Gunakan penyegaran token otomatis** untuk bot yang berjalan lama +- **Gunakan allowlist ID pengguna** alih-alih nama pengguna untuk kontrol akses +- **Pantau log** untuk event penyegaran token dan status koneksi +- **Batasi scope token seminimal mungkin** - Hanya minta `chat:read` dan `chat:write` +- **Jika buntu**: Mulai ulang gateway setelah memastikan tidak ada proses lain yang memiliki sesi + +## Batasan + +- **500 karakter** per pesan (dipotong otomatis di batas kata) +- Markdown dihapus sebelum pemotongan +- Tidak ada pembatasan laju (menggunakan batas laju bawaan Twitch) + +## Terkait + +- [Channels Overview](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku group chat dan pembatasan mention +- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan +- [Security](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/whatsapp.md b/docs/id/channels/whatsapp.md new file mode 100644 index 000000000..b482a7688 --- /dev/null +++ b/docs/id/channels/whatsapp.md @@ -0,0 +1,495 @@ +--- +read_when: + - Sedang mengerjakan perilaku channel WhatsApp/web atau perutean inbox +summary: Dukungan channel WhatsApp, kontrol akses, perilaku pengiriman, dan operasi +title: WhatsApp +x-i18n: + generated_at: "2026-04-05T13:45:01Z" + model: gpt-5.4 + provider: openai + source_hash: c16a468b3f47fdf7e4fc3fd745b5c49c7ccebb7af0e8c87c632b78b04c583e49 + source_path: channels/whatsapp.md + workflow: 15 +--- + +# WhatsApp (Web channel) + +Status: siap produksi melalui WhatsApp Web (Baileys). Gateway memiliki sesi tertaut. + +## Instal (sesuai kebutuhan) + +- Onboarding (`openclaw onboard`) dan `openclaw channels add --channel whatsapp` + akan meminta Anda menginstal plugin WhatsApp saat pertama kali memilihnya. +- `openclaw channels login --channel whatsapp` juga menawarkan alur instalasi saat + plugin belum tersedia. +- Dev channel + checkout git: default ke path plugin lokal. +- Stable/Beta: default ke paket npm `@openclaw/whatsapp`. + +Instalasi manual tetap tersedia: + +```bash +openclaw plugins install @openclaw/whatsapp +``` + + + + Kebijakan DM default adalah pairing untuk pengirim yang tidak dikenal. + + + Diagnostik lintas channel dan panduan perbaikan. + + + Pola dan contoh config channel lengkap. + + + +## Penyiapan cepat + + + + +```json5 +{ + channels: { + whatsapp: { + dmPolicy: "pairing", + allowFrom: ["+15551234567"], + groupPolicy: "allowlist", + groupAllowFrom: ["+15551234567"], + }, + }, +} +``` + + + + + +```bash +openclaw channels login --channel whatsapp +``` + + Untuk akun tertentu: + +```bash +openclaw channels login --channel whatsapp --account work +``` + + + + + +```bash +openclaw gateway +``` + + + + + +```bash +openclaw pairing list whatsapp +openclaw pairing approve whatsapp +``` + + Permintaan pairing kedaluwarsa setelah 1 jam. Permintaan tertunda dibatasi hingga 3 per channel. + + + + + +OpenClaw merekomendasikan menjalankan WhatsApp pada nomor terpisah jika memungkinkan. (Metadata channel dan alur penyiapan dioptimalkan untuk penyiapan tersebut, tetapi penyiapan nomor pribadi juga didukung.) + + +## Pola deployment + + + + Ini adalah mode operasional yang paling bersih: + + - identitas WhatsApp terpisah untuk OpenClaw + - allowlist DM dan batas perutean yang lebih jelas + - kemungkinan kebingungan obrolan sendiri yang lebih rendah + + Pola kebijakan minimal: + + ```json5 + { + channels: { + whatsapp: { + dmPolicy: "allowlist", + allowFrom: ["+15551234567"], + }, + }, + } + ``` + + + + + Onboarding mendukung mode nomor pribadi dan menulis baseline yang ramah obrolan sendiri: + + - `dmPolicy: "allowlist"` + - `allowFrom` mencakup nomor pribadi Anda + - `selfChatMode: true` + + Dalam runtime, perlindungan obrolan sendiri bergantung pada nomor diri tertaut dan `allowFrom`. + + + + + Channel platform pesan berbasis WhatsApp Web (`Baileys`) dalam arsitektur channel OpenClaw saat ini. + + Tidak ada channel pesan Twilio WhatsApp terpisah dalam registry channel obrolan bawaan. + + + + +## Model runtime + +- Gateway memiliki socket WhatsApp dan loop reconnect. +- Pengiriman keluar memerlukan listener WhatsApp aktif untuk akun target. +- Obrolan status dan siaran diabaikan (`@status`, `@broadcast`). +- Obrolan langsung menggunakan aturan sesi DM (`session.dmScope`; default `main` menggabungkan DM ke sesi utama agen). +- Sesi grup diisolasi (`agent::whatsapp:group:`). + +## Kontrol akses dan aktivasi + + + + `channels.whatsapp.dmPolicy` mengontrol akses obrolan langsung: + + - `pairing` (default) + - `allowlist` + - `open` (memerlukan `allowFrom` untuk menyertakan `"*"`) + - `disabled` + + `allowFrom` menerima nomor bergaya E.164 (dinormalisasi secara internal). + + Override multi-akun: `channels.whatsapp.accounts..dmPolicy` (dan `allowFrom`) lebih diprioritaskan daripada default tingkat channel untuk akun tersebut. + + Detail perilaku runtime: + + - pairing disimpan di allow-store channel dan digabungkan dengan `allowFrom` yang dikonfigurasi + - jika tidak ada allowlist yang dikonfigurasi, nomor diri tertaut diizinkan secara default + - DM keluar `fromMe` tidak pernah dipair otomatis + + + + + Akses grup memiliki dua lapisan: + + 1. **Allowlist keanggotaan grup** (`channels.whatsapp.groups`) + - jika `groups` dihilangkan, semua grup memenuhi syarat + - jika `groups` ada, itu bertindak sebagai allowlist grup (`"*"` diperbolehkan) + + 2. **Kebijakan pengirim grup** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) + - `open`: allowlist pengirim dilewati + - `allowlist`: pengirim harus cocok dengan `groupAllowFrom` (atau `*`) + - `disabled`: blokir semua grup masuk + + Fallback allowlist pengirim: + + - jika `groupAllowFrom` tidak diatur, runtime fallback ke `allowFrom` jika tersedia + - allowlist pengirim dievaluasi sebelum aktivasi mention/balasan + + Catatan: jika tidak ada blok `channels.whatsapp` sama sekali, fallback kebijakan grup runtime adalah `allowlist` (dengan log peringatan), bahkan jika `channels.defaults.groupPolicy` diatur. + + + + + Balasan grup memerlukan mention secara default. + + Deteksi mention mencakup: + + - mention WhatsApp eksplisit dari identitas bot + - pola regex mention yang dikonfigurasi (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) + - deteksi reply-to-bot implisit (pengirim balasan cocok dengan identitas bot) + + Catatan keamanan: + + - kutip/balas hanya memenuhi pembatasan mention; itu **tidak** memberikan otorisasi pengirim + - dengan `groupPolicy: "allowlist"`, pengirim yang tidak ada di allowlist tetap diblokir meskipun mereka membalas pesan pengguna yang ada di allowlist + + Perintah aktivasi tingkat sesi: + + - `/activation mention` + - `/activation always` + + `activation` memperbarui status sesi (bukan config global). Ini dibatasi untuk owner. + + + + +## Perilaku nomor pribadi dan obrolan sendiri + +Saat nomor diri tertaut juga ada di `allowFrom`, perlindungan obrolan sendiri WhatsApp aktif: + +- lewati tanda baca untuk giliran obrolan sendiri +- abaikan perilaku pemicu otomatis mention-JID yang sebaliknya akan meming diri Anda sendiri +- jika `messages.responsePrefix` tidak diatur, balasan obrolan sendiri default ke `[{identity.name}]` atau `[openclaw]` + +## Normalisasi pesan dan konteks + + + + Pesan WhatsApp masuk dibungkus dalam envelope masuk bersama. + + Jika ada balasan kutipan, konteks ditambahkan dalam bentuk ini: + + ```text + [Replying to id:] + + [/Replying] + ``` + + Bidang metadata balasan juga diisi jika tersedia (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164). + + + + + Pesan masuk yang hanya berisi media dinormalisasi dengan placeholder seperti: + + - `` + - `` + - `` + - `` + - `` + + Payload lokasi dan kontak dinormalisasi menjadi konteks tekstual sebelum perutean. + + + + + Untuk grup, pesan yang belum diproses dapat dibuffer dan disisipkan sebagai konteks saat bot akhirnya dipicu. + + - batas default: `50` + - config: `channels.whatsapp.historyLimit` + - fallback: `messages.groupChat.historyLimit` + - `0` menonaktifkan + + Penanda injeksi: + + - `[Chat messages since your last reply - for context]` + - `[Current message - respond to this]` + + + + + Tanda baca diaktifkan secara default untuk pesan WhatsApp masuk yang diterima. + + Nonaktifkan secara global: + + ```json5 + { + channels: { + whatsapp: { + sendReadReceipts: false, + }, + }, + } + ``` + + Override per akun: + + ```json5 + { + channels: { + whatsapp: { + accounts: { + work: { + sendReadReceipts: false, + }, + }, + }, + }, + } + ``` + + Giliran obrolan sendiri melewati tanda baca bahkan saat diaktifkan secara global. + + + + +## Pengiriman, pemotongan, dan media + + + + - batas potongan default: `channels.whatsapp.textChunkLimit = 4000` + - `channels.whatsapp.chunkMode = "length" | "newline"` + - mode `newline` mengutamakan batas paragraf (baris kosong), lalu fallback ke pemotongan aman berdasarkan panjang + + + + - mendukung payload gambar, video, audio (PTT voice-note), dan dokumen + - `audio/ogg` ditulis ulang menjadi `audio/ogg; codecs=opus` untuk kompatibilitas voice-note + - pemutaran GIF animasi didukung melalui `gifPlayback: true` pada pengiriman video + - caption diterapkan pada item media pertama saat mengirim payload balasan multi-media + - sumber media dapat berupa HTTP(S), `file://`, atau path lokal + + + + - batas penyimpanan media masuk: `channels.whatsapp.mediaMaxMb` (default `50`) + - batas pengiriman media keluar: `channels.whatsapp.mediaMaxMb` (default `50`) + - override per akun menggunakan `channels.whatsapp.accounts..mediaMaxMb` + - gambar dioptimalkan otomatis (resize/quality sweep) agar sesuai dengan batas + - saat pengiriman media gagal, fallback item pertama mengirim peringatan teks alih-alih diam-diam membuang respons + + + +## Tingkat reaction + +`channels.whatsapp.reactionLevel` mengontrol seberapa luas agen menggunakan reaction emoji di WhatsApp: + +| Level | Reaction ack | Reaction yang dimulai agen | Deskripsi | +| ------------- | ------------ | -------------------------- | ------------------------------------------------- | +| `"off"` | Tidak | Tidak | Tidak ada reaction sama sekali | +| `"ack"` | Ya | Tidak | Hanya reaction ack (tanda terima pra-balasan) | +| `"minimal"` | Ya | Ya (konservatif) | Ack + reaction agen dengan panduan konservatif | +| `"extensive"` | Ya | Ya (didorong) | Ack + reaction agen dengan panduan yang didorong | + +Default: `"minimal"`. + +Override per akun menggunakan `channels.whatsapp.accounts..reactionLevel`. + +```json5 +{ + channels: { + whatsapp: { + reactionLevel: "ack", + }, + }, +} +``` + +## Reaction acknowledgment + +WhatsApp mendukung reaction ack segera saat penerimaan masuk melalui `channels.whatsapp.ackReaction`. +Reaction ack dibatasi oleh `reactionLevel` — reaction ini ditekan saat `reactionLevel` adalah `"off"`. + +```json5 +{ + channels: { + whatsapp: { + ackReaction: { + emoji: "👀", + direct: true, + group: "mentions", // always | mentions | never + }, + }, + }, +} +``` + +Catatan perilaku: + +- dikirim segera setelah pesan masuk diterima (pra-balasan) +- kegagalan dicatat dalam log tetapi tidak memblokir pengiriman balasan normal +- mode grup `mentions` bereaksi pada giliran yang dipicu mention; aktivasi grup `always` bertindak sebagai bypass untuk pemeriksaan ini +- WhatsApp menggunakan `channels.whatsapp.ackReaction` (`messages.ackReaction` legacy tidak digunakan di sini) + +## Multi-akun dan kredensial + + + + - id akun berasal dari `channels.whatsapp.accounts` + - pemilihan akun default: `default` jika ada, jika tidak id akun pertama yang dikonfigurasi (diurutkan) + - id akun dinormalisasi secara internal untuk lookup + + + + - path autentikasi saat ini: `~/.openclaw/credentials/whatsapp//creds.json` + - file cadangan: `creds.json.bak` + - autentikasi default legacy di `~/.openclaw/credentials/` masih dikenali/dimigrasikan untuk alur akun default + + + + `openclaw channels logout --channel whatsapp [--account ]` menghapus status autentikasi WhatsApp untuk akun tersebut. + + Dalam direktori autentikasi legacy, `oauth.json` dipertahankan sementara file autentikasi Baileys dihapus. + + + + +## Alat, action, dan penulisan config + +- Dukungan alat agen mencakup action reaction WhatsApp (`react`). +- Pembatasan action: + - `channels.whatsapp.actions.reactions` + - `channels.whatsapp.actions.polls` +- Penulisan config yang dimulai channel diaktifkan secara default (nonaktifkan melalui `channels.whatsapp.configWrites=false`). + +## Pemecahan masalah + + + + Gejala: status channel melaporkan belum tertaut. + + Perbaikan: + + ```bash + openclaw channels login --channel whatsapp + openclaw channels status + ``` + + + + + Gejala: akun tertaut dengan disconnect berulang atau upaya reconnect. + + Perbaikan: + + ```bash + openclaw doctor + openclaw logs --follow + ``` + + Jika perlu, tautkan ulang dengan `channels login`. + + + + + Pengiriman keluar gagal cepat saat tidak ada listener gateway aktif untuk akun target. + + Pastikan gateway berjalan dan akun tertaut. + + + + + Periksa dalam urutan ini: + + - `groupPolicy` + - `groupAllowFrom` / `allowFrom` + - entri allowlist `groups` + - pembatasan mention (`requireMention` + pola mention) + - kunci duplikat di `openclaw.json` (JSON5): entri terakhir menggantikan entri sebelumnya, jadi gunakan satu `groupPolicy` per cakupan + + + + + Runtime gateway WhatsApp seharusnya menggunakan Node. Bun ditandai tidak kompatibel untuk operasi gateway WhatsApp/Telegram yang stabil. + + + +## Penunjuk referensi konfigurasi + +Referensi utama: + +- [Referensi konfigurasi - WhatsApp](/gateway/configuration-reference#whatsapp) + +Bidang WhatsApp dengan sinyal tinggi: + +- akses: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups` +- pengiriman: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel` +- multi-akun: `accounts..enabled`, `accounts..authDir`, override tingkat akun +- operasi: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*` +- perilaku sesi: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit` + +## Terkait + +- [Pairing](/channels/pairing) +- [Groups](/channels/groups) +- [Security](/gateway/security) +- [Channel routing](/channels/channel-routing) +- [Multi-agent routing](/concepts/multi-agent) +- [Troubleshooting](/channels/troubleshooting) diff --git a/docs/id/channels/zalo.md b/docs/id/channels/zalo.md new file mode 100644 index 000000000..cbadccf18 --- /dev/null +++ b/docs/id/channels/zalo.md @@ -0,0 +1,261 @@ +--- +read_when: + - Mengerjakan fitur atau webhook Zalo +summary: Status dukungan bot Zalo, kemampuan, dan konfigurasi +title: Zalo +x-i18n: + generated_at: "2026-04-05T13:45:10Z" + model: gpt-5.4 + provider: openai + source_hash: ab94642ba28e79605b67586af8f71c18bc10e0af60343a7df508e6823b6f4119 + source_path: channels/zalo.md + workflow: 15 +--- + +# Zalo (Bot API) + +Status: eksperimental. DM didukung. Bagian [Kemampuan](#capabilities) di bawah mencerminkan perilaku bot Marketplace saat ini. + +## Plugin bawaan + +Zalo tersedia sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build paket +normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Zalo, instal secara +manual: + +- Instal melalui CLI: `openclaw plugins install @openclaw/zalo` +- Atau dari checkout sumber: `openclaw plugins install ./path/to/local/zalo-plugin` +- Detail: [Plugins](/tools/plugin) + +## Penyiapan cepat (pemula) + +1. Pastikan plugin Zalo tersedia. + - Rilis OpenClaw paket saat ini sudah menyertakan plugin ini. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Atur token: + - Env: `ZALO_BOT_TOKEN=...` + - Atau konfigurasi: `channels.zalo.accounts.default.botToken: "..."`. +3. Mulai ulang gateway (atau selesaikan penyiapan). +4. Akses DM secara default menggunakan pairing; setujui kode pairing saat kontak pertama. + +Konfigurasi minimal: + +```json5 +{ + channels: { + zalo: { + enabled: true, + accounts: { + default: { + botToken: "12345689:abc-xyz", + dmPolicy: "pairing", + }, + }, + }, + }, +} +``` + +## Apa itu + +Zalo adalah aplikasi pesan yang berfokus pada Vietnam; Bot API-nya memungkinkan Gateway menjalankan bot untuk percakapan 1:1. +Ini cocok untuk dukungan atau notifikasi saat Anda menginginkan perutean deterministik kembali ke Zalo. + +Halaman ini mencerminkan perilaku OpenClaw saat ini untuk **bot Zalo Bot Creator / Marketplace**. +**Bot Zalo Official Account (OA)** adalah permukaan produk Zalo yang berbeda dan dapat berperilaku berbeda. + +- Channel Zalo Bot API yang dimiliki oleh Gateway. +- Perutean deterministik: balasan kembali ke Zalo; model tidak pernah memilih channel. +- DM berbagi sesi utama agen. +- Bagian [Kemampuan](#capabilities) di bawah menunjukkan dukungan bot Marketplace saat ini. + +## Penyiapan (jalur cepat) + +### 1) Buat token bot (Zalo Bot Platform) + +1. Buka [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) dan masuk. +2. Buat bot baru dan konfigurasikan pengaturannya. +3. Salin token bot lengkap (biasanya `numeric_id:secret`). Untuk bot Marketplace, token runtime yang dapat digunakan mungkin muncul dalam pesan sambutan bot setelah pembuatan. + +### 2) Konfigurasikan token (env atau config) + +Contoh: + +```json5 +{ + channels: { + zalo: { + enabled: true, + accounts: { + default: { + botToken: "12345689:abc-xyz", + dmPolicy: "pairing", + }, + }, + }, + }, +} +``` + +Jika nantinya Anda berpindah ke permukaan bot Zalo tempat grup tersedia, Anda dapat menambahkan konfigurasi khusus grup seperti `groupPolicy` dan `groupAllowFrom` secara eksplisit. Untuk perilaku bot Marketplace saat ini, lihat [Kemampuan](#capabilities). + +Opsi env: `ZALO_BOT_TOKEN=...` (hanya berfungsi untuk akun default). + +Dukungan multi-akun: gunakan `channels.zalo.accounts` dengan token per akun dan `name` opsional. + +3. Mulai ulang gateway. Zalo dimulai saat token berhasil di-resolve (env atau config). +4. Akses DM secara default menggunakan pairing. Setujui kode saat bot pertama kali dihubungi. + +## Cara kerjanya (perilaku) + +- Pesan masuk dinormalisasi ke envelope channel bersama dengan placeholder media. +- Balasan selalu dirutekan kembali ke chat Zalo yang sama. +- Long-polling secara default; mode webhook tersedia dengan `channels.zalo.webhookUrl`. + +## Batasan + +- Teks keluar dipotong menjadi 2000 karakter (batas API Zalo). +- Unduhan/unggahan media dibatasi oleh `channels.zalo.mediaMaxMb` (default 5). +- Streaming diblokir secara default karena batas 2000 karakter membuat streaming kurang berguna. + +## Kontrol akses (DM) + +### Akses DM + +- Default: `channels.zalo.dmPolicy = "pairing"`. Pengirim yang tidak dikenal menerima kode pairing; pesan diabaikan sampai disetujui (kode kedaluwarsa setelah 1 jam). +- Setujui melalui: + - `openclaw pairing list zalo` + - `openclaw pairing approve zalo ` +- Pairing adalah pertukaran token default. Detail: [Pairing](/channels/pairing) +- `channels.zalo.allowFrom` menerima ID pengguna numerik (tidak ada pencarian username yang tersedia). + +## Kontrol akses (Grup) + +Untuk **bot Zalo Bot Creator / Marketplace**, dukungan grup secara praktik tidak tersedia karena bot sama sekali tidak dapat ditambahkan ke grup. + +Artinya key konfigurasi terkait grup di bawah ini ada dalam schema, tetapi tidak dapat digunakan untuk bot Marketplace: + +- `channels.zalo.groupPolicy` mengontrol penanganan masuk grup: `open | allowlist | disabled`. +- `channels.zalo.groupAllowFrom` membatasi ID pengirim mana yang dapat memicu bot di grup. +- Jika `groupAllowFrom` tidak diatur, Zalo menggunakan fallback ke `allowFrom` untuk pemeriksaan pengirim. +- Catatan runtime: jika `channels.zalo` sama sekali tidak ada, runtime tetap menggunakan fallback ke `groupPolicy="allowlist"` demi keamanan. + +Nilai kebijakan grup (saat akses grup tersedia pada permukaan bot Anda) adalah: + +- `groupPolicy: "disabled"` — memblokir semua pesan grup. +- `groupPolicy: "open"` — mengizinkan anggota grup mana pun (dibatasi mention). +- `groupPolicy: "allowlist"` — default fail-closed; hanya pengirim yang diizinkan yang diterima. + +Jika Anda menggunakan permukaan produk bot Zalo yang berbeda dan telah memverifikasi perilaku grup yang berfungsi, dokumentasikan itu secara terpisah daripada mengasumsikan bahwa perilakunya sama dengan alur bot Marketplace. + +## Long-polling vs webhook + +- Default: long-polling (tidak memerlukan URL publik). +- Mode webhook: atur `channels.zalo.webhookUrl` dan `channels.zalo.webhookSecret`. + - Rahasia webhook harus 8-256 karakter. + - URL webhook harus menggunakan HTTPS. + - Zalo mengirim peristiwa dengan header `X-Bot-Api-Secret-Token` untuk verifikasi. + - HTTP Gateway menangani permintaan webhook di `channels.zalo.webhookPath` (default ke path URL webhook). + - Permintaan harus menggunakan `Content-Type: application/json` (atau tipe media `+json`). + - Peristiwa duplikat (`event_name + message_id`) diabaikan selama jendela replay singkat. + - Lonjakan trafik dibatasi lajunya per path/sumber dan dapat mengembalikan HTTP 429. + +**Catatan:** getUpdates (polling) dan webhook saling eksklusif menurut dokumentasi API Zalo. + +## Jenis pesan yang didukung + +Untuk ringkasan dukungan cepat, lihat [Kemampuan](#capabilities). Catatan di bawah menambahkan detail saat perilaku memerlukan konteks tambahan. + +- **Pesan teks**: Dukungan penuh dengan pemotongan 2000 karakter. +- **URL polos dalam teks**: Berperilaku seperti input teks normal. +- **Pratinjau tautan / kartu tautan rich**: Lihat status bot Marketplace di [Kemampuan](#capabilities); fitur ini tidak secara andal memicu balasan. +- **Pesan gambar**: Lihat status bot Marketplace di [Kemampuan](#capabilities); penanganan gambar masuk tidak andal (indikator mengetik tanpa balasan akhir). +- **Stiker**: Lihat status bot Marketplace di [Kemampuan](#capabilities). +- **Catatan suara / file audio / video / lampiran file umum**: Lihat status bot Marketplace di [Kemampuan](#capabilities). +- **Jenis yang tidak didukung**: Dicatat di log (misalnya, pesan dari pengguna yang dilindungi). + +## Kemampuan + +Tabel ini merangkum perilaku OpenClaw saat ini untuk **bot Zalo Bot Creator / Marketplace**. + +| Fitur | Status | +| --------------------------- | --------------------------------------- | +| Pesan langsung | ✅ Didukung | +| Grup | ❌ Tidak tersedia untuk bot Marketplace | +| Media (gambar masuk) | ⚠️ Terbatas / verifikasi di lingkungan Anda | +| Media (gambar keluar) | ⚠️ Belum diuji ulang untuk bot Marketplace | +| URL polos dalam teks | ✅ Didukung | +| Pratinjau tautan | ⚠️ Tidak andal untuk bot Marketplace | +| Reaksi | ❌ Tidak didukung | +| Stiker | ⚠️ Tidak ada balasan agen untuk bot Marketplace | +| Catatan suara / audio / video | ⚠️ Tidak ada balasan agen untuk bot Marketplace | +| Lampiran file | ⚠️ Tidak ada balasan agen untuk bot Marketplace | +| Thread | ❌ Tidak didukung | +| Polling | ❌ Tidak didukung | +| Perintah native | ❌ Tidak didukung | +| Streaming | ⚠️ Diblokir (batas 2000 karakter) | + +## Target pengiriman (CLI/cron) + +- Gunakan chat id sebagai target. +- Contoh: `openclaw message send --channel zalo --target 123456789 --message "hi"`. + +## Pemecahan masalah + +**Bot tidak merespons:** + +- Periksa apakah token valid: `openclaw channels status --probe` +- Pastikan pengirim telah disetujui (pairing atau allowFrom) +- Periksa log gateway: `openclaw logs --follow` + +**Webhook tidak menerima peristiwa:** + +- Pastikan URL webhook menggunakan HTTPS +- Pastikan token rahasia 8-256 karakter +- Konfirmasikan endpoint HTTP gateway dapat dijangkau pada path yang dikonfigurasi +- Periksa bahwa polling getUpdates tidak sedang berjalan (keduanya saling eksklusif) + +## Referensi konfigurasi (Zalo) + +Konfigurasi lengkap: [Konfigurasi](/gateway/configuration) + +Key datar tingkat atas (`channels.zalo.botToken`, `channels.zalo.dmPolicy`, dan yang serupa) adalah singkatan lama untuk akun tunggal. Gunakan `channels.zalo.accounts..*` untuk konfigurasi baru. Kedua bentuk masih didokumentasikan di sini karena keduanya ada dalam schema. + +Opsi provider: + +- `channels.zalo.enabled`: aktifkan/nonaktifkan startup channel. +- `channels.zalo.botToken`: token bot dari Zalo Bot Platform. +- `channels.zalo.tokenFile`: baca token dari path file reguler. Symlink ditolak. +- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing). +- `channels.zalo.allowFrom`: allowlist DM (ID pengguna). `open` mengharuskan `"*"`. Wizard akan meminta ID numerik. +- `channels.zalo.groupPolicy`: `open | allowlist | disabled` (default: allowlist). Ada dalam config; lihat [Kemampuan](#capabilities) dan [Kontrol akses (Grup)](#access-control-groups) untuk perilaku bot Marketplace saat ini. +- `channels.zalo.groupAllowFrom`: allowlist pengirim grup (ID pengguna). Menggunakan fallback ke `allowFrom` saat tidak diatur. +- `channels.zalo.mediaMaxMb`: batas media masuk/keluar (MB, default 5). +- `channels.zalo.webhookUrl`: aktifkan mode webhook (HTTPS wajib). +- `channels.zalo.webhookSecret`: rahasia webhook (8-256 karakter). +- `channels.zalo.webhookPath`: path webhook pada server HTTP gateway. +- `channels.zalo.proxy`: URL proxy untuk permintaan API. + +Opsi multi-akun: + +- `channels.zalo.accounts..botToken`: token per akun. +- `channels.zalo.accounts..tokenFile`: file token reguler per akun. Symlink ditolak. +- `channels.zalo.accounts..name`: nama tampilan. +- `channels.zalo.accounts..enabled`: aktifkan/nonaktifkan akun. +- `channels.zalo.accounts..dmPolicy`: kebijakan DM per akun. +- `channels.zalo.accounts..allowFrom`: allowlist per akun. +- `channels.zalo.accounts..groupPolicy`: kebijakan grup per akun. Ada dalam config; lihat [Kemampuan](#capabilities) dan [Kontrol akses (Grup)](#access-control-groups) untuk perilaku bot Marketplace saat ini. +- `channels.zalo.accounts..groupAllowFrom`: allowlist pengirim grup per akun. +- `channels.zalo.accounts..webhookUrl`: URL webhook per akun. +- `channels.zalo.accounts..webhookSecret`: rahasia webhook per akun. +- `channels.zalo.accounts..webhookPath`: path webhook per akun. +- `channels.zalo.accounts..proxy`: URL proxy per akun. + +## Terkait + +- [Ikhtisar Channel](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Grup](/channels/groups) — perilaku chat grup dan penyaringan mention +- [Perutean Channel](/channels/channel-routing) — perutean sesi untuk pesan +- [Keamanan](/gateway/security) — model akses dan hardening diff --git a/docs/id/channels/zalouser.md b/docs/id/channels/zalouser.md new file mode 100644 index 000000000..4c66fefbf --- /dev/null +++ b/docs/id/channels/zalouser.md @@ -0,0 +1,202 @@ +--- +read_when: + - Menyiapkan Zalo Personal untuk OpenClaw + - Men-debug login atau alur pesan Zalo Personal +summary: Dukungan akun pribadi Zalo melalui zca-js native (login QR), capability, dan konfigurasi +title: Zalo Personal +x-i18n: + generated_at: "2026-04-05T13:45:09Z" + model: gpt-5.4 + provider: openai + source_hash: 331b95041463185472d242cb0a944972f0a8e99df8120bda6350eca86ad5963f + source_path: channels/zalouser.md + workflow: 15 +--- + +# Zalo Personal (tidak resmi) + +Status: eksperimental. Integrasi ini mengotomatisasi **akun pribadi Zalo** melalui `zca-js` native di dalam OpenClaw. + +> **Peringatan:** Ini adalah integrasi tidak resmi dan dapat mengakibatkan akun ditangguhkan/diblokir. Gunakan dengan risiko Anda sendiri. + +## Plugin bawaan + +Zalo Personal dikirim sebagai plugin bawaan dalam rilis OpenClaw saat ini, jadi build +paket normal tidak memerlukan instalasi terpisah. + +Jika Anda menggunakan build lama atau instalasi kustom yang tidak menyertakan Zalo Personal, +instal secara manual: + +- Instal melalui CLI: `openclaw plugins install @openclaw/zalouser` +- Atau dari source checkout: `openclaw plugins install ./path/to/local/zalouser-plugin` +- Detail: [Plugins](/tools/plugin) + +Tidak diperlukan binary CLI `zca`/`openzca` eksternal. + +## Penyiapan cepat (pemula) + +1. Pastikan plugin Zalo Personal tersedia. + - Rilis OpenClaw terpaket saat ini sudah menyertakannya. + - Instalasi lama/kustom dapat menambahkannya secara manual dengan perintah di atas. +2. Login (QR, di mesin Gateway): + - `openclaw channels login --channel zalouser` + - Pindai kode QR dengan aplikasi seluler Zalo. +3. Aktifkan channel: + +```json5 +{ + channels: { + zalouser: { + enabled: true, + dmPolicy: "pairing", + }, + }, +} +``` + +4. Restart Gateway (atau selesaikan penyiapan). +5. Akses DM secara default menggunakan pairing; setujui kode pairing saat kontak pertama. + +## Apa itu + +- Berjalan sepenuhnya in-process melalui `zca-js`. +- Menggunakan event listener native untuk menerima pesan masuk. +- Mengirim balasan langsung melalui JS API (teks/media/tautan). +- Dirancang untuk kasus penggunaan “akun pribadi” saat Zalo Bot API tidak tersedia. + +## Penamaan + +ID channel adalah `zalouser` untuk menegaskan bahwa ini mengotomatisasi **akun pengguna pribadi Zalo** (tidak resmi). Kami mempertahankan `zalo` untuk potensi integrasi resmi Zalo API di masa depan. + +## Menemukan ID (direktori) + +Gunakan CLI direktori untuk menemukan peer/grup dan ID-nya: + +```bash +openclaw directory self --channel zalouser +openclaw directory peers list --channel zalouser --query "name" +openclaw directory groups list --channel zalouser --query "work" +``` + +## Batasan + +- Teks keluar dipecah menjadi ~2000 karakter (batas klien Zalo). +- Streaming diblokir secara default. + +## Kontrol akses (DM) + +`channels.zalouser.dmPolicy` mendukung: `pairing | allowlist | open | disabled` (default: `pairing`). + +`channels.zalouser.allowFrom` menerima ID pengguna atau nama. Saat penyiapan, nama di-resolve menjadi ID menggunakan lookup kontak in-process milik plugin. + +Setujui melalui: + +- `openclaw pairing list zalouser` +- `openclaw pairing approve zalouser ` + +## Akses grup (opsional) + +- Default: `channels.zalouser.groupPolicy = "open"` (grup diizinkan). Gunakan `channels.defaults.groupPolicy` untuk menimpa default saat tidak disetel. +- Batasi ke allowlist dengan: + - `channels.zalouser.groupPolicy = "allowlist"` + - `channels.zalouser.groups` (kunci sebaiknya berupa ID grup stabil; nama di-resolve menjadi ID saat startup jika memungkinkan) + - `channels.zalouser.groupAllowFrom` (mengontrol pengirim mana di grup yang diizinkan yang dapat memicu bot) +- Blokir semua grup: `channels.zalouser.groupPolicy = "disabled"`. +- Wizard konfigurasi dapat meminta allowlist grup. +- Saat startup, OpenClaw me-resolve nama grup/pengguna dalam allowlist menjadi ID dan mencatat pemetaannya. +- Pencocokan allowlist grup secara default hanya berdasarkan ID. Nama yang tidak ter-resolve diabaikan untuk autentikasi kecuali `channels.zalouser.dangerouslyAllowNameMatching: true` diaktifkan. +- `channels.zalouser.dangerouslyAllowNameMatching: true` adalah mode kompatibilitas break-glass yang mengaktifkan kembali pencocokan nama grup yang dapat berubah. +- Jika `groupAllowFrom` tidak disetel, runtime akan fallback ke `allowFrom` untuk pemeriksaan pengirim grup. +- Pemeriksaan pengirim berlaku untuk pesan grup normal maupun perintah kontrol (misalnya `/new`, `/reset`). + +Contoh: + +```json5 +{ + channels: { + zalouser: { + groupPolicy: "allowlist", + groupAllowFrom: ["1471383327500481391"], + groups: { + "123456789": { allow: true }, + "Work Chat": { allow: true }, + }, + }, + }, +} +``` + +### Pembatasan mention grup + +- `channels.zalouser.groups..requireMention` mengontrol apakah balasan grup memerlukan mention. +- Urutan resolusi: ID/nama grup persis -> slug grup ternormalisasi -> `*` -> default (`true`). +- Ini berlaku baik untuk grup yang di-allowlist maupun mode grup terbuka. +- Perintah kontrol yang diotorisasi (misalnya `/new`) dapat mem-bypass pembatasan mention. +- Saat pesan grup dilewati karena mention diperlukan, OpenClaw menyimpannya sebagai riwayat grup tertunda dan menyertakannya pada pesan grup berikutnya yang diproses. +- Batas riwayat grup secara default adalah `messages.groupChat.historyLimit` (fallback `50`). Anda dapat menimpanya per akun dengan `channels.zalouser.historyLimit`. + +Contoh: + +```json5 +{ + channels: { + zalouser: { + groupPolicy: "allowlist", + groups: { + "*": { allow: true, requireMention: true }, + "Work Chat": { allow: true, requireMention: false }, + }, + }, + }, +} +``` + +## Multi-akun + +Akun dipetakan ke profil `zalouser` dalam status OpenClaw. Contoh: + +```json5 +{ + channels: { + zalouser: { + enabled: true, + defaultAccount: "default", + accounts: { + work: { enabled: true, profile: "work" }, + }, + }, + }, +} +``` + +## Typing, reaksi, dan pengakuan pengiriman + +- OpenClaw mengirim event typing sebelum mengirim balasan (best-effort). +- Tindakan reaksi pesan `react` didukung untuk `zalouser` dalam tindakan channel. + - Gunakan `remove: true` untuk menghapus emoji reaksi tertentu dari pesan. + - Semantik reaksi: [Reactions](/tools/reactions) +- Untuk pesan masuk yang menyertakan metadata event, OpenClaw mengirim pengakuan delivered + seen (best-effort). + +## Pemecahan masalah + +**Login tidak tersimpan:** + +- `openclaw channels status --probe` +- Login ulang: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser` + +**Allowlist/nama grup tidak ter-resolve:** + +- Gunakan ID numerik di `allowFrom`/`groupAllowFrom`/`groups`, atau nama teman/grup yang persis. + +**Upgrade dari penyiapan lama berbasis CLI:** + +- Hapus asumsi proses `zca` eksternal lama. +- Channel sekarang berjalan sepenuhnya di OpenClaw tanpa binary CLI eksternal. + +## Terkait + +- [Ikhtisar Channels](/channels) — semua channel yang didukung +- [Pairing](/channels/pairing) — autentikasi DM dan alur pairing +- [Groups](/channels/groups) — perilaku obrolan grup dan pembatasan mention +- [Channel Routing](/channels/channel-routing) — routing sesi untuk pesan +- [Security](/gateway/security) — model akses dan hardening diff --git a/docs/id/ci.md b/docs/id/ci.md new file mode 100644 index 000000000..9efdda655 --- /dev/null +++ b/docs/id/ci.md @@ -0,0 +1,73 @@ +--- +read_when: + - Anda perlu memahami mengapa suatu job CI berjalan atau tidak berjalan + - Anda sedang men-debug pemeriksaan GitHub Actions yang gagal +summary: Graf job CI, gate scope, dan padanan perintah lokal +title: Pipeline CI +x-i18n: + generated_at: "2026-04-05T13:44:58Z" + model: gpt-5.4 + provider: openai + source_hash: 5a95b6e584b4309bc249866ea436b4dfe30e0298ab8916eadbc344edae3d1194 + source_path: ci.md + workflow: 15 +--- + +# Pipeline CI + +CI berjalan pada setiap push ke `main` dan setiap pull request. Ini menggunakan scoping cerdas untuk melewati job mahal ketika hanya area yang tidak terkait yang berubah. + +## Ikhtisar Job + +| Job | Tujuan | Kapan dijalankan | +| ------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- | +| `preflight` | Mendeteksi perubahan khusus docs, scope yang berubah, extension yang berubah, dan membangun manifest CI | Selalu pada push dan PR non-draft | +| `security-fast` | Deteksi private key, audit workflow melalui `zizmor`, audit dependensi produksi | Selalu pada push dan PR non-draft | +| `build-artifacts` | Membangun `dist/` dan UI Control sekali, mengunggah artifact yang dapat digunakan ulang untuk job downstream | Perubahan yang relevan dengan Node | +| `checks-fast-core` | Lane korektness Linux cepat seperti pemeriksaan bundled/plugin-contract/protocol | Perubahan yang relevan dengan Node | +| `checks-fast-extensions` | Mengagregasi lane shard extension setelah `checks-fast-extensions-shard` selesai | Perubahan yang relevan dengan Node | +| `extension-fast` | Pengujian terfokus hanya untuk bundled plugin yang berubah | Saat perubahan extension terdeteksi | +| `check` | Gate lokal utama di CI: `pnpm check` plus `pnpm build:strict-smoke` | Perubahan yang relevan dengan Node | +| `check-additional` | Guard arsitektur dan boundary plus harness regresi gateway watch | Perubahan yang relevan dengan Node | +| `build-smoke` | Pengujian smoke CLI hasil build dan smoke memori saat startup | Perubahan yang relevan dengan Node | +| `checks` | Lane Node Linux yang lebih berat: pengujian penuh, pengujian channel, dan kompatibilitas Node 22 khusus push | Perubahan yang relevan dengan Node | +| `check-docs` | Pemeriksaan format docs, lint, dan tautan rusak | Docs berubah | +| `skills-python` | Ruff + pytest untuk Skills berbasis Python | Perubahan yang relevan dengan Skills Python | +| `checks-windows` | Lane pengujian khusus Windows | Perubahan yang relevan dengan Windows | +| `macos-node` | Lane pengujian TypeScript macOS menggunakan artifact build bersama | Perubahan yang relevan dengan macOS | +| `macos-swift` | Lint, build, dan pengujian Swift untuk aplikasi macOS | Perubahan yang relevan dengan macOS | +| `android` | Matriks build dan pengujian Android | Perubahan yang relevan dengan Android | + +## Urutan Fail-Fast + +Job diurutkan sehingga pemeriksaan murah gagal sebelum job mahal berjalan: + +1. `preflight` menentukan lane mana yang ada sama sekali. Logika `docs-scope` dan `changed-scope` adalah step di dalam job ini, bukan job terpisah. +2. `security-fast`, `check`, `check-additional`, `check-docs`, dan `skills-python` gagal cepat tanpa menunggu artifact yang lebih berat dan job matriks platform. +3. `build-artifacts` berjalan tumpang tindih dengan lane Linux cepat sehingga konsumen downstream dapat mulai segera setelah build bersama siap. +4. Setelah itu, lane platform dan runtime yang lebih berat menyebar: `checks-fast-core`, `checks-fast-extensions`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift`, dan `android`. + +Logika scope berada di `scripts/ci-changed-scope.mjs` dan dicakup oleh unit test di `src/scripts/ci-changed-scope.test.ts`. +Workflow `install-smoke` yang terpisah menggunakan ulang skrip scope yang sama melalui job `preflight` miliknya sendiri. Workflow ini menghitung `run_install_smoke` dari sinyal changed-smoke yang lebih sempit, sehingga smoke Docker/install hanya berjalan untuk perubahan yang relevan dengan install, packaging, dan container. + +Pada push, matriks `checks` menambahkan lane `compat-node22` khusus push. Pada pull request, lane tersebut dilewati dan matriks tetap fokus pada lane pengujian/channel normal. + +## Runner + +| Runner | Job | +| -------------------------------- | ---------------------------------------------------------------------------------------------------- | +| `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-fast`, `build-artifacts`, pemeriksaan Linux, pemeriksaan docs, Skills Python, `android` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `macos-latest` | `macos-node`, `macos-swift` | + +## Padanan Lokal + +```bash +pnpm check # types + lint + format +pnpm build:strict-smoke +pnpm test:gateway:watch-regression +pnpm test # vitest tests +pnpm test:channels +pnpm check:docs # docs format + lint + broken links +pnpm build # build dist when CI artifact/build-smoke lanes matter +``` diff --git a/docs/id/cli/acp.md b/docs/id/cli/acp.md new file mode 100644 index 000000000..04900610f --- /dev/null +++ b/docs/id/cli/acp.md @@ -0,0 +1,293 @@ +--- +read_when: + - Menyiapkan integrasi IDE berbasis ACP + - Men-debug perutean sesi ACP ke Gateway +summary: Jalankan bridge ACP untuk integrasi IDE +title: acp +x-i18n: + generated_at: "2026-04-05T13:45:37Z" + model: gpt-5.4 + provider: openai + source_hash: 2461b181e4a97dd84580581e9436ca1947a224decce8044132dbcf7fb2b7502c + source_path: cli/acp.md + workflow: 15 +--- + +# acp + +Jalankan bridge [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) yang berbicara dengan OpenClaw Gateway. + +Perintah ini berbicara ACP melalui stdio untuk IDE dan meneruskan prompt ke Gateway melalui WebSocket. Perintah ini menjaga sesi ACP tetap dipetakan ke kunci sesi Gateway. + +`openclaw acp` adalah bridge ACP yang didukung Gateway, bukan runtime editor native ACP penuh. Fokusnya adalah perutean sesi, pengiriman prompt, dan pembaruan streaming dasar. + +Jika Anda ingin klien MCP eksternal berbicara langsung dengan percakapan channel OpenClaw alih-alih meng-host sesi harness ACP, gunakan +[`openclaw mcp serve`](/cli/mcp). + +## Ini bukan apa + +Halaman ini sering disalahartikan sebagai sesi harness ACP. + +`openclaw acp` berarti: + +- OpenClaw bertindak sebagai server ACP +- IDE atau klien ACP terhubung ke OpenClaw +- OpenClaw meneruskan pekerjaan itu ke sesi Gateway + +Ini berbeda dari [ACP Agents](/tools/acp-agents), di mana OpenClaw menjalankan harness eksternal seperti Codex atau Claude Code melalui `acpx`. + +Aturan cepat: + +- editor/klien ingin berbicara ACP ke OpenClaw: gunakan `openclaw acp` +- OpenClaw harus meluncurkan Codex/Claude/Gemini sebagai harness ACP: gunakan `/acp spawn` dan [ACP Agents](/tools/acp-agents) + +## Matriks Kompatibilitas + +| Area ACP | Status | Catatan | +| --------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `initialize`, `newSession`, `prompt`, `cancel` | Diimplementasikan | Alur bridge inti melalui stdio ke chat/send Gateway + abort. | +| `listSessions`, slash commands | Diimplementasikan | Daftar sesi bekerja terhadap status sesi Gateway; perintah diiklankan melalui `available_commands_update`. | +| `loadSession` | Parsial | Mengikat ulang sesi ACP ke kunci sesi Gateway dan memutar ulang riwayat teks pengguna/asisten yang tersimpan. Riwayat tool/sistem belum direkonstruksi. | +| Konten prompt (`text`, `resource` tersemat, gambar) | Parsial | Teks/resource diratakan ke input chat; gambar menjadi lampiran Gateway. | +| Mode sesi | Parsial | `session/set_mode` didukung dan bridge mengekspos kontrol sesi awal yang didukung Gateway untuk tingkat pemikiran, verbositas tool, penalaran, detail penggunaan, dan elevated actions. Surface mode/config native ACP yang lebih luas masih di luar cakupan. | +| Info sesi dan pembaruan penggunaan | Parsial | Bridge memancarkan notifikasi `session_info_update` dan `usage_update` best-effort dari snapshot sesi Gateway yang di-cache. Penggunaan bersifat perkiraan dan hanya dikirim saat total token Gateway ditandai fresh. | +| Streaming tool | Parsial | Event `tool_call` / `tool_call_update` mencakup I/O mentah, konten teks, dan lokasi file best-effort saat argumen/hasil tool Gateway mengeksposnya. Terminal tersemat dan output native diff yang lebih kaya masih belum diekspos. | +| Server MCP per sesi (`mcpServers`) | Tidak didukung | Mode bridge menolak permintaan server MCP per sesi. Konfigurasikan MCP di gateway atau agen OpenClaw. | +| Metode filesystem klien (`fs/read_text_file`, `fs/write_text_file`) | Tidak didukung | Bridge tidak memanggil metode filesystem klien ACP. | +| Metode terminal klien (`terminal/*`) | Tidak didukung | Bridge tidak membuat terminal klien ACP atau men-stream id terminal melalui pemanggilan tool. | +| Rencana sesi / streaming pemikiran | Tidak didukung | Bridge saat ini memancarkan teks output dan status tool, bukan pembaruan rencana atau pemikiran ACP. | + +## Keterbatasan yang Diketahui + +- `loadSession` memutar ulang riwayat teks pengguna dan asisten yang tersimpan, tetapi tidak merekonstruksi pemanggilan tool historis, pemberitahuan sistem, atau jenis event native ACP yang lebih kaya. +- Jika beberapa klien ACP berbagi kunci sesi Gateway yang sama, perutean event dan cancel bersifat best-effort, bukan benar-benar terisolasi per klien. Gunakan sesi `acp:` terisolasi default saat Anda memerlukan giliran lokal editor yang bersih. +- Status berhenti Gateway diterjemahkan ke alasan berhenti ACP, tetapi pemetaan itu kurang ekspresif dibanding runtime native ACP penuh. +- Kontrol sesi awal saat ini hanya mengekspos subset terfokus dari knob Gateway: tingkat pemikiran, verbositas tool, penalaran, detail penggunaan, dan elevated actions. Pemilihan model serta kontrol exec-host belum diekspos sebagai opsi config ACP. +- `session_info_update` dan `usage_update` diturunkan dari snapshot sesi Gateway, bukan akuntansi runtime native ACP langsung. Penggunaan bersifat perkiraan, tidak membawa data biaya, dan hanya dipancarkan saat Gateway menandai data total token sebagai fresh. +- Data follow-along tool bersifat best-effort. Bridge dapat menampilkan jalur file yang muncul dalam argumen/hasil tool yang dikenal, tetapi belum memancarkan terminal ACP atau diff file terstruktur. + +## Penggunaan + +```bash +openclaw acp + +# Gateway jarak jauh +openclaw acp --url wss://gateway-host:18789 --token + +# Gateway jarak jauh (token dari file) +openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token + +# Lampirkan ke kunci sesi yang sudah ada +openclaw acp --session agent:main:main + +# Lampirkan berdasarkan label (harus sudah ada) +openclaw acp --session-label "support inbox" + +# Reset kunci sesi sebelum prompt pertama +openclaw acp --session agent:main:main --reset-session +``` + +## Klien ACP (debug) + +Gunakan klien ACP bawaan untuk sanity-check bridge tanpa IDE. +Perintah ini menjalankan bridge ACP dan memungkinkan Anda mengetik prompt secara interaktif. + +```bash +openclaw acp client + +# Arahkan bridge yang dijalankan ke Gateway jarak jauh +openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token + +# Override perintah server (default: openclaw) +openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001 +``` + +Model izin (mode debug klien): + +- Persetujuan otomatis berbasis allowlist dan hanya berlaku untuk ID tool inti tepercaya. +- Persetujuan otomatis `read` dibatasi ke direktori kerja saat ini (`--cwd` jika disetel). +- ACP hanya menyetujui otomatis kelas readonly yang sempit: pemanggilan `read` yang dibatasi di bawah cwd aktif plus tool pencarian readonly (`search`, `web_search`, `memory_search`). Tool yang tidak dikenal/non-inti, pembacaan di luar cakupan, tool yang mampu exec, tool control-plane, tool yang memodifikasi, dan alur interaktif selalu memerlukan persetujuan prompt eksplisit. +- `toolCall.kind` yang disediakan server diperlakukan sebagai metadata yang tidak tepercaya (bukan sumber otorisasi). +- Kebijakan bridge ACP ini terpisah dari izin harness ACPX. Jika Anda menjalankan OpenClaw melalui backend `acpx`, `plugins.entries.acpx.config.permissionMode=approve-all` adalah sakelar break-glass “yolo” untuk sesi harness tersebut. + +## Cara menggunakan ini + +Gunakan ACP saat IDE (atau klien lain) berbicara Agent Client Protocol dan Anda ingin IDE itu mengendalikan sesi OpenClaw Gateway. + +1. Pastikan Gateway sedang berjalan (lokal atau jarak jauh). +2. Konfigurasikan target Gateway (config atau flag). +3. Arahkan IDE Anda untuk menjalankan `openclaw acp` melalui stdio. + +Contoh config (persisten): + +```bash +openclaw config set gateway.remote.url wss://gateway-host:18789 +openclaw config set gateway.remote.token +``` + +Contoh menjalankan langsung (tanpa menulis config): + +```bash +openclaw acp --url wss://gateway-host:18789 --token +# disarankan untuk keamanan proses lokal +openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token +``` + +## Memilih agen + +ACP tidak memilih agen secara langsung. ACP merutekan berdasarkan kunci sesi Gateway. + +Gunakan kunci sesi yang dicakup agen untuk menargetkan agen tertentu: + +```bash +openclaw acp --session agent:main:main +openclaw acp --session agent:design:main +openclaw acp --session agent:qa:bug-123 +``` + +Setiap sesi ACP dipetakan ke satu kunci sesi Gateway. Satu agen dapat memiliki banyak sesi; ACP default ke sesi `acp:` terisolasi kecuali Anda menimpa kunci atau labelnya. + +`mcpServers` per sesi tidak didukung dalam mode bridge. Jika klien ACP mengirimkannya selama `newSession` atau `loadSession`, bridge akan mengembalikan error yang jelas alih-alih mengabaikannya secara diam-diam. + +Jika Anda ingin sesi yang didukung ACPX melihat plugin tools OpenClaw, aktifkan bridge plugin ACPX di sisi gateway alih-alih mencoba meneruskan `mcpServers` per sesi. Lihat [ACP Agents](/tools/acp-agents#plugin-tools-mcp-bridge). + +## Gunakan dari `acpx` (Codex, Claude, klien ACP lainnya) + +Jika Anda ingin agen coding seperti Codex atau Claude Code berbicara dengan bot OpenClaw Anda melalui ACP, gunakan `acpx` dengan target `openclaw` bawaannya. + +Alur umum: + +1. Jalankan Gateway dan pastikan bridge ACP dapat menjangkaunya. +2. Arahkan `acpx openclaw` ke `openclaw acp`. +3. Targetkan kunci sesi OpenClaw yang ingin digunakan agen coding tersebut. + +Contoh: + +```bash +# Permintaan sekali jalan ke sesi ACP OpenClaw default Anda +acpx openclaw exec "Ringkas status sesi OpenClaw aktif." + +# Sesi bernama persisten untuk giliran lanjutan +acpx openclaw sessions ensure --name codex-bridge +acpx openclaw -s codex-bridge --cwd /path/to/repo \ + "Tanyakan ke agen kerja OpenClaw saya konteks terbaru yang relevan untuk repo ini." +``` + +Jika Anda ingin `acpx openclaw` selalu menargetkan Gateway dan kunci sesi tertentu, timpa perintah agen `openclaw` di `~/.acpx/config.json`: + +```json +{ + "agents": { + "openclaw": { + "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main" + } + } +} +``` + +Untuk checkout OpenClaw lokal berbasis repo, gunakan entrypoint CLI langsung alih-alih dev runner agar stream ACP tetap bersih. Contohnya: + +```bash +env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ... +``` + +Ini adalah cara termudah untuk membiarkan Codex, Claude Code, atau klien lain yang mendukung ACP menarik informasi kontekstual dari agen OpenClaw tanpa mengikis terminal. + +## Setup editor Zed + +Tambahkan agen ACP kustom di `~/.config/zed/settings.json` (atau gunakan UI Settings Zed): + +```json +{ + "agent_servers": { + "OpenClaw ACP": { + "type": "custom", + "command": "openclaw", + "args": ["acp"], + "env": {} + } + } +} +``` + +Untuk menargetkan Gateway atau agen tertentu: + +```json +{ + "agent_servers": { + "OpenClaw ACP": { + "type": "custom", + "command": "openclaw", + "args": [ + "acp", + "--url", + "wss://gateway-host:18789", + "--token", + "", + "--session", + "agent:design:main" + ], + "env": {} + } + } +} +``` + +Di Zed, buka panel Agent dan pilih “OpenClaw ACP” untuk memulai thread. + +## Pemetaan sesi + +Secara default, sesi ACP mendapatkan kunci sesi Gateway terisolasi dengan prefiks `acp:`. +Untuk menggunakan ulang sesi yang diketahui, berikan kunci sesi atau label: + +- `--session `: gunakan kunci sesi Gateway tertentu. +- `--session-label