Skip to content

setup.md

Latest commit

 

History

History
114 lines (87 loc) · 4.37 KB

setup.md

File metadata and controls

114 lines (87 loc) · 4.37 KB
Raw

Community setup

OpenClaw image generation defaults to openai/gpt-image-2. Override it with GENII_OPENCLAW_IMAGE_GENERATION_MODEL before creating or restarting a bot runtime when a different supported model is required.

Choose a mode

Browser mode is the shortest path. The API and UI run locally, state is stored in SQLite, and chat runs in an OpenClaw browser session inside E2B. It needs an E2B key/template and an OpenAI key entered during bot creation. It does not need Docker, a tunnel, Composio, or Linq.

Postgres mode runs the same product against the Docker Compose database. Full callback mode adds a stable HTTPS tunnel for remote runtime callbacks, Talk, scheduler delivery, Composio OAuth/triggers, and optional Linq.

Install

make setup

The command creates ignored .env and frontend/.env.local files only when they are absent, generates strong local secrets, and installs pinned Python and frontend dependencies. Re-running it keeps existing values.

Add these developer-owned E2B values to .env:

SANDBOX_E2B_API_KEY=...
SANDBOX_E2B_TEMPLATE_ID=...

The template must contain a compatible desktop/browser environment and OpenClaw 2026.6.5. This repository does not distribute an E2B image.

Native OpenClaw browser chat does not require Genii's experimental computer-use bridge. If your E2B template also contains the required Kimi WebBridge runtime, you may opt in with GENII_DESKTOP_ENABLED=1. Run the desktop smoke endpoint after provisioning to verify that template-specific dependency; keep the flag off when it is unavailable.

Validate configuration, then start:

make doctor
make dev-basic

Visit http://localhost:1430. Local developer sign-in is available only while GENII_ENV is local and GENII_DEV_AUTH_BYPASS=1. Paste your OpenAI API key in the BYOK creation form; do not put a bot key in a committed config file.

Postgres

make infra
make db-migrate
make dev

The Compose database listens on port 5434 by default so it does not collide with a common local Postgres install. make infra-stop preserves its volume; make infra-down deletes that local Genii volume.

If another project already owns 5434, choose an unused port in the root .env:

GENII_DB_PORT=5435

Make and Docker Compose both read this same file. make infra-wait verifies that the Genii Postgres container actually owns the expected host binding; internal container health alone is not treated as proof that migrations can reach it.

make dev already depends on make infra and make db-migrate, so after the first explicit setup they may be omitted. They remain useful as separate diagnostic steps when validating Docker or migrations.

Optional Linq callback

After configuring a public HTTPS tunnel plus your Linq API key and phone number, run make linq-setup. It creates or reuses the exact callback and stores Linq's one-time signing secret in the ignored .env. It does not enable Linq; set GENII_LINQ_ENABLED=1 only after setup succeeds, then run make doctor-full.

See Optional Linq beta for safe recovery when a provider subscription exists but its one-time secret has been lost.

Troubleshooting

  • make doctor reports missing E2B values: add your own key and template ID.
  • Runtime is sleeping: use Resume/Open Genii; E2B auto-pause is enabled by default to control cost.
  • Browser UI cannot reach the API: confirm ports 1430/8010 and the frontend proxy values in frontend/.env.local.
  • Remote runtime says the Gateway is unreachable: configure a tunnel and make sure GENII_PUBLIC_BASE_URL/health reaches this backend.
  • OAuth or provider callbacks fail: callback mode requires a stable HTTPS URL; restarting a free tunnel may change it and invalidate registrations.
  • A schedule did not fire while the laptop/backend was off: v0.1 has no always-on wake service. Restart recovery applies only after the local backend returns.
  • A provider call fails: verify the developer-owned account, scopes, quota, and provider dashboard before treating it as a Genii runtime failure.
  • Internet search fails: the default key-free Parallel Search endpoint is an external best-effort service. Retry later and distinguish search-provider availability from web_fetch, which can still fetch a known public URL.

Never paste .env, bearer tokens, tokenized OpenClaw URLs, or raw provider payloads into public issues or logs.