Agent runtime workflow#

A recommended workflow for developing and testing changes to the OpenClaw agent runtime.

Type checking and linting#

Run the default local gate before committing changes:

pnpm check

When a change can affect build output, packaging, or lazy-loading and module boundaries, also run the build:

pnpm build

For a full landing gate on agent-runtime changes, combine both:

pnpm check && pnpm test

Running agent runtime tests#

Execute the core agent runtime test suites directly with Vitest:

pnpm test \
  "src/agents/agent-*.test.ts" \
  "src/agents/embedded-agent-*.test.ts" \
  "src/agents/agent-tools*.test.ts" \
  "src/agents/agent-settings.test.ts" \
  "src/agents/agent-tool-definition-adapter*.test.ts" \
  "src/agents/agent-hooks/**/*.test.ts"

To exercise live provider paths, prefix with the live-test flag:

OPENCLAW_LIVE_TEST=1 pnpm test src/agents/embedded-agent-runner-extraparams.live.test.ts

These commands cover the primary unit suites for agent execution, embedded runner behavior, tool definitions, settings, adapter logic, and runtime hooks.

Manual testing#

The recommended manual flow starts the gateway in development mode, then exercises the agent and interactive surfaces:

pnpm gateway:dev

Send a direct agent message (delivered through connected channels):

pnpm openclaw agent --message "Hello" --thinking low

Launch the TUI for interactive sessions:

pnpm tui

To observe tool streaming and payload handling, include prompts that trigger read or exec actions.

Clean slate reset#

Runtime state lives under the OpenClaw state directory (default ~/.openclaw). Set OPENCLAW_STATE_DIR to use a different location.

To reset the environment, clear these locations:

• openclaw.json — configuration
• agents/<agentId>/agent/auth-profiles.json — model auth profiles (API keys and OAuth)
• credentials/ — provider and channel state outside the auth profile store
• agents/<agentId>/sessions/ — agent session history
• agents/<agentId>/sessions/sessions.json — session index
• sessions/ — legacy session paths
• workspace/ — to start from a blank workspace

To reset only sessions for one agent, delete agents/<agentId>/sessions/. To keep existing authentication, leave agents/<agentId>/agent/auth-profiles.json and any credentials/ entries in place.

Related#

• Agent runtime architecture
• Agents