Voice
Tier1 Gate
By Tier-1 Pre-Task Gate plugin for OpenClaw — mechanically enforces pre-task lesson checks via before_tool_call hook. Supports MemPalace, local docs, and online handbook lookups.
Install
npm install
npmConfiguration Example
{
"plugins": {
"entries": {
"tier1-gate": {
"config": {
"enabled": true,
"gatedTools": ["exec", "ssh-manager", "cygnus-ssh"],
"checkTools": ["mempalace_search", "read", "mempalace__mempalace_search"],
"bypassSenderIds": ["<your-sender-id>"]
}
}
}
}
}README
# Tier-1 Gate Plugin
**Mechanical pre-task gate for OpenClaw agents.**
[](https://www.gnu.org/licenses/agpl-2.0)
## Problem
Agents with extensive `SOUL.md` rules (e.g., "search MemPalace before any task") often skip those rules mid-task due to urgency bias. The rules exist on paper but aren't enforced mechanically.
Result: 45-minute loops of assumptions and trial-and-error that a single MemPalace search or documentation lookup would have prevented.
## Solution
This plugin blocks configured tool calls (`exec`, `ssh-manager.*`, `cygnus-ssh.*`) until the agent has performed at least one **Tier-1 check** in the current session:
- **MemPalace search** — semantic search across agent memory drawers
- **Documentation read** — reading local doc files (`.md`, manuals, handbooks)
- **Online handbook lookup** — fetching vendor docs via `curl`, `obscura`, `agent-browser`, or web search
The gate runs in the OpenClaw harness via the `before_tool_call` typed plugin hook — the agent cannot bypass it via prompt reasoning or "I know this already" internal monologue.
## How it works
```
Agent receives task
│
▼
Agent calls exec / ssh-manager / cygnus-ssh
│
▼
┌─────────────────────────────────┐
│ before_tool_call hook fires │
│ Check: Tier-1 check done in │
│ this session? │
└─────────────────────────────────┘
│ │
YES NO
│ │
▼ ▼
Tool runs Tool BLOCKED
blockReason: "Tier-1 Check fehlt..."
│
▼
Agent performs MemPalace search,
reads docs, or fetches online handbook
│
▼
after_tool_call hook marks
Tier-1 check as satisfied
│
▼
Agent retries exec — now passes
```
### Gated Tools (blocked until check passes)
- `exec` (shell commands)
- `ssh-manager.*` (MCP SSH manager tools)
- `cygnus-ssh.*` (MCP Cygnus SSH tools)
- Configurable via `gatedTools`
### Tier-1 Check Tools (satisfy the gate)
**Memory & knowledge:**
- `mempalace_search` — semantic search across MemPalace drawers
- `mempalace__mempalace_search` — MCP-namespaced variant
- `read` — only counts when path looks like documentation (`.md`, manuals, handbooks, README)
**Online lookups (via `exec`):**
- `obscura fetch <url>` — anti-detection browser, good for JS-heavy sites
- `agent-browser <url>` — simple browser for straightforward pages
- `curl <url>` — direct HTTP fetch (counts when URL contains doc-like patterns)
- `wget <url>` — download (same URL heuristic as curl)
- `langsearch <query>` — web search via LangSearch API
URL patterns that count as documentation: `docs.`, `documentation`, `manual`, `handbook`, `readme`, `wiki`, `guide`, `reference`, `/help/`, `learn.`, plus known vendor domains (ubuntu.com, debian.org, redhat.com, kernel.org, vyos.io, proxmox.com, openclaw.ai, github.com, stackoverflow.com, man7.org, gnu.org).
### Allowlisted Commands (never blocked inside `exec`)
Read-only quick checks that don't benefit from pre-task research:
`ls`, `pwd`, `whoami`, `id`, `date`, `uptime`, `df`, `du`, `free`, `cat`, `head`, `tail`, `grep`, `find`, `file`, `stat`, `wc`, `echo`, `printf`, `systemctl status`, `journalctl`
### Session Scope
Gate state is per-session (by `sessionKey`). Resets on session end, gateway restart, or `/new`.
## Configuration
```json
{
"plugins": {
"entries": {
"tier1-gate": {
"config": {
"enabled": true,
"gatedTools": ["exec", "ssh-manager", "cygnus-ssh"],
"checkTools": ["mempalace_search", "read", "mempalace__mempalace_search"],
"bypassSenderIds": ["<your-sender-id>"]
}
}
}
}
}
```
| Option | Type | Default | Description |
|---|---|---|---|
| `enabled` | boolean | `true` | Enable/disable the gate |
| `gatedTools` | string[] | `["exec", "ssh-manager", "cygnus-ssh"]` | Tool names that are blocked until Tier-1 check passes |
| `checkTools` | string[] | `["mempalace_search", "read", "mempalace__mempalace_search"]` | Tool names that satisfy the Tier-1 check |
| `bypassSenderIds` | string[] | `[]` | Sender IDs that bypass the gate (e.g., owner) |
## Install
### From source (local development)
```bash
git clone https://github.com/0n1cOn3/openclaw-tier1-gate.git
cd openclaw-tier1-gate
npm install
npm run build
```
### Link into OpenClaw (recommended for development)
```bash
openclaw plugins install --link ./openclaw-tier1-gate
openclaw gateway restart
```
### Or install as copy
```bash
openclaw plugins install ./openclaw-tier1-gate
openclaw gateway restart
```
## Verification
After install + restart:
```bash
openclaw plugins list | grep tier1
```
Expected:
```
Tier-1 Gate | tier1-gate | enabled | .../dist/index.js | 0.1.0
```
## Rationale
### Why mechanical enforcement?
Prompt-level rules ("search before you act") rely on the agent choosing to follow them. Under time pressure or mid-task urgency, agents skip them. A harness-level block cannot be rationalized away — the agent is physically prevented from proceeding until the check is done.
### Why not just a stronger SOUL.md rule?
Because the problem isn't missing knowledge — it's missing execution discipline. Another rule in SOUL.md is another rule that can be skipped. The gate makes the rule structural, not behavioral.
### Why the allowlist?
Trivial read-only commands (`ls`, `cat`, `df`) don't benefit from pre-task research. Blocking them would create noise and friction without value. The allowlist keeps the gate targeted at state-mutating operations.
### Why include online handbooks?
Local memory and MemPalace cover past lessons, but they don't help with new software versions, unfamiliar CLI syntax, or vendor-specific documentation. Online handbook lookups (vendor docs, manpages, Stack Overflow) are equally critical for pre-task research.
## Use cases
- **VyOS configuration changes** — check VyOS docs first, not guess CLI syntax
- **Kernel parameter tuning** — consult kernel.org or vendor docs before `sysctl`
- **Proxmox VM operations** — verify API syntax in Proxmox docs before scripting
- **Package installation** — search for known issues or CVEs before `apt install`
- **SSH/SSH key operations** — verify the correct procedure (ssh-keygen, authorized_keys format) before touching configs
## Related
### OpenClaw documentation
- [Plugin hooks](https://docs.openclaw.ai/en/rolling/plugins/hooks) — `before_tool_call`, `after_tool_call`, `session_end`
- [Building plugins](https://docs.openclaw.ai/en/rolling/plugins/building-plugins) — `definePluginEntry` reference
- [Plugin entry points](https://docs.openclaw.ai/en/rolling/plugins/sdk-entrypoints) — SDK entry point reference
### Companion tools (MCP servers)
This plugin works well alongside these MCP servers that provide Tier-1 check surfaces:
- **[MemPalace](https://github.com/openclaw/mempalace)** — semantic memory drawers, `mempalace_search` tool
- **[ssh-manager](https://github.com/bvisible/mcp-ssh-manager)** — SSH operations (gated by this plugin)
- **[cygnus-ssh](https://github.com/cygnussystems/cygnus-ssh-mcp)** — advanced SSH operations (gated by this plugin)
- **[ProxmoxMCP](https://github.com/canvrno/ProxmoxMCP)** — Proxmox VE integration
### Inspiration
- Self-Optimization Protocol (Tier 1: Pre-Task Lesson Check) — agent operating manual pattern
- Repetitive Error Trigger rule — "search memory before attempting known-difficult tasks"
## License
GNU Affero General Public License v2.0 — see [LICENSE](LICENSE).
This ensures that all modifications and network-facing deployments contribute back to the community.
voice
Comments
Sign in to leave a comment