Real-World OpenClaw Setup on Apple Silicon

I spent an evening setting up OpenClaw on a Mac Mini to serve as an AI-powered assistant for my consulting business. The official docs make it sound like a 30-minute job. It took closer to three hours, and not because I was slow — because the guides skip over every real error you'll encounter.

This article documents every issue I hit, in order, with exact fixes. If you're setting up OpenClaw on a Mac with Apple Silicon, this will save you significant time and frustration.

My Setup

Hardware: Mac Mini (M-series, Apple Silicon)
LLM: ChatGPT Pro personal account ($200/mo) via Codex OAuth
Channel: Telegram bot
Remote access: Jump Desktop + Twingate (not Tailscale)
Productivity: M365 Business Basic ($6/mo) for the assistant
Account strategy: Single macOS account, admin during setup, downgraded to standard after

The Plan

The idea was straightforward: install OpenClaw, connect it to ChatGPT Pro, set up a Telegram bot so I could message it from anywhere, and wire it into my M365 environment. The agent would handle email triage, calendar management, note-taking, reminders, and basic document work. This kind of local AI deployment represents a real shift in how small businesses can operate — running your own infrastructure instead of relying entirely on SaaS platforms.

Simple enough on paper.

Issue 1: Homebrew Isn't in Your PATH

The very first command after installing Homebrew fails.

$ brew install node@22
zsh: command not found: brew

On Apple Silicon Macs, Homebrew installs to /opt/homebrew/bin/, not /usr/local/bin/ like on Intel Macs. The installer prints the fix at the end, but it scrolls by so fast you'll miss it.

Fix:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
eval "$(/opt/homebrew/bin/brew shellenv)"

Why guides miss this: Most were written for Intel Macs, or assume you already have Homebrew configured. Every Apple Silicon setup guide should lead with this.

Issue 2: Node.js Installs but Doesn't Work

After successfully installing Node 22 via Homebrew, the node command doesn't exist.

$ brew install node@22
$ node --version
zsh: command not found: node

Node@22 is "keg-only" in Homebrew, meaning it's installed but not symlinked into your PATH. Homebrew does this when multiple versions might coexist.

Fix:

brew link node@22
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
node --version  # v22.22.0

The brew link command creates over 2,000 symlinks but you still need the PATH export. Both steps are required.

Why this matters: If you just run brew link and move on, it might work in the current session but break in new terminal windows. The .zshrc export makes it permanent.

Issue 3: 710 Packages Installed with Scary Yellow Warnings

Running npm install -g openclaw produces a wall of yellow deprecation warnings:

npm warn deprecated [email protected]
npm warn deprecated [email protected]
npm warn deprecated [email protected]
npm warn deprecated [email protected]
npm warn deprecated [email protected]
npm warn deprecated [email protected]
npm warn deprecated [email protected]
npm warn deprecated [email protected]

This looks like something went wrong. It didn't. These are sub-dependency deprecation notices — libraries used by libraries used by OpenClaw. They're informational. Everything installed correctly.

The rule: If npm finishes with "added X packages" at the end, you're fine. Yellow warnings about deprecated sub-dependencies are normal in every Node.js project.

Issue 4: npm Wants to Upgrade Itself — Don't Let It

After the install, npm helpfully suggests:

npm notice New major version of npm available! 10.9.4 → 11.11.0

Do not run `npm install -g npm@latest`. npm 10.9.4 ships paired with Node 22 and is fully compatible. npm 11 is a major version bump from Node 23's release cycle. Upgrading npm independently of Node creates version mismatches — Homebrew expects one version but finds another, which can cause weird breakage during future brew upgrade runs.

The rule: Let Homebrew manage npm. When you eventually run brew upgrade node@22, it will bump npm to whatever version is paired with that Node release.

Issue 5: OAuth Redirect Doesn't Auto-Complete

During the onboarding wizard, OpenClaw opens your browser for ChatGPT Pro sign-in via Codex OAuth. After authorizing, the browser shows:

"Authentication successful. Return to your terminal to continue."

But the terminal is still sitting there waiting for an authorization code. The redirect to localhost:1455 didn't propagate back to the CLI process.

Fix: Copy the full URL from Safari's address bar — it looks something like http://localhost:1455/auth/callback?code=ac_wb-NMRza7wPqIcuZK25w... — and paste it into the terminal when prompted.

Why this happens: Browser security policies and localhost callback handling are inconsistent across macOS. The auto-complete works for some people, fails for others. Guides should present manual paste as the primary method, not the fallback.

Issue 6: macOS "Local Network" Permission Popup

When the gateway starts for the first time, macOS shows a system dialog:

"Allow 'node' to find devices on local networks?"

