Forge connects your browser, agents, and phone to the same life system.

Recommended shape

origin:   http://127.0.0.1
port:     4317
dataRoot: /absolute/path/to/forge-data
userId:   explicit on writes
userIds:  explicit on cross-owner reads

Why this matters

If OpenClaw, Hermes, Codex, and the browser are meant to see the same goals, tasks, notes, strategies, and users, they must point at the same Forge instance rather than drifting onto separate default stores.

Install

openclaw plugins install forge-openclaw-plugin
openclaw plugins enable forge-openclaw-plugin
openclaw gateway restart
openclaw forge health

Temporary bypass (`2026.4.x`)

npm install -g forge-openclaw-plugin
node -e 'const cp=require("child_process"); const fs=require("fs"); const path=require("path"); const p=process.env.HOME+"/.openclaw/openclaw.json"; const j=JSON.parse(fs.readFileSync(p,"utf8")); const pluginPath=path.join(cp.execSync("npm root -g",{encoding:"utf8"}).trim(),"forge-openclaw-plugin"); j.plugins ??= {}; j.plugins.allow = Array.from(new Set([...(j.plugins.allow || []), "forge-openclaw-plugin"])); j.plugins.load ??= {}; j.plugins.load.paths = Array.from(new Set([...(j.plugins.load.paths || []), pluginPath])); j.plugins.entries ??= {}; j.plugins.entries["forge-openclaw-plugin"] = { enabled: true, config: { origin: "http://127.0.0.1", port: 4317, actorLabel: "aurel", timeoutMs: 15000 } }; fs.writeFileSync(p, JSON.stringify(j, null, 2)+"\n"); console.log("Configured", pluginPath);'
openclaw gateway restart
openclaw plugins info forge-openclaw-plugin
openclaw forge health

What you get

The plugin exposes a curated Forge operating surface rather than every internal route. It is optimized around operator overview, entity mutation, live work, notes, wiki, health, and UI handoff.

Install

~/.hermes/hermes-agent/venv/bin/python -m ensurepip --upgrade
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade ./plugins/forge-hermes

Config location

~/.hermes/forge/config.json

Use the same origin, port, and data root as the browser and OpenClaw if Hermes is meant to share the same Forge system.

Install from a local Forge checkout

Codex uses MCP, and the MCP configuration is shared across the Codex CLI and IDE extension. The most reliable local setup is to point Codex at Forge's repo-local MCP launcher script.

codex mcp add forge \
  --env FORGE_ORIGIN=http://127.0.0.1 \
  --env FORGE_PORT=4317 \
  --env FORGE_ACTOR_LABEL=codex \
  --env FORGE_TIMEOUT_MS=15000 \
  -- /bin/zsh /absolute/path/to/forge/plugins/forge-codex/scripts/run-mcp.sh
codex mcp list

What it is for

The Codex adapter lives in plugins/forge-codex/ and is built for shared-runtime work against the same local Forge system used by the browser, OpenClaw, and Hermes.

Runtime payload

The OpenClaw build path also copies the built runtime into the Codex runtime payload so agent surfaces stay aligned with the same app/API behavior.

How to make it widely available

For broad public distribution, the better path is a hosted remote MCP server over HTTPS with auth, so users can install Forge with one command instead of cloning the repo first.

codex mcp add forge --url https://your-forge-mcp.example.com/mcp
codex mcp list

That is the cleanest public install story for Codex today. The repo-local launcher is ideal for contributors and local-first use, but a remote MCP endpoint is what makes Forge easy to adopt at scale.

What the companion does

The iOS companion pairs to a local Forge runtime, requests Apple permissions, imports HealthKit sleep and workout data, and writes structured Forge records rather than opaque snapshots.

Relevant routes

/api/v1/health/pairing-sessions
/api/v1/mobile/pairing/verify
/api/v1/mobile/healthkit/sync
/api/v1/health/sleep
/api/v1/health/fitness