RomanNum3ral
/
claw-code
mirror of https://github.com/instructkr/claw-code.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
claw-code/.guardrails/docs/OPENCODE_INTEGRATION.md

8.1 KiB
Raw Blame History

OpenCode Integration

This guide explains how to integrate Agent Guardrails with OpenCode using custom agents and skills.

Overview

OpenCode uses a multi-agent architecture with:

  • Configuration - JSONC file (.opencode/oh-my-opencode.jsonc)
  • Agents - Specialized workers for different tasks
  • Skills - Markdown files with YAML frontmatter
  • MCP Servers - Remote Model Context Protocol servers for guardrail enforcement

MCP Server Configuration

Remote MCP Server Setup

If you have a deployed Guardrail MCP server (see README.md MCP Server section), configure OpenCode to connect to it:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  
  "mcpServers": {
    "guardrails": {
      "type": "remote",
      "url": "http://your-server-ip:8094/mcp/v1/sse",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}

Configuration Details:

Field Description Example
type Must be "remote" for external MCP servers "remote"
url SSE endpoint URL with external port http://0.0.0.0:8094/mcp/v1/sse
headers.Authorization Bearer token with MCP_API_KEY Bearer JGtwbxsS2Nvy...

Important Notes:

  • Use the external port (e.g., 8094), not the internal container port (8080)
  • The Authorization header must use Bearer format
  • Do NOT use X-API-Key header - it won't work
  • Get the API key from your server's .env file (MCP_API_KEY variable)

Verifying MCP Connection

Test that OpenCode can connect to the MCP server:

# Check MCP server health
curl http://your-server:8095/health/ready

# Should return: {"status":"ready",...}

# Check version
curl http://your-server:8095/version

# Should return: {"version":"v1.12.0",...}

Setup

1. Run Setup Script

python scripts/setup_agents.py --opencode --full

This creates:

.opencode/
├── oh-my-opencode.jsonc
├── skills/
│   ├── guardrails-enforcer/
│   │   └── SKILL.md
│   ├── commit-validator/
│   │   └── SKILL.md
│   └── env-separator/
│       └── SKILL.md
└── agents/
    ├── guardrails-auditor.json
    └── doc-indexer.json

2. Verify Installation

Check the configuration:

cat .opencode/oh-my-opencode.jsonc

Check that skills exist:

ls -la .opencode/skills/*/

3. Restart OpenCode

OpenCode loads configuration on startup. Restart to apply changes.

Configuration Format

OpenCode uses JSONC (JSON with Comments):

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  // Agent definitions
  "agents": {
    "guardrails-enforcer": {
      "model": "anthropic/claude-sonnet-4",
      "temperature": 0.1,
      "prompt_append": "Additional instructions..."
    }
  },

  // Skill configuration
  "skills": {
    "enable": ["guardrails-enforcer", "commit-validator"]
  }
}

How It Works

Agents

Agents are specialized workers with:

  • model - Which LLM to use
  • temperature - Creativity vs determinism (0.0-1.0)
  • prompt_append - Additional system instructions
  • permissions - Access controls

Skills

Skills are Markdown files with YAML frontmatter:

---
name: skill-name
description: "What this skill does"
---

# Skill Title

Instructions here...

Categories

OpenCode uses cost-based categories:

Category Cost Use For
quick $ Fast queries, greps
unspecified-low Standard operations
unspecified-high $ Complex analysis
visual-engineering $ UI/UX work

Included Agents

guardrails-enforcer

Purpose: Real-time enforcement of safety rules

Configuration:

  • Model: claude-sonnet-4
  • Temperature: 0.1 (deterministic)
  • Permissions: Ask before edit/bash

Behavior:

  • Validates read-before-edit
  • Enforces scope boundaries
  • Checks for halt conditions

guardrails-auditor

Purpose: Post-execution compliance review

Configuration:

  • Model: claude-sonnet-4
  • Read-only permissions
  • No edit or bash access

Behavior:

  • Reviews completed work
  • Reports violations
  • Suggests corrections

doc-indexer

Purpose: Keeps documentation maps updated

Configuration:

  • Model: claude-haiku-4 (fast, cheap)
  • Edit permissions for docs only

Behavior:

  • Updates INDEX_MAP.md
  • Updates HEADER_MAP.md
  • Runs on document changes

Included Skills

guardrails-enforcer

Activates: All operations

Enforces:

  • Four Laws of Agent Safety
  • Pre-operation checklist
  • Halt conditions
  • Three Strikes Rule

commit-validator

Activates: Before commits

Validates:

  • AI attribution
  • Single focus
  • No secrets
  • Tests passing

env-separator

Activates: Test code creation

Enforces:

  • Production code first
  • Separate instances
  • No data mixing

Customization

Adding a Custom Agent

  1. Create a JSON file in .opencode/agents/:
{
  "name": "my-agent",
  "model": "anthropic/claude-sonnet-4",
  "temperature": 0.1,
  "prompt_append": "Your instructions...",
  "permissions": {
    "edit": "ask",
    "bash": "deny",
    "read": "allow"
  }
}
  1. Reference it in oh-my-opencode.jsonc:
{
  "agents": {
    "my-agent": {
      "model": "anthropic/claude-sonnet-4",
      // ...
    }
  }
}
  1. Restart OpenCode

Adding a Custom Skill

  1. Create a directory in .opencode/skills/:
mkdir .opencode/skills/my-skill
  1. Create SKILL.md:
---
name: my-skill
description: "What this skill does"
---

# My Skill

Instructions here...
  1. Enable in oh-my-opencode.jsonc:
{
  "skills": {
    "enable": ["guardrails-enforcer", "my-skill"]
  }
}
  1. Restart OpenCode

Advanced Configuration

Category Overrides

Change which models categories use:

{
  "categories": {
    "quick": {
      "model": "opencode/gpt-5-nano"
    },
    "visual-engineering": {
      "model": "google/gemini-3-pro"
    }
  }
}

Permission Tuning

Fine-grain agent permissions:

{
  "agents": {
    "explore": {
      "permission": {
        "edit": "deny",
        "bash": "ask",
        "webfetch": "allow"
      }
    }
  }
}

Options: allow, ask, deny

Model Parameters

Advanced model configuration:

{
  "agents": {
    "my-agent": {
      "model": "anthropic/claude-opus-4",
      "temperature": 0.1,
      "top_p": 0.9,
      "maxTokens": 4096,
      "thinking": {
        "budget_tokens": 2000
      }
    }
  }
}

Troubleshooting

Configuration Not Loading

Check:

  • JSONC syntax is valid (use a JSONC validator)
  • $schema URL is correct
  • File is at .opencode/oh-my-opencode.jsonc

Skills Not Activating

Check:

  • Skill is listed in skills.enable array
  • SKILL.md has valid YAML frontmatter
  • Skill directory name matches skill name

Agent Not Responding

Check:

  • Agent defined in agents section
  • Model identifier is valid
  • Permissions allow the operation

Best Practices

  1. Use temperature 0.1 for safety agents - More deterministic
  2. Enable skills explicitly - Don't rely on auto-discovery
  3. Set restrictive permissions - Default to ask for destructive ops
  4. Version control - Commit .opencode/ to share with team
  5. Document custom agents - Add purpose and usage notes

Differences from Claude Code

Feature Claude Code OpenCode
Config format JSON JSONC
Skills location .claude/skills/*.json .opencode/skills/*/SKILL.md
Agents Implicit Explicit definition
Hooks Shell scripts Not supported
Categories N/A Cost-based routing

References