Select Don't Allow. The OpenClaw gateway binds to localhost (127.0.0.1) and communicates outbound to Telegram and OpenAI servers. It does not need to discover devices on your local network. This is just macOS's standard local network permission prompt firing for any Node process that opens a network socket.

No guide mentions this dialog. It appears at a moment when you're anxious about whether the gateway will start correctly, and the natural instinct is to click "Allow" to avoid breaking anything. You don't need to.

Issue 7: The ClawHub Skill Registry and DNS Filtering

This was my biggest time sink. After the core setup was complete and the Telegram bot was responding, I tried to install additional skills:

$ npx clawhub@latest install excel
✖ fetch failed
Error: fetch failed

That's it. No URL, no status code, no explanation. Just "fetch failed."

I spent an hour trying every debug approach:

Cleared the npx cache
Installed clawhub globally
Tried DEBUG=* (no output)
Tried --verbose (not a valid flag)
Checked connectivity with curl and ping (everything worked)

The breakthrough came with NODE_DEBUG=fetch:

$ NODE_DEBUG=fetch clawhub install excel
FETCH 2173: connecting to clawhub.ai using https:undefined
FETCH 2173: connection to clawhub.ai using https:undefined errored — unable to verify the first certificate
FETCH 2173: request to GET https://clawhub.ai//.well-known/clawhub.json errored — unable to verify the first certificate
FETCH 2173: connecting to registry.clawhub.com using https:undefined
FETCH 2173: connection to registry.clawhub.com using https:undefined errored — getaddrinfo ENOTFOUND registry.clawhub.com

Two problems visible now: an SSL certificate issue on clawhub.ai, and a DNS resolution failure for registry.clawhub.com.

Root cause: I run DNSFilter on my network, which blocks newly registered domains as a security measure. ClawHub's domain was new enough to be caught by this filter. The "fetch failed" error gave zero indication that DNS was the issue. If you run any network-level security controls, this is the kind of silent failure that will eat your time.

Fix: Whitelist clawhub.ai and registry.clawhub.com in your DNS filter.

The lesson: If you run any corporate DNS filtering, content filtering, or network security appliance (Cisco Umbrella, DNSFilter, Zscaler, etc.), OpenClaw's ClawHub registry may be blocked. The error message will not tell you this. Use NODE_DEBUG=fetch to see the actual URLs being requested and what's failing.

Domains to Whitelist for OpenClaw

If you're behind any DNS filter or firewall, whitelist these:

clawhub.ai — Skill registry
registry.clawhub.com — Skill downloads
api.openai.com — ChatGPT / OpenAI API
api.telegram.org — Telegram bot API
login.microsoftonline.com — M365 authentication
graph.microsoft.com — M365 Graph API
outlook.office.com — Outlook web access
*.office365.com — M365 services
github.com — Skill repos and updates
registry.npmjs.org — npm packages

No OpenClaw documentation lists these requirements. If you're deploying in any managed network environment, you need this list on day one.

Issue 8: Skill Names Aren't What You Think

After fixing the DNS issue, I tried installing skills with the names I'd seen referenced in guides and community posts:

$ npx clawhub@latest install excel
✖ Skill not found

$ npx clawhub@latest install pptx-creator
✖ Skill not found

The slugs excel and pptx-creator don't exist. You need to search first:

$ npx clawhub@latest search excel
microsoft-excel  Microsoft Excel  (3.604)
excel-xlsx  Excel / XLSX  (3.543)
...

$ npx clawhub@latest search pptx
powerpoint-pptx  PowerPoint PPTX  (3.689)
...

The correct commands are:

npx clawhub@latest install microsoft-excel
npx clawhub@latest install powerpoint-pptx

The lesson: Always search before installing. Skill slugs are not standardized and community references may use unofficial names.

Issue 9: The Invisible Space That Creates the Wrong Folder

During troubleshooting, I needed to create a skills directory manually. A tiny typo created a mess:

# What I typed (wrong — space before 'skills'):
mkdir -p ~/.openclaw skills

# What this actually creates:
# 1. ~/.openclaw (already existed)
# 2. A folder called 'skills' in the current directory

The correct command:

mkdir -p ~/.openclaw/skills

In a dark terminal at the end of a long session, the difference between ~/.openclaw skills and ~/.openclaw/skills is nearly invisible. If you're copy-pasting from a guide and the line breaks wrong, you'll silently create the wrong directory and nothing will tell you.

Issue 10: M365 Business Basic ≠ Desktop Editing

During setup, I assigned the assistant account an M365 Business Basic license. Word on the Mac showed "Ready to View Documents" with no editing capability, which initially looked like a permissions issue.

The actual cause: M365 Business Basic only includes web and mobile Office apps — no desktop editing licenses. If you need desktop editing, you need Business Standard ($12.50/mo) or higher.

For OpenClaw, this doesn't matter. The agent interacts with M365 through browser automation and APIs, not desktop applications. But it's worth understanding which cloud services tier fits your needs before you commit to a license.

