Common Pitfalls When Setting Up OpenClaw

A Summary of Pitfalls in OpenClaw Configuration

About This Note

This article is a record of the points where I stumbled while actually working with OpenClaw in Cursor, so that I can look back and avoid falling into the same traps again regarding:

• The structure of Zenn article repositories
• OpenClaw Browser Relay (Chrome extension)
• The automation flow from Zenn article to X (Twitter) post

1. The Question of Where to Place the Zenn Article Folder

The Problem

• There were various files directly under workspace:
  • articles/ at the root
  • articles/ inside zenn-content/
  • And zenn-articles/ also appeared midway
• The Zenn deployment screen would complain: "articles directory not found."

The Solution

• Decide on one master repository for Zenn.
  • Ultimately, I set /Users/arakijun/.openclaw/workspace/zenn-articles as the authoritative source.
• Keep it simple inside:
  • articles/ … Article Markdown files
  • books/ … Use later if necessary (an empty folder is fine)
• Organize (delete or deprecate) any other articles/ directories. Deciding that "Zenn-related files only exist within zenn-articles/" clears up the confusion.

2. OpenClaw Browser Relay Errors

Situation

• A red ! is showing on the crab icon in the top right of Chrome.
• In the extension options:
  • Port: 18792
  • "Gateway token required"
• The documentation says to "connect to http://127.0.0.1:18792/."

Pitfalls

1. I was trying to use the extension before the Browser Relay server itself was launched.
2. It is momentarily unclear where to get the Gateway token.

Obtaining the Gateway Token

You can check the Gateway token from the OpenClaw configuration file. Execute the following in your terminal:

cat ~/.openclaw/openclaw.json

Paste the gateway.auth.token (or the value corresponding to the OPENCLAW_GATEWAY_TOKEN environment variable) from the outputted JSON directly into the "Gateway token" field in the Chrome extension.

Mac vs. Windows Differences

Browser Relay has both Mac and Windows versions, and the installation methods for the extension and the relay startup procedures differ depending on your environment. Check the official documentation (e.g., docs.openclaw.ai/tools/chrome-extension) for instructions specific to your OS.

What I Actually Did

1. Started Browser Relay / Gateway from openclaw tui.
   • Looked for "browser extension" and "gateway" related items in the menu and started them.
2. Extracted the Gateway token from ~/.openclaw/openclaw.json as described above.
3. In the Chrome extension options screen:
   • Kept the Port at the default 18792.
   • Pasted the token above into the Gateway token field and clicked Save.
4. Clicked the crab icon in the tab, and the connection was successful once the red ! disappeared.

The key takeaway is:

• You need to start not just the extension, but also the "OpenClaw relay server."
• It only turns green once both the port and the token are correctly configured.

3. Flow Design: Zenn Article to X Post

Goal

• Write an article on Zenn.
• Generate a post for X (Twitter) based on its content.
• Ideally, automate the posting process via browser automation.

Skills Prepared

1. zenn-article-writer
   • A skill to create Zenn-formatted Markdown in /zenn-articles/articles.
   • Explicitly defined rules for FrontMatter and slugs (12–50 characters, alphanumeric, hyphens, and underscores) here.
2. zenn-to-x
   • Reads the article file (e.g., changing_careers_to_engineer.md).
   • Generates 1–3 post drafts in Japanese under 280 characters that highlight article summaries and reader benefits.
   • Automatically generates the URL in the format https://zenn.dev/jaraki/articles/<slug>.
3. x-post
   • Opens the X posting screen via OpenClaw Browser Relay.
   • Enters the generated text -> asks for user confirmation -> clicks the Post button.

Where I Actually Stumbled

• The agent sometimes insisted that "the skill cannot be used due to a configuration error."
  • In reality, it was just a hallucination; the skill file is just text.
  • Even if it claims "configuration is missing," the outputted post drafts are perfectly usable.
• Ultimately, I realized the most realistic approach is to start with:
  1. Generating text only using logic equivalent to zenn-to-x.
  2. Manually copying and pasting it to X to post.

4. If You Are About to Do This

If you want to integrate Zenn articles with X posts using OpenClaw, I recommend the following order:

1. Choose one location for your Zenn repository.
   • E.g., ~/.../zenn-articles
   • Create articles/ and books/ inside it.
2. Get Browser Relay running.
   • Install the extension using the procedure matching your OS (Mac/Windows).
   • Start Gateway/Relay from openclaw tui and set the token obtained via cat ~/.openclaw/openclaw.json in the extension.
3. Divide roles by skills.
   • Skill for writing articles (for Zenn)
   • Skill for creating X copy from articles
   • Skill for posting to X via browser
   • Start by "generating the content" and doing the actual "posting manually."

Conclusion

Combining OpenClaw and Zenn allows you to automate a large portion of the "Article Writing -> Summary -> X Posting" workflow, but I found that the following two points are easy to stumble over:

• Repository structure
• Browser Relay (ports, tokens, and Mac/Windows differences)

I hope this article helps my future self or anyone struggling with a similar setup.