ClawGo

A long-running world runtime for game-like simulation.

ClawGo is no longer positioned as a generic multi-agent shell. Its core model is now a World Runtime where main acts as the world mind, npc acts as autonomous characters, and structured state drives the simulation.

• World mind: main owns time, rules, arbitration, and rendering
• Autonomous NPCs: NPCs have persona, goals, memory, relations, and local perception
• Structured world state: world state, NPC state, and world events are persisted independently
• Recoverable execution: runtime and world state survive restart
• Observable: WebUI and APIs expose locations, NPCs, entities, quests, and recent events
• Extensible: low-level providers, channels, and node branches remain intact

中文

What It Is Now

The default runtime loop is:

user -> main(world mind) -> npc/agent intents -> arbitrate -> apply -> render -> user

Roles:

• main
  • user entry
  • world event ingestion
  • NPC wake-up and dispatch
  • intent arbitration
  • world state updates
  • narrative rendering
• npc
  • proposes ActionIntent
  • never mutates world state directly
  • acts from persona, goals, memory, and visible events
• world store
  • persists world state, NPC state, event audit, and runtime records

In one line:

ClawGo is a world runtime, not just an agent chat shell.

Core Highlights

1. main is the world will

• main is not just an orchestrator
• every user message becomes a world event first
• final world truth is decided centrally by main

2. NPCs are autonomous

• each NPC has its own profile
• supports persona, traits, faction, home location, and default goals
• supports long-term goal behavior and event reactions
• supports delegation, messaging, and local perception

3. The world is structured

Core persisted files under workspace/agents/runtime:

• world_state.json
• npc_state.json
• world_events.jsonl
• agent_runs.jsonl
• agent_events.jsonl
• agent_messages.jsonl

4. The simulation loop is real

Current support includes:

• user input -> world event
• NPC perception -> intent generation
• move / speak / observe / interact / delegate / wait
• quest and resource progression
• runtime NPC creation
• map, occupancy, quest, entity, and recent-event visualization

5. The WebUI is already a GM console

• world snapshot
• map view
• NPC detail
• entity detail
• quest board
• advance tick
• recent world events

WebUI

Dashboard

World / Runtime

Config / Registry

Quick Start

1. Install

curl -fsSL https://raw.githubusercontent.com/YspCoder/clawgo/main/install.sh | bash

2. Initialize

clawgo onboard

3. Choose a provider and model

clawgo provider list
clawgo provider use openai/gpt-5.4
clawgo provider configure

For OAuth-backed providers such as Codex, Anthropic, Antigravity, Gemini CLI, Kimi, and Qwen:

clawgo provider list
clawgo provider login codex
clawgo provider login codex --manual

Notes:

• OAuth credentials are stored locally
• available models are synced automatically
• multiple accounts per provider are supported
• WebUI can also start OAuth login, accept callback URL pasteback, confirm device flow, import auth.json, and manage accounts

If you have both an API key and OAuth accounts for the same upstream, use auth: "hybrid":

• prefer api_key
• fall back to OAuth account pools on quota/rate-limit style failures
• keep account rotation, refresh, import, and runtime history

4. Start

Interactive mode:

clawgo agent
clawgo agent -m "I walk to the gate and check what the guard is doing."

Gateway mode:

clawgo gateway run

Development mode:

make dev

WebUI:

http://<host>:<port>/?token=<gateway.token>

World Model

The runtime is organized around:

• WorldState
  • world clock
  • locations
  • global facts
  • entities
  • active quests
• NPCState
  • current location
  • short-term and long-term goals
  • beliefs
  • relationships
  • inventory/assets
  • private memory summary
• WorldEvent
  • user input
  • NPC actions
  • arbitration results
  • state change summaries
• ActionIntent
  • what an NPC wants to do
  • not the final world mutation itself

Core loop:

1. ingest
2. perceive
3. decide
4. arbitrate
5. apply
6. render

Config Layout

Recommended config now centers on agents.agents:

{
  "agents": {
    "defaults": {
      "context_compaction": {},
      "execution": {},
      "summary_policy": {}
    },
    "agents": {
      "main": {
        "type": "agent",
        "prompt_file": "agents/main/AGENT.md"
      },
      "guard": {
        "kind": "npc",
        "persona": "A cautious town guard",
        "home_location": "gate",
        "default_goals": ["patrol the square"]
      },
      "coder": {
        "type": "agent",
        "prompt_file": "agents/coder/AGENT.md"
      }
    }
  }
}

Notes:

• the main config surface is now:
  • agents.defaults.execution
  • agents.defaults.summary_policy
  • agents.agents
• executable local agents usually define prompt_file
• world NPCs enter the world runtime through kind: "npc"
• remote branches still support:
  • transport: "node"
  • node_id
  • parent_agent_id
• normalized config and runtime APIs primarily expose:
  • core.default_provider
  • core.agents
  • runtime.providers

See config.example.json for a complete example.

Memory and Runtime

ClawGo does not treat every actor as one shared context.

• main
  • keeps world-level memory and summaries
• agent / npc
  • uses its own memory namespace or world decision context
• runtime store
  • persists tasks, events, messages, and world state

That gives you:

• better recovery
• better traceability
• clearer execution boundaries

What It Is Good For

• autonomous NPC world simulation
• town / map / scene progression
• quest, resource, and entity interaction
• story-driven sandbox loops
• hybrid local control with remote node branches
• systems that need strong observability and recovery

Node P2P

The low-level node data plane is still available:

• websocket_tunnel
• webrtc

It stays disabled by default. Enable it explicitly with gateway.nodes.p2p.enabled=true. In practice, validate with websocket_tunnel first, then switch to webrtc.

If you want a working starting point, open config.example.json and run make dev.