SharetoBoard
Local-only diagnosis

TentaClaw troubleshooting.

Diagnose one layer at a time: installation, local config/key files, Poppy reachability, stdio startup, client registration, destination policy, then the agent workflow.

OverviewInstallClientsTroubleshootingIncident response
Never include in support: the key, key-file contents, private prompt/response, raw board/chat/conversation IDs, credential-bearing URL, cookies, tokens, or a full environment dump.

Start with the safe local checks

tentaclaw-mcp --version
tentaclaw-mcp status
tentaclaw-mcp doctor

status never contacts Poppy and prints sanitized configuration. doctor validates the protected files and current approved-destination visibility.

tentaclaw-mcp is not recognized

  1. Close and reopen the terminal if the RC13 bundled installer updated PATH.
  2. Confirm the verified release bundle was installed with scripts/install-local.ps1 on Windows or scripts/install-local.sh on macOS/Linux.
  3. Rerun only the installer from the same checksum-verified RC13 bundle; do not substitute a source-checkout installation.
  4. Run tentaclaw-mcp --version and confirm 0.3.0rc13.

configuration_error or missing setup

Run:

tentaclaw-mcp status
tentaclaw-mcp init
tentaclaw-mcp doctor

Do not add a key or key-file path to the client configuration as a workaround. The local server owns and loads its per-user files.

Missing, unreadable, or unsafe key file

Missing or empty

Rerun tentaclaw-mcp init in a trusted local terminal. Enter the key only through its hidden input.

POSIX permission rejection

The file must be a regular non-symlink owned by the current user with no group/other access.

Windows ACL issue

Rerun setup to reapply the owner-only ACL. Keep the files in the per-user TentaClaw directory.

Previously exposed

Stop the client, revoke/reissue the Poppy key, remove exposed copies, rerun setup, and use a disposable test destination.

Client shows TentaClaw as disconnected

  1. Run tentaclaw-mcp --version and doctor in a normal terminal.
  2. For Codex-backed clients, run tentaclaw-mcp codex-config check. If it reports UPGRADE_REQUIRED, close the client and run codex-config install, then check.
  3. For another candidate client, regenerate only its entry with tentaclaw-mcp client-config <client>.
  4. Confirm the entry is local, key-free, and contains no URL or port.
  5. Completely quit and reopen the client, then use its native MCP status surface.
  6. When unclear, test with the generated MCP Inspector diagnostic command.

Client starts but fewer than six tools appear

  1. Confirm the exact client surface supports local stdio MCP.
  2. Remove and re-add the generated TentaClaw entry.
  3. Restart the client.
  4. Call tentaclaw_version before any Poppy tool.
  5. Record the client product/version and safe MCP error—not its full transcript.

policy_denied

The board or chat is not in the local allowlist. Rerun tentaclaw-mcp init, reuse or replace the key, and explicitly select the destination. Do not enable unrestricted access merely to make a test pass.

Poppy HTTP, timeout, or malformed response

Safe errorAction
http_errorRecord status only; verify Poppy API access and account state.
request_failedCheck Internet/TLS reachability. GET retries are bounded; POST calls are not automatically retried.
redirect_rejectedStop. TentaClaw will not follow a Poppy redirect to another destination.
request_too_largeReduce prompt/additional context; do not disable the bound reflexively.
response_too_largeNarrow the question or destination.
malformed_responseRecord time, Poppy status when available, and exact TentaClaw/client versions.
streaming_not_supportedUse the normal non-streaming tool call.

Safe support bundle