Issue 11: Claude Subscriptions Are Banned for Third-Party Tools

During planning, I considered using Claude instead of ChatGPT as the LLM backend. The answer is no — Anthropic's terms explicitly prohibit using Claude Pro, Max, or Team subscriptions with third-party tools like OpenClaw. You'd need API keys, which are pay-per-token and cost-prohibitive for an always-on assistant compared to ChatGPT Pro's flat $200/month with generous limits.

This isn't documented in OpenClaw's guides because it's an Anthropic policy, not an OpenClaw limitation. But it's a critical decision point if you're choosing your LLM provider.

Issue 12: M365 Integration Is Browser Automation, Not a Plugin

I expected M365 integration to work like other platforms — install a plugin, enter credentials, done. It doesn't.

OpenClaw accesses M365 through a headless Chrome browser controlled by a Chrome extension called the "OpenClaw Browser Relay." The setup involves:

Installing the Chrome extension from openclaw browser extension install
Loading it as an unpacked extension in Chrome (Developer Mode required)
Configuring the gateway token in the extension
Navigating to M365 web apps and signing in
The agent then uses this authenticated browser session for all M365 tasks

This is significantly more complex than a simple OAuth flow and requires the gateway token, which you'll need to extract from your config:

cat ~/.openclaw/openclaw.json | grep token

A gotcha: when Chrome asks you to navigate to the extension directory at ~/.openclaw/browser/chrome-extension, Finder dialogs can't resolve the ~ shortcut. Use Cmd + Shift + G in the file picker and type the full path: /Users/openclaw/.openclaw/browser/chrome-extension.

What I Ended Up With

After about three hours:

OpenClaw gateway running 24/7 on Mac Mini
ChatGPT Pro (gpt-5.3-codex) as the AI brain
Telegram bot responding to messages from my phone
Apple Notes and Reminders skills for shared task management
nano-pdf for document handling
model-usage for tracking token consumption
Session memory enabled so the agent remembers context across conversations
Security audit passed — loopback binding, token auth, file permissions locked down
Chrome browser relay connected for M365 web access
Energy settings configured so the Mac Mini never sleeps
Auto-restart on power failure enabled

What the Guides Should Say

The official OpenClaw documentation is accurate but incomplete. It tells you the right commands without mentioning the errors those commands will produce. Here's what every setup guide should include:

Lead with the Apple Silicon PATH fix. Homebrew on M-series Macs needs the shellenv eval in .zshrc. Print it in a box. Bold it.
Explain that node@22 is keg-only. The brew link + PATH export is a required step, not an edge case.
Tell people to ignore yellow npm warnings. First-time Node users will panic. A single sentence saying "deprecation warnings are normal" would prevent 15 minutes of Googling.
Show the OAuth manual paste as step one, not as a troubleshooting footnote.
List required domains for network environments. Anyone with DNS filtering, a corporate firewall, or a security appliance will hit ClawHub failures with no useful error message.
Document `NODE_DEBUG=fetch` as the primary debugging tool. The "fetch failed" error is the most common issue in the OpenClaw ecosystem and it provides zero diagnostic information by default.
Explain that skill slugs must be searched, not guessed. Community posts reference names that don't match the actual registry.
State the Claude subscription restriction clearly in the LLM provider selection docs.

Cost Reality

ChatGPT Pro: $200/month (existing subscription, shared with personal use)
M365 Business Basic: $6/month
Everything else: free (Telegram, Twingate, OpenClaw itself)

Total additional cost: ~$6/month beyond what I was already paying for ChatGPT Pro.

Time Reality

Official estimate: "Quick setup"
Actual time: ~3 hours including troubleshooting
Time if you read this article first: ~45-60 minutes

Security Notes

The ClawHub skill ecosystem has had real security incidents. In January 2026, researchers discovered 341 malicious skills distributing malware through the registry. A subsequent scan of nearly 13,000 skills flagged 4.4% as potentially dangerous. Before installing any community skill, check the author's reputation, star count, and read the SKILL.md file. Stick to well-known, actively maintained skills. The same foundational cybersecurity practices that apply to any software supply chain apply here.

Final Thoughts

OpenClaw is genuinely impressive once it's running. Having an AI assistant I can message from Telegram, that remembers our conversation history, can read my shared notes and reminders, handle PDFs, and interact with M365 — all running on a $600 Mac Mini in my house — feels like the future.

Getting there was the hard part. Not because the technology is bad, but because the documentation assumes a clean path that doesn't exist in the real world. Every developer environment has quirks: PATH issues, keg-only packages, DNS filters, browser permission dialogs, rate limits. The guides skip all of it.

I wrote this so the next person doesn't have to spend three hours figuring out what fetch failed actually means.