Troubleshooting

Common issues and fixes across all seven onboarding steps.

Quick verification table

Run these to confirm each step completed correctly:

Environment differences (OpenClaw vs HyperClaw)

Some steps work differently depending on which environment you're on. Check first:

openclaw status

Key differences:

If you're on OpenClaw and a step refers to a dashboard setting, look for the equivalent openclaw configure command instead.

Step 1 — Identity

Identity files aren't being read

The files exist but your Claw responds generically. Most common cause: files are uploaded but not at the workspace root.

Check where your workspace is:

echo $OPENCLAW_WORKSPACE
ls $OPENCLAW_WORKSPACE/SOUL.md

If the file isn't there, copy it:

cp ~/SOUL.md $OPENCLAW_WORKSPACE/SOUL.md

Then restart your Claw and re-verify.

Changes to SOUL.md not taking effect

A running Claw doesn't re-read its context files mid-session. Always restart after editing identity files.

Step 2 — ZenBin

ZenBin publish fails with 401

Your key isn't registered or the signature is wrong. Verify the key is registered:

curl -s https://zenbin.org/api/keys/$(cat ~/.zenbin-key-id)

If you get a 404, the key ID is wrong or the key wasn't registered. Re-run the registration step:

curl -s -X POST https://zenbin.org/api/keys \
  -H "Content-Type: application/json" \
  -d "{\"publicKey\": \"$(openssl pkey -in ~/.zenbin-private-key.pem -pubout -outform PEM | tr -d '\n')\"}"

Update ~/.zenbin-key-id with the returned key ID.

ZenBin publish fails with 403

The signature doesn't match. The most common cause is encoding mismatch — the base64 encoding must match what was signed exactly. Use -w 0 to prevent line wrapping:

ENCODED=$(echo "$CONTENT" | base64 -w 0)   # correct
ENCODED=$(echo "$CONTENT" | base64)         # may fail — wrapped lines

Private key not found

ls -la ~/.zenbin-private-key.pem

If missing, you need to regenerate the keypair and re-register. Your old publish code won't work after re-keying.

Step 3 — Web Search

"I don't have the ability to browse the web"

On OpenClaw, the browser/search tool is disabled by default:

openclaw tools enable browser
openclaw tools enable search

Then restart and verify.

Search returns stale or training-data results

The search MCP may not be configured. Check:

openclaw tools list

If brave-search or equivalent isn't in the list, add it. See the web search step for setup.

Step 4 — Memory

Claw doesn't remember things between sessions

Memory only persists if the Claw is actively writing to files. Confirm the memory rule is in SOUL.md:

grep -i "memory" ~/SOUL.md

If nothing appears, add the memory rules from Step 4 and restart.

MEMORY.md keeps getting overwritten

Your Claw may be re-initializing it on each session. Check if there's a startup script that resets workspace files. If so, add MEMORY.md to the exclusion list.

Step 5 — Scheduling

Cron job isn't running

Check the scheduler's status:

# HyperClaw
openclaw schedule list
 
# OpenClaw
openclaw cron list

If the job is listed but not running, check the gateway logs:

openclaw gateway logs --tail 50

Look for the job name and any error messages.

Scheduled task runs but Telegram message isn't delivered

The task is running but the Telegram integration is broken. Test independently:

Send me a test message on Telegram right now.

If that fails, reconnect Telegram in your Claw's settings.

Timezone mismatch

Jobs running at the wrong time are almost always a timezone issue. Verify what timezone your Claw thinks it's in:

What timezone are you in? What time is it right now?

If it's wrong, set the timezone explicitly in the schedule configuration and update USER.md.

Step 6 — Morning Brief

Morning brief skill times out

The brief makes multiple web searches and a ZenBin publish in one run. On slow connections or with rate-limited search APIs, this can exceed the default timeout.

Increase the timeout in your skill configuration:

# Add to skills/morning-brief.md YAML front matter:
# timeout: 120   (seconds)

Or split the brief into two skills: morning-gather (search) and morning-publish (format + publish).

Brief has no "Today" section content

MEMORY.md exists but doesn't have current priorities. Add them manually:

Add to my MEMORY.md: this week I'm focused on [current project].

The next run will pick it up.

ZenBin URL in Telegram is wrong or broken

The brief published but the URL is malformed. Check the publish response in the morning brief output — it should include a full https://zenbin.org/p/... URL. If it's truncated, the skill's HTML formatting step may be cutting the URL.

Step 7 — Clawvisor

"No credentials found" for Google Workspace

Run the configuration flow:

openclaw configure
# Select: Google Workspace
# Follow the OAuth browser flow

Or in HyperClaw: Dashboard → Claw → Clawvisor → Google Workspace → Connect.

Google OAuth flow fails to redirect back

The redirect URI may not be registered. Check that the authorized redirect URI in your Google OAuth app includes https://app.hyper.io/oauth/callback (HyperClaw) or http://localhost:PORT/callback (OpenClaw local).

Slack posts going to the wrong channel

The channel name in your request must exactly match the Slack channel name, including capitalization:

Post "test" to #dev-general        # correct if channel is named dev-general
Post "test" to #Dev-General        # won't work

GitHub token has insufficient permissions

A common issue is a token scoped too narrowly. The minimum permissions for repo read + PR create:

• repo (full repo access) or
• contents:read, pull_requests:write, issues:write

Generate a new PAT at github.com/settings/tokens with the right scopes.