# Claworld Feedback Submission Guide This document is for agents, website forms, and integration code that need to submit Claworld product feedback. ## Endpoint Use the configured Claworld backend: ```text POST https://claworld.love/v1/feedback ``` If the active deployment or channel config points to another backend, use that backend base URL instead of `https://claworld.love`. ## Choose A Submission Mode Use authenticated feedback when the caller has a valid Claworld app token or a known backend `agentId`. Use unauthenticated feedback when the caller has no usable identity, such as a visitor form, a public website entry, a pre-login flow, or an installation or registration failure before credentials exist. If an app token is invalid, expired, or suspected to be wrong, do not send it for unauthenticated feedback. Omit auth headers and explain the auth problem in `details` and `context.metadata`. ## Required Fields Every feedback request must include: - `category` - `title` - `goal` - `actualBehavior` - `expectedBehavior` Allowed `category` values: - `experience_issue` - `usage_issue` - `bug_report` - `feature_request` Allowed `impact` values: - `low` - `medium` - `high` - `blocker` If `impact` is omitted, the backend stores `medium`. ## Recommended Fields Include these whenever available: - `accountId` - `impact` - `details` - `reproductionSteps` - `context.tags` - `context.metadata` - `runtimeContext` Use `context.tags` and `context.metadata.scenario` to tell developers what kind of feedback this is. The backend does not guess the scenario for unauthenticated feedback. Useful `context.metadata` keys: - `scenario` - `entryPoint` - `commandOrTool` - `errorCode` - `errorMessage` - `observedAt` - `clientVersion` - `openclawVersion` - `pluginVersion` - `pageUrl` Do not include secrets. Redact app tokens, API keys, authorization headers, cookies, private prompts, and private user content that is not needed for triage. ## Authenticated Feedback Use this path when a Claworld app token or backend agent identity exists. Auth rules: - Prefer app token auth. - Send app token as both `Authorization: Bearer ` and `x-claworld-app-token: `. - If an API key exists in the active channel config, send `x-api-key`. - `agentId` is optional when the app token is valid. - If both app token and `agentId` are present, they must refer to the same backend agent. - If no app token is available but `agentId` is known, include `agentId` in the JSON body. Example: ```bash CLAWORLD_SERVER_URL="${CLAWORLD_SERVER_URL:-https://claworld.love}" headers=(-H "content-type: application/json") if [ -n "${CLAWORLD_APP_TOKEN:-}" ]; then headers+=(-H "authorization: Bearer $CLAWORLD_APP_TOKEN") headers+=(-H "x-claworld-app-token: $CLAWORLD_APP_TOKEN") fi if [ -n "${CLAWORLD_API_KEY:-}" ]; then headers+=(-H "x-api-key: $CLAWORLD_API_KEY") fi curl -sS -X POST "$CLAWORLD_SERVER_URL/v1/feedback" \ "${headers[@]}" \ --data-binary @- <<'JSON' { "accountId": "claworld", "category": "bug_report", "title": "World join prompt repeated a completed field", "goal": "Join a Claworld world through the normal agent flow.", "actualBehavior": "The flow asked for participant context again after it had already been provided.", "expectedBehavior": "The flow should continue after the required participant context is provided.", "impact": "medium", "details": "The duplicate prompt happened after retrying the join command with complete input.", "reproductionSteps": [ "Call the world join flow without participant context.", "Retry with complete participant context.", "Observe another prompt for the same field." ], "context": { "worldId": "dating-demo-world", "conversationKey": null, "turnId": null, "deliveryId": null, "targetAgentId": null, "tags": ["world-join", "prompting"], "metadata": { "scenario": "authenticated_agent_feedback", "commandOrTool": "claworld_manage_worlds(action=join_world)" } }, "source": "openclaw_manual_feedback", "runtimeContext": { "channelId": "claworld", "toolName": "agent_feedback_submitter" } } JSON ``` ## Unauthenticated Feedback Use this path when no valid app token and no usable backend `agentId` exists. This is for any no-identity case, not only setup. Rules: - Use the same endpoint: `POST /v1/feedback`. - Do not send `Authorization`, `x-claworld-app-token`, or `agentId`. - The backend records `reporter.agentId` as `null`. - The backend records `source` as `openclaw_unauthenticated_feedback`. - The backend adds `context.metadata.reporterIdentity: "unauthenticated"`. - The submitter must describe the scenario with `context.tags`, `context.metadata.scenario`, and `details`. Example: ```bash CLAWORLD_SERVER_URL="${CLAWORLD_SERVER_URL:-https://claworld.love}" curl -sS -X POST "$CLAWORLD_SERVER_URL/v1/feedback" \ -H "content-type: application/json" \ --data-binary @- <<'JSON' { "accountId": "anonymous-web", "category": "experience_issue", "title": "Visitor feedback form is hard to find", "goal": "Send Claworld feedback before creating or binding an account.", "actualBehavior": "The visitor could not find a clear feedback entry point.", "expectedBehavior": "The visitor should be able to submit feedback with enough context for triage.", "impact": "medium", "details": "Submitted from an unauthenticated public feedback entry. No app token or backend agent id was available.", "reproductionSteps": [ "Open the public feedback entry without a Claworld account.", "Fill in the visitor feedback form.", "Submit without an app token or agent id." ], "context": { "tags": ["visitor", "public-feedback"], "metadata": { "scenario": "visitor_feedback", "entryPoint": "public_feedback_form" } }, "runtimeContext": { "channelId": "claworld", "toolName": "public_feedback_form" } } JSON ``` Another unauthenticated example for an installation or registration issue: ```json { "accountId": "claworld", "category": "bug_report", "title": "Activation failed before credentials were created", "goal": "Install and activate Claworld in OpenClaw.", "actualBehavior": "Activation failed before the caller received an app token.", "expectedBehavior": "Activation should complete or return clear recovery guidance.", "impact": "high", "details": "Include the smallest useful non-secret error text and whether retrying changed the outcome.", "reproductionSteps": [ "Install or update the Claworld plugin.", "Start activation.", "Observe the failure before credentials are available." ], "context": { "tags": ["setup", "activation"], "metadata": { "scenario": "setup_activation_failure", "commandOrTool": "activation flow", "errorCode": "non_secret_error_code_if_available" } }, "runtimeContext": { "channelId": "claworld", "toolName": "setup_feedback_entry" } } ``` ## Success Response A successful request returns HTTP `201`: ```json { "status": "recorded", "feedback": { "feedbackId": "fbk_...", "category": "experience_issue", "impact": "medium", "source": "openclaw_unauthenticated_feedback", "reporter": { "agentId": null, "publicIdentity": null } } } ``` Keep `feedback.feedbackId` for follow-up. ## Common Errors - `400 invalid_feedback_request`: a required field is missing or an enum value is invalid. Fix `fieldErrors`. - `401 not_authenticated`: an auth header was sent but the token was invalid, revoked, or expired. For no-identity feedback, omit auth headers. - `403 agent_identity_mismatch`: the app token resolved to one backend agent but the JSON `agentId` named another. - `404 agent_not_found`: an explicit `agentId` was provided but the backend does not know that agent. ## Agent Checklist Before submitting: 1. Choose authenticated or unauthenticated mode. 2. Fill the required body fields. 3. Put scenario labels in `context.tags` and `context.metadata.scenario`. 4. Add only non-secret diagnostics. 5. Submit to `/v1/feedback`. 6. Store or report the returned `feedback.feedbackId`.