vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 08:10:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: audit and fix 5 pages (sentence-case headings + Related/title)

Browse Source
This commit is contained in:
Vincent Koc
2026-05-05 21:47:24 -07:00
parent 6da5eda488
commit 963073088d
5 changed files with 45 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/concepts/mantis.md
View File

@@ -33,7 +33,7 @@ browser UI where humans can visually confirm what the transport showed.
- Post concise status to an operator Discord channel when the run is blocked,
needs manual VNC help, or finishes.
## Non Goals
## Non goals
- Mantis is not a replacement for unit tests. A Mantis run should usually become
a smaller regression test after the fix is understood.
@@ -62,7 +62,7 @@ Mantis lives in the OpenClaw QA stack.
This boundary keeps transport knowledge in OpenClaw, machine scheduling in
Crabbox, and maintainer workflow glue in ClawSweeper.
## Command Shape
## Command shape
The first local command verifies the Discord bot, guild, channel, message send,
reaction send, and artifact path:
@@ -317,7 +317,7 @@ The first command is explicit and scenario-focused. The second can later map a P
or issue to recommended Mantis scenarios from labels, changed files, and
ClawSweeper review findings.
## Run Lifecycle
## Run lifecycle
1. Acquire credentials.
2. Allocate or reuse a VM.
@@ -412,7 +412,7 @@ polls the real Discord triggering message and expects the observed sequence
`discord-status-reactions-tool-only-timeline.html`, and
`discord-status-reactions-tool-only-timeline.png`.
## Existing QA Pieces
## Existing QA pieces
Mantis should build on the existing private QA stack instead of starting from
zero:
@@ -430,7 +430,7 @@ zero:
The first Mantis implementation can be a thin before/after runner over these
pieces, plus one visual evidence layer.
## Evidence Model
## Evidence model
Every run writes a stable artifact directory:
@@ -473,7 +473,7 @@ private channel names, user names, or message content may appear. For public PRs
prefer GitHub Actions artifact links over inline images until the redaction story
is stronger.
## Browser And VNC
## Browser and VNC
The browser lane has two modes:
@@ -561,7 +561,7 @@ guild, channel, and message ids. The GitHub smoke workflow enables
If a token is accidentally pasted into an issue, PR, chat, or log, rotate it
after the new secret has been stored.
## GitHub Artifacts And PR Comments
## GitHub artifacts and PR comments
Mantis workflows should upload the full evidence bundle as a short-lived Actions
artifact. When the workflow is run for a bug report or fix PR, it should also
@@ -600,7 +600,7 @@ candidate showed the expected queued -> thinking -> done sequence.
When the run fails because the harness failed, the comment must say that instead
of implying the candidate failed.
## Private Deployment Notes
## Private deployment notes
A private deployment may already have a Mantis Discord application. Reuse that
application instead of creating another app when it has the right bot
@@ -614,7 +614,7 @@ Do not put guild ids, channel ids, bot tokens, browser cookies, or VNC passwords
in this document. Store them in GitHub secrets, the credential broker, or the
operator's local secret store.
## Adding A Scenario
## Adding a scenario
A Mantis scenario should declare:
@@ -643,7 +643,7 @@ Scenarios should prefer small, typed oracles:
Vision checks should be additive. If a platform API can prove the bug, use the
API as the pass/fail oracle and keep screenshots for human confidence.
## Provider Expansion
## Provider expansion
After Discord, the same runner can add:
@@ -657,7 +657,7 @@ After Discord, the same runner can add:
Each transport should have one cheap smoke scenario and one or more bug-class
scenarios. Expensive visual scenarios should stay opt-in.
## Open Questions
## Open questions
- Which Discord bot should be the driver, and which should be the SUT, when the
existing Mantis bot is reused?

36
docs/concepts/message-lifecycle-refactor.md
View File

@@ -75,7 +75,7 @@ non-durable policy.
- Structured OpenClaw-origin metadata for operational/system output so visible
gateway failures do not re-enter shared bot-enabled rooms as fresh prompts.
## Non Goals
## Non goals
- Do not remove `runtime.channel.turn.*` in the first phase.
- Do not force every channel into the same native transport behavior.
@@ -84,7 +84,7 @@ non-durable policy.
- Do not publish all internal migration helpers as stable SDK API.
- Do not make retries replay completed non-idempotent platform operations.
## Reference Model
## Reference model
Vercel Chat has a good public mental model:
@@ -114,7 +114,7 @@ What OpenClaw needs beyond that model:
`thread.post()` style promises are not enough for OpenClaw. They hide the
transaction boundary that decides whether a send is recoverable.
## Core Model
## Core model
The new domain should live under an internal core namespace such as
`src/channels/message/*`.
@@ -137,7 +137,7 @@ core.messages.state(...)
`state` owns durable intent storage, receipts, idempotency, recovery, locks, and
dedupe.
## Message Terms
## Message terms
### Message
@@ -284,7 +284,7 @@ A receipt can describe one platform message or a multi-part delivery. Chunked
text, media plus text, voice plus text, and card fallbacks must preserve all
platform ids while still exposing a primary id for threading and later edits.
## Receive Context
## Receive context
Receiving should not be a bare helper call. The core needs a context that knows
dedupe, routing, session recording, and platform ack policy.
@@ -382,7 +382,7 @@ source if we need platform-level redelivery beyond OpenClaw's restart
watermark. Webhook platforms may need immediate HTTP ack, but they still need
inbound dedupe and durable outbound send intents because webhooks can redeliver.
## Send Context
## Send context
Sending is also context based:
@@ -504,7 +504,7 @@ fallback with no durable record for the remaining payloads. Recovery must know
which units already have receipts and either replay only missing units or mark
the batch `unknown_after_send` until the adapter reconciles it.
## Live Context
## Live context
Preview, edit, progress, and stream behavior should be one opt-in lifecycle.
@@ -552,7 +552,7 @@ This should cover current behavior:
- Teams native progress stream.
- QQ Bot stream or accumulated fallback.
## Adapter Surface
## Adapter surface
The public SDK target should be one subpath:
@@ -651,7 +651,7 @@ type MessageCapabilities = {
};
```
## Public SDK Reduction
## Public SDK reduction
The new public surface should absorb or deprecate these conceptual areas:
@@ -672,7 +672,7 @@ Bundled plugins may keep internal helper imports through reserved runtime
subpaths while migrating. Public docs should steer plugin authors to
`plugin-sdk/channel-message` once it exists.
## Relationship To Channel Turn
## Relationship to channel turn
`runtime.channel.turn.*` should stay during migration.
@@ -699,7 +699,7 @@ After all bundled plugins and known third-party compatibility paths are bridged,
published SDK migration path and contract tests proving old plugins still work
or fail with a clear version error.
## Compatibility Guardrails
## Compatibility guardrails
During migration, generic durable delivery is opt-in for any channel whose
existing delivery callback has side effects beyond "send this payload".
@@ -775,7 +775,7 @@ Concrete migration hazards to preserve:
Channels must not implement this with visible-text prefix filters except as a
short emergency stopgap; the durable contract is structured origin metadata.
## Internal Storage
## Internal storage
The durable queue should store message send intents, not reply payloads.
@@ -822,7 +822,7 @@ load pending or sending intents
The queue should keep enough identity to replay through the same account,
thread, target, formatting policy, and media rules after restart.
## Failure Classes
## Failure classes
Channel adapters classify transport failures into closed categories:
@@ -852,7 +852,7 @@ Core policy:
commit becomes `unknown_after_send` unless the adapter can prove the platform
operation did not happen.
## Channel Mapping
## Channel mapping
| Channel | Target migration |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -879,7 +879,7 @@ Core policy:
| Zalo | Simple receive plus send adapter. |
| Zalo Personal | Simple receive plus send adapter. |
## Migration Plan
## Migration plan
### Phase 1: Internal Message Domain
@@ -984,7 +984,7 @@ messages".
- Remove or hide old internal helpers only after no bundled plugin needs them
and third-party contracts have a stable replacement.
## Test Plan
## Test plan
Unit tests:
@@ -1067,7 +1067,7 @@ Validation:
- Live or qa-channel smoke for at least one edit-capable channel and one
simple send-only channel before removing compatibility wrappers.
## Open Questions
## Open questions
- Whether Telegram should eventually replace the grammY runner source with a
fully durable polling source that can control platform-level redelivery, not
@@ -1086,7 +1086,7 @@ Validation:
- Which channels have native origin metadata, which need persisted outbound
registries, and which cannot offer reliable cross-bot echo suppression.
## Acceptance Criteria
## Acceptance criteria
- Every bundled message channel sends final visible output through
`messages.send`.

22
docs/plugins/sdk-channel-message.md
View File

@@ -7,8 +7,6 @@ read_when:
- You are migrating from legacy reply pipeline or inbound reply dispatch helpers
---
# Channel Message API
Channel plugins should expose one `message` adapter from
`openclaw/plugin-sdk/channel-message`. The adapter describes the native message
lifecycle that the platform supports:
@@ -33,7 +31,7 @@ Runtime delivery helpers are available from
`openclaw/plugin-sdk/channel-message-runtime` for monitor/send code paths that
are already doing asynchronous message I/O.
## Minimal Adapter
## Minimal adapter
Most new channel plugins can start with a small adapter:
@@ -93,7 +91,7 @@ export const demoPlugin = createChatChannelPlugin({
Only declare capabilities that the adapter really preserves. Every declared
capability should have a contract test.
## Outbound Bridge
## Outbound bridge
If the channel already has a compatible `outbound` adapter, prefer deriving the
message adapter instead of duplicating send code:
@@ -116,7 +114,7 @@ uses `manual` receive acknowledgement policy. That makes plugin-owned platform
acknowledgement explicit without changing channels that acknowledge webhooks,
sockets, or polling offsets outside generic receive context.
## Message Tool Sends
## Message tool sends
The shared `message(action="send")` path should use the same core delivery
lifecycle as final replies. If a channel needs provider-specific shaping for the
@@ -167,7 +165,7 @@ keep the prepared send path best-effort; core will still try the write-ahead
queue, but queue persistence or uncertain crash recovery is not part of the
required delivery contract.
## Durable Final Capabilities
## Durable final capabilities
Durable final delivery is opt in per side effect. Core will only use generic
durable delivery when the adapter declares every capability needed by the
@@ -217,7 +215,7 @@ const requiredCapabilities = deriveDurableFinalDeliveryRequirements({
`messageSendingHooks` is required by default. Set `messageSendingHooks: false`
only for a path that intentionally cannot run global message-sending hooks.
## Durable Send Contract
## Durable send contract
A durable final send has stricter semantics than legacy channel-owned delivery:
@@ -266,7 +264,7 @@ becomes the final receipt. Avoid adding new owner-local `messageIds` fields.
Legacy `ChannelDeliveryResult.messageIds` is still produced at compatibility
edges.
## Live Preview
## Live preview
Channels that stream draft previews or progress updates should declare live
capabilities:
@@ -300,7 +298,7 @@ finalizer decides whether the final reply edits the preview in place, sends a
normal fallback, discards pending preview state, keeps an ambiguous failed edit
without duplicating the message, and returns the final receipt.
## Receive Ack Policy
## Receive ack policy
Inbound receivers that control platform acknowledgement timing should declare
receive policy:
@@ -344,7 +342,7 @@ Use `createMessageReceiveContext(...)` in receivers that defer ack state, and
`shouldAckMessageAfterStage(...)` when the receiver needs to test whether a
stage has satisfied the configured policy.
## Contract Tests
## Contract tests
Capability declarations are part of the plugin contract. Back them with tests:
@@ -387,7 +385,7 @@ Add live and receive proof suites when the adapter declares those features. A
missing proof should fail the test rather than silently widening the durable
surface.
## Deprecated Compatibility APIs
## Deprecated compatibility APIs
These APIs remain importable for third-party compatibility. Do not use them for
new channel code.
@@ -409,7 +407,7 @@ Compatibility dispatchers can still use `createReplyPrefixContext(...)`,
message facade. New lifecycle code should avoid the old
`channel-reply-pipeline` subpath.
## Migration Checklist
## Migration checklist
1. Add `message: defineChannelMessageAdapter(...)` or
`message: createChannelMessageAdapterFromOutbound(...)` to the channel plugin.

8
docs/providers/deepinfra.md
View File

@@ -3,10 +3,9 @@ summary: "Use DeepInfra's unified API to access the most popular open source and
read_when:
- You want a single API key for the top open source LLMs
- You want to run models via DeepInfra's API in OpenClaw
title: "DeepInfra"
---
# DeepInfra
DeepInfra provides a **unified API** that routes requests to the most popular open source and frontier models behind a single
endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
@@ -81,3 +80,8 @@ deepinfra/zai-org/GLM-5.1
- Default model: `deepinfra/deepseek-ai/DeepSeek-V3.2`
- Base URL: `https://api.deepinfra.com/v1/openai`
- Native video generation uses `https://api.deepinfra.com/v1/inference/<model>`.
## Related
- [Model providers](/concepts/model-providers)
- [All providers](/providers/index)

2
docs/security/incident-response.md
View File

@@ -7,8 +7,6 @@ read_when:
- Reviewing post-incident follow-up expectations
---
# Incident Response
## 1. Detection and triage
We monitor security signals from: