Phy OpenClaw Multibot Audit

audit any openclaw telegram bot for multi-tenant security issues. based on real production incidents from deploying multiple openclaw telegram bots to public users.

intent

run a security audit on an openclaw telegram bot serving multiple users. this skill walks through 15 critical configuration checks (session isolation, filesystem sandboxing, exec restrictions, auth file handling, error output filtering, and more) that prevent data leakage across users. use this before launching any public bot, after adding multi-user support to an existing bot, during security review of any openclaw gateway serving multiple users, or when you suspect cross-user data leakage. the skill is based on openclaw's own security model: "openclaw is NOT a hostile multi-tenant security boundary for multiple adversarial users." any public telegram bot with open dm policy IS a mixed-trust scenario, so proper isolation is mandatory.

inputs

external connections:

• openclaw gateway (version 1.0+): must be deployed and accessible for config inspection
• env var OPENCLAW_PROFILE_DIR: path to openclaw profile directory (default: /root/.openclaw-PROFILE)
• env var BOT_WORKSPACE_ROOT: path to bot workspace (default: /workspaces)
• bash, grep, python capable execution environment

context needed:

• bot directory with these files present: config/openclaw.json, provision-user.sh, entrypoint.sh, SOUL.md, AGENTS.md or template
• at least one deployed user agent (for testing config persistence)
• access to read config files and script contents
• optional: test telegram user IDs for validation checks

edge cases to handle:

• missing config files (skip that check, mark N/A)
• multiline json strings (grep will miss them, require manual inspection)
• symlink loops in workspace (could hang during traversal)
• concurrent provisioning processes (may lock audit script)
• auth-profiles.json missing or malformed (audit still runs, flags as FAIL)

procedure

step 1: extract and validate session isolation setting

input: config/openclaw.json process:

grep -o '"dmScope"[^,}]*' config/openclaw.json

output: one line containing "dmScope": "per-channel-peer" or "dmScope": "per-account-channel-peer" or similar, or no match if missing. pass condition: match found AND value is per-channel-peer or per-account-channel-peer. failure means all users share the same conversation context.

step 2: check filesystem tool isolation in agent config

input: config/openclaw.json, provision-user.sh process:

grep -o '"workspaceOnly"[^,}]*' config/openclaw.json provision-user.sh

output: list of all occurrences with values (true/false). count occurrences of true. pass condition: at least 2 entries with "workspaceOnly": true (one for fs tools, one for exec.applyPatch). if present in provision-user.sh but not in config, mark as manual enforcement. note: workspaceOnly blocks read/write/edit/apply_patch but does NOT block exec shell commands.

step 3: validate exec sandbox mode (the hard problem)

input: config/openclaw.json process:

grep -A5 '"sandbox"' config/openclaw.json | grep -o '"mode"[^,}]*' | head -1

output: line with mode value or empty if not set. pass condition: mode is all with scope agent or session. if mode is missing or set to none, this is a gap. document trade-off: container per agent costs 50-100MB RAM per user (acceptable for <50 users, expensive for 500+).

step 4: confirm auth-profiles.json is copied to user agents

input: provision-user.sh, entrypoint.sh, filesystem check process:

grep -n 'auth-profiles.json' provision-user.sh entrypoint.sh
ls -la "${OPENCLAW_PROFILE_DIR}/agents/user-"*/agent/auth-profiles.json 2>/dev/null | wc -l

output: line numbers in scripts where copy happens, plus count of actual auth files in deployed agents. pass condition: both provision-user.sh and entrypoint.sh contain at least one cp or cp -f command that targets auth-profiles.json. AND at least one deployed user agent has the file. if missing from entrypoint.sh, user agents will be silent after container restart.

step 5: verify workspaceOnly re-applied after entrypoint restart

input: entrypoint.sh, config/openclaw.json process:

grep -A20 'openclaw agents add' entrypoint.sh | grep -c 'workspaceOnly'

output: count of workspaceOnly enforcement after re-registration. pass condition: at least 1 match. if zero, workspaceOnly setting may be lost on restart. check if re-apply logic exists in python block.

step 6: validate telegram user id as numeric only

input: provision-user.sh process:

grep -n 'TELEGRAM_USER_ID' provision-user.sh | grep -E '\[\[|=~|\^[0-9]'

output: line numbers where validation regex is applied. pass condition: at least one line contains regex check like ^[0-9]+$. if missing, path traversal via user_id=../../etc/passwd is possible.

step 7: check workspace directory permissions

input: provision-user.sh, filesystem check process:

grep -n 'chmod 700' provision-user.sh
stat -c '%a' "${BOT_WORKSPACE_ROOT}"/[0-9]* 2>/dev/null | sort | uniq

output: line number in script, plus list of actual octal permissions on deployed workspaces. pass condition: script contains chmod 700 for user workspace. AND all deployed workspaces show 700 permissions (read-write-execute for owner only). if permissions are 755 or higher, other container processes can read user data.

step 8: confirm flock and idempotency in provisioning

input: provision-user.sh process:

grep -n 'flock' provision-user.sh
grep -n 'if.*provisioned\|if.*-f.*workspace' provision-user.sh

output: line numbers for flock and idempotency checks. pass condition: both flock (file locking) and idempotency check (skip if already provisioned) present. if missing, concurrent messages from same user could corrupt workspace.

step 9: verify error messages are wrapped safely

input: workspace-shared/skills//scripts/.py, generate.py, any user-facing scripts process:

find . -name '*.py' -type f | xargs grep -l 'Exception\|except' | while read f; do
  grep -A2 'except.*:' "$f" | grep -c 'GENERATION_FAILED\|safe.*signal'
done

output: count of safe error signals found across all scripts. pass condition: all user-facing scripts catch exceptions and output safe signal like GENERATION_FAILED to stdout (never raw API errors, stack traces, or {"error":{"code":500}}). check AGENTS.md instructs agent to never forward raw error text.

step 10: audit secrecy protocol (SOUL.md and AGENTS.md)

input: SOUL.md, AGENTS.md or template process:

grep -i 'model.*name\|gpt\|gemini\|claude\|api.*key\|cost\|price' SOUL.md AGENTS.md | head -10
grep -i 'message-guard\|output.*filter\|separate.*llm' SOUL.md AGENTS.md

output: list of any exposed terms, plus presence of message-guard or output filter. pass condition: no model names, api keys, costs, or provider names visible. agent uses single identity statement and redirects on refusal (never explains constraints). message-guard hook mentioned as Layer 2 defense.

step 11: confirm shared resources are symlinked

input: provision-user.sh, deployed user workspaces process:

grep -n 'ln -s\|symlink' provision-user.sh
ls -la "${BOT_WORKSPACE_ROOT}"/[0-9]*/SOUL.md 2>/dev/null | head -3

output: line numbers of symlink commands in script, plus first 3 symlink targets in deployed workspaces. pass condition: provision-user.sh contains symlinks for shared files (SOUL.md, skills/, hooks/). deployed SOUL.md entries show -> (symlink indicator). per-user files (USER.md, AGENTS.md, MEMORY.md) are regular files (not symlinks).

step 12: check registry file exists and contains user list

input: ${BOT_WORKSPACE_ROOT}/_registry.json process:

test -f "${BOT_WORKSPACE_ROOT}/_registry.json" && echo "exists" || echo "missing"
grep -o '"[0-9]\{5,\}"' "${BOT_WORKSPACE_ROOT}/_registry.json" 2>/dev/null | wc -l

output: existence check, plus count of numeric user IDs in registry. pass condition: registry file exists and contains at least 1 user ID. note gap: exec commands can still cat this file, but workspaceOnly blocks fs tools from reading it.

step 13: verify AGENTS.md.template syncs on restart

input: entrypoint.sh, AGENTS.md.template process:

grep -n 'AGENTS.md.template' entrypoint.sh
test -f AGENTS.md.template && echo "template exists" || echo "missing"

output: line numbers where template is synced, plus template existence check. pass condition: both entrypoint.sh contains logic to sync template to all user workspaces (loop over /workspaces/[0-9]*) AND AGENTS.md.template file exists in bot directory. if missing, users keep stale instructions after bot update.

step 14: validate background exec timeout

input: config/openclaw.json process:

grep -o '"backgroundMs"[^,}]*' config/openclaw.json

output: line with backgroundMs value or empty if not set. pass condition: backgroundMs is >= 120000 (120 seconds) for ai image/video generation. if missing or set to default 10000, generation will timeout mid-flight.

step 15: audit media path security

input: workspace-shared/skills//scripts/.py, any media-generating scripts process:

grep -n '/tmp/\|MEDIA:\|OUTPUT_PATH' workspace-shared/skills/*/scripts/*.py 2>/dev/null | head -10
grep -i 'file://\|mime' workspace-shared/skills/*/scripts/*.py 2>/dev/null | head -5

output: list of media path references, plus any MIME or file:// format strings. pass condition: all generated media paths are hardcoded and point to /tmp/ (openclaw allowed dir). no agent-provided paths. MEDIA: format is plain path (no MIME prefix, no file:// scheme).

decision points

if session.dmScope is missing or not per-channel-peer:

• mark as FAIL. all users share context. either add "session": {"dmScope": "per-channel-peer"} to openclaw.json or stop serving multiple users from same agent.

if workspaceOnly is missing from fs tools:

• mark as FAIL for filesystem tool isolation layer. document: users can read/write files outside their workspace via tools. mitigation: only add 100% trusted users, or add sandbox.mode "all".

if sandbox.mode is missing or "none":

• mark as FAIL for exec isolation. mark as intentional gap if <50 users and Layer 2 (SOUL.md) is strong. document: users CAN execute arbitrary shell commands and access any file on host. for true adversarial isolation, require sandbox.mode "all" or separate gateways per user.

if auth-profiles.json is not copied in entrypoint.sh:

• mark as FAIL for recovery. user agents will be unable to send messages after container restart (silent failure). add copy logic to entrypoint.sh.

if workspaceOnly is not re-applied after entrypoint restart:

• mark as FAIL for config persistence. openclaw agents add may overwrite tool config. add re-apply block after agent registration loop.

if user id validation is missing:

• mark as FAIL for input validation. path traversal via user_id=../../etc/passwd is possible. add numeric regex check to provision-user.sh before using TELEGRAM_USER_ID in paths.

if workspace permissions are not 700:

• mark as FAIL for permission isolation. other processes in container can read user data. run chmod 700 ${USER_DIR} in provision-user.sh.

if flock is missing:

• mark as FAIL for concurrency safety. two simultaneous provisioning calls can corrupt workspace. add flock and idempotency check.

if error handling is not wrapping exceptions:

• mark as FAIL for output sanitization. raw API errors and stack traces leak to users via telegram. add try/except blocks in all scripts, output safe signal to stdout only.

if model names, costs, or api keys are visible in SOUL.md or AGENTS.md:

• mark as FAIL for secrecy protocol. add internal/external split to AGENTS.md, remove all exposed terms from user-facing sections. ensure message-guard hook is configured.

if shared resources are copied instead of symlinked:

• mark as FAIL for update safety. per-user copies means manual sync on every bot update. require symlinks for SOUL.md, skills/, hooks/.

if AGENTS.md.template is not synced on restart:

• mark as FAIL for instruction freshness. users keep stale or outdated bot instructions after container restarts.

if backgroundMs is missing or <120000:

• mark as WARN (not FAIL) for generation timeout. image/video generation may timeout. increase to 120000 (120 seconds) minimum for ai workloads.

if media paths are not hardcoded or use file:// or MIME prefixes:

• mark as FAIL for media delivery. images may not render in telegram, or paths may be bypassable. require hardcoded /tmp/ paths, plain format.

output contract

format: structured audit report (text or json).

data structure:

{
  "audit_date": "2025-01-20T14:30:00Z",
  "bot_name": "<bot_name_from_config>",
  "bot_workspace": "<path>",
  "openclaw_profile": "<path>",
  "checks": [
    {
      "id": 1,
      "name": "session isolation",
      "status": "PASS|FAIL|N/A",
      "finding": "<brief result>",
      "remediation": "<action if FAIL>"
    },
    ...
  ],
  "summary": {
    "pass_count": 12,
    "fail_count": 2,
    "na_count": 1,
    "critical_failures": ["sandbox isolation"],
    "risk_level": "low|medium|high"
  },
  "3_layer_defense": {
    "layer_1_fs_isolation": "PASS|FAIL",
    "layer_2_soul_agents": "PASS|FAIL",
    "layer_3_message_guard": "PASS|N/A"
  },
  "remediation_priority": [
    "IMMEDIATE: <failure>",
    "BEFORE_LAUNCH: <failure>",
    "OPTIONAL: <warning>"
  ]
}

file location: audit report written to stdout or to ./audit-report-<timestamp>.json if -o flag is used.

content detail: each check includes finding (what was found), expected value (what should be), actual value (what is), and remediation (how to fix).

outcome signal

• exit code 0: all checks passed, bot is safe to launch.
• exit code 1: one or more critical failures (e.g., missing session isolation, no sandbox, no error wrapping). do not launch until remediated.
• exit code 2: warnings only (e.g., timeout too low, registry not found). bot is launchable but review issues before going public.
• stdout: audit report printed in human-readable or json format.
• visible markers in output:
  • [PASS] in green: protection is configured correctly.
  • [FAIL] in red: protection missing or misconfigured. blocks launch.
  • [WARN] in yellow: protection weak but not blocking (e.g., timeout too low, no message-guard).
  • [N/A] in gray: check skipped (file not found, feature disabled).
• bottom-line risk assessment: if all 15 checks pass, bot is safe for <50 multi-user deployment with openclaw's stated limitations. if any of checks 1, 3, 5, 6, 7, 8, 9 fail, do not launch.

---

quick audit command

to audit a bot directory in one shot, run from bot root:

#!/bin/bash
echo "=== session isolation ==="
grep -o '"dmScope"[^,}]*' config/openclaw.json

echo "=== background timeout ==="
grep -o '"backgroundMs"[^,}]*' config/openclaw.json

echo "=== user id validation ==="
grep -c '\^[0-9]' provision-user.sh && echo "pass" || echo "fail"

echo "=== auth copy in entrypoint ==="
grep -c 'auth-profiles.json' entrypoint.sh && echo "pass" || echo "fail"

echo "=== workspaceOnly isolation ==="
grep -c 'workspaceOnly.*true' provision-user.sh entrypoint.sh && echo "pass" || echo "fail"

echo "=== error handling ==="
find . -name '*.py' -type f | xargs grep -l 'GENERATION_FAILED' 2>/dev/null | wc -l

echo "=== chmod 700 workspace ==="
grep -c 'chmod 700' provision-user.sh && echo "pass" || echo "fail"

echo "=== flock and idempotency ==="
grep -c 'flock' provision-user.sh && echo "pass" || echo "fail"

echo "=== symlinks for shared resources ==="
ls -la "$(pwd)"/[0-9]*/SOUL.md 2>/dev/null | grep -c '\->' && echo "pass" || echo "fail"

echo "=== registry exists ==="
test -f _registry.json && echo "pass" || echo "fail"

all echo outputs should show "pass" or non-zero count. zero = missing protection.

reference: production incidents

incident	impact	root cause	fix
raw 500 error in telegram	users see {"error":{"code":500}} in chat	no exception wrapping in generate.py	catch all exceptions, output safe stdout signal only
buttons appear before image	confusing ux, users tap empty buttons	message send fires instantly, media upload is slow (3s)	add sleep 3 between MEDIA: line and button markup
agent makes excuses	"network issues" when image missing	no instructions for missing image case	explicit "image not available" handling in AGENTS.md
agent uses wrong output path	images never delivered	agent improvises cli args	hardcode all paths in script, ignore agent-provided input
model names leaked in welcome	users see "Gemini 3 Flash + NB2" in welcome	AGENTS.md exposes model list	secrecy protocol: separate internal/external docs, no model names in user-facing text
all users share context	private messages visible to others	missing per-channel-peer session scope	set "session": {"dmScope": "per-channel-peer"}
user agents silent after restart	agent registered but no auth file	openclaw agents add does not create auth-profiles.json	copy auth-profiles.json from main agent to user agent in entrypoint.sh
concurrent provisioning race	workspace corrupted, agent unresponsive	two provisioning calls at same time	use flock and idempotency check in provision-user.sh
cross-user file read (exec bypass)	user a reads /workspaces/b/USER.md	workspaceOnly does not block exec commands	require sandbox.mode all or separate gateways for adversarial users
registry enumeration	attacker lists all user ids	any agent can read _registry.json via exec	mitigate: document gap, rely on message-guard to filter output

---

3-layer defense model

for public bots where full sandbox is too expensive, use these three layers:

layer	what	blocks	gap
1. tools.fs.workspaceOnly	platform enforcement in agent config	read/write/edit/apply_patch outside workspace	does NOT block exec shell commands
2. SOUL.md + AGENTS.md	behavioral rules and instructions	agent refuses voluntarily to access other users' files	bypassable via prompt injection or role-play
3. message-guard hook	separate llm evaluates outbound messages	leaked secrets in chat output	only catches output, not file access. separate service needed

recommendation for true adversarial isolation: "sandbox": {"mode": "all", "scope": "agent"} (container per agent, ~50-100MB per user) or separate openclaw gateways + credentials for each user group. do not rely on layers 1-2 alone for hostile multi-tenant.

---

author: canlah ai , run performance marketing without breaking your brand.

• github: github.com/PHY041
• all skills: clawhub.ai/PHY041