openclaw - 💡(How to fix) Fix [Feature]:Automatically inject session context into exec tool subprocess environment

Root Cause

Variables should be set dynamically per spawn, not globally at Gateway startup
This is necessary because session context is runtime-dynamic
User-provided env in the exec tool call should take precedence (override if explicitly set)
Graceful fallback when session context is unavailable (e.g. local/CLI mode)

Fix Action

Fix / Workaround

Current workaround & its pain

The only current workaround is manually passing env: { OPENCLAW_SESSION_ID: "..." } on every exec call. This requires:

The agent to explicitly know its own session ID (awkward self-reference)
Every exec call site to remember to pass it
Re-passing on every new conversation turn (env not persisted across turns)

Summary

Problem

When OpenClaw agent executes commands via the exec tool, the spawned subprocess has no way to identify which session it's running in. This makes it difficult to:

Correlate subprocess logs with agent sessions
Build tools that need to call back into the agent's session (e.g. openclaw agent --session-id)
Track work across multiple concurrent sessions

Use Case

A subprocess (bash/python/any command) spawned by the exec tool needs to know the current session ID to call back into the agent or log session-correlated output.

Currently, this requires manually passing env: { OPENCLAW_SESSION_ID: "..." } on every exec call, which means the agent must explicitly know and pass its own session ID — an awkward self-reference.

Proposed Solution

Automatically inject session context into every subprocess spawned by the exec tool, similar to how opencode handles this (see: anomalyco/opencode#9292):

OPENCLAW_SESSION_ID — the unique session UUID
OPENCLAW_SESSION_KEY — the session key (e.g. agent:main:draft:xxx)
OPENCLAW_AGENT_ID — the agent id (e.g. main)

Implementation Notes

Variables should be set dynamically per spawn, not globally at Gateway startup
This is necessary because session context is runtime-dynamic
User-provided env in the exec tool call should take precedence (override if explicitly set)
Graceful fallback when session context is unavailable (e.g. local/CLI mode)

Example Usage

# Any script spawned by exec tool can now do:  
echo "Running in session: $OPENCLAW_SESSION_ID"  
openclaw agent --session-id "$OPENCLAW_SESSION_ID" --message "subtask done"  


### Problem to solve

When OpenClaw agent executes commands via the `exec` tool, the spawned subprocess
has no way to identify which session it's running in. This makes it difficult to:
- Correlate subprocess logs with agent sessions
- Build tools that need to call back into the agent's session (e.g. `openclaw agent --session-id`)
- Track work across multiple concurrent sessions


### Proposed solution

Automatically inject session context into every subprocess spawned by the `exec` tool,
similar to how opencode handles this (see: anomalyco/opencode#9292):

- `OPENCLAW_SESSION_ID` — the unique session UUID
- `OPENCLAW_SESSION_KEY` — the session key (e.g. `agent:main:draft:xxx`)
- `OPENCLAW_AGENT_ID` — the agent id (e.g. `main`)

### Alternatives considered

_No response_

### Impact

### Who is affected
Any user who:
- Runs multi-step workflows where subprocesses need to call back into the agent session
- Uses `exec` tool to spawn scripts that need session-aware logging or tracing
- Orchestrates multiple concurrent agent sessions and needs to correlate subprocess output

### Current workaround & its pain
The only current workaround is manually passing `env: { OPENCLAW_SESSION_ID: "..." }`
on every exec call. This requires:
1. The agent to explicitly know its own session ID (awkward self-reference)
2. Every exec call site to remember to pass it
3. Re-passing on every new conversation turn (env not persisted across turns)

### Impact if implemented
- **Zero-config**: subprocesses automatically get session context, no agent-side changes needed
- **Enables callback patterns**: scripts can call `openclaw agent --session-id $OPENCLAW_SESSION_ID`
  to send results back to the originating session
- **Better observability**: logs from subprocesses can be correlated to agent sessions trivially
- **Consistent with industry standard**: aligns with how opencode, Cursor and other
  coding agents handle session context propagation

### Severity
Low risk change (additive only, new env vars), high value for power users and
tool/skill developers building on top of OpenClaw.

### Evidence/examples

_No response_

### Additional information

_No response_

Data

Security

Network

Code

UI/UX

Text

System

Multimedia

Protocol

API

Engineering