Shell (Executor) Configuration Guide

Shell is the runtime environment container in Wegent that provides Bots with capabilities such as code execution, file operations, and tool invocation. This guide will help you understand and configure Shells.

📋 Table of Contents

What is a Shell
Shell Functions
Runtime Selection Guide
Preset Shells
Configuration Steps
YAML Configuration Reference
Configuration Examples
FAQ
Related Resources

🎯 What is a Shell

A Shell is the "body" or "execution environment" of a Bot, determining what tools and runtime capabilities the Bot can use.

Position in Bot Architecture

Bot = Ghost (Soul) + Shell (Body) + Model (Brain)

Analogy:

Ghost: A person's character and expertise
Shell: A person's body and limbs (ability to perform actions)
Model: A person's brain (thinking ability)

Database Relationship

Shell resources are stored in the following database tables:

public_shells: Stores system-provided public Shell configurations (shared across all users)
kinds: Stores user-defined custom Shell configurations (user_id specific)

Shell Resolution Order

When a Bot references a Shell, the system follows this lookup order:

User-defined Shells: First checks the kinds table for user-specific Shells in the specified namespace
Public Shells: If not found, falls back to system-provided public Shells in the public_shells table

This allows users to:

Use preset public Shells (such as Codex, ClaudeCode, and Dify) without creating them
Override public Shells by creating custom Shells with the same name
Define private Shells that only they can access

🔍 Shell Functions

Shells provide Bots with the following core capabilities:

Code Execution Environment: Run code in various programming languages
File Operations: Read/write files, manage directories
Git Integration: Version control operations
Tool Invocation: Call MCP (Model Context Protocol) tools
System Commands: Execute Bash commands

📊 Runtime Selection Guide

When creating or editing an Agent, the standard settings do not require users to understand Shells. Users first choose how the Agent will be used:

Everyday chat: For conversations, knowledge Q&A, and lightweight tasks. Wegent uses Chat.
Complex tasks and coding: For multi-step work, code changes, files, commands, and connected devices. Users then choose Codex or Claude Code.
Advanced custom: For advanced users who need a custom Shell.

Agno is being decommissioned and is no longer shown as a preset option in the web UI. Dify and other custom Shells remain available through advanced custom settings.

Codex Runtime

Use Cases:

Code development and refactoring
File operations and management
Git branch management and commits
Agentic coding and tool use with OpenAI models

Features:

✅ Supports MCP tool invocation
✅ Full filesystem access
✅ Git integration
✅ Workspace and device execution

Claude Code Runtime

Use Cases:

Code development and refactoring
File operations and management
Git branch management and commits
Coding and tool use with Anthropic models

Features:

✅ Based on Claude Agent SDK
✅ Supports MCP tool invocation
✅ Full filesystem access
✅ Git integration
✅ Workspace and device execution

Dify Runtime

Use Cases:

Integration with Dify platform applications
Workflow automation
Multi-turn conversations with external AI services
Agent-based chat applications

Features:

✅ Supports multiple Dify application modes (chat, chatflow, workflow, agent-chat)
✅ Session management for multi-turn conversations
✅ Task cancellation support
✅ Seamless integration with Dify ecosystem

Environment Variables:

DIFY_API_KEY: Your Dify API key
DIFY_BASE_URL: Dify server URL (default: https://api.dify.ai/v1)
DIFY_APP_ID: Dify application ID
DIFY_PARAMS: Additional parameters in JSON format

Recommended for: Teams using Dify for AI application development

Decision Table

Scenario	Recommended choice
Conversation, Q&A, and knowledge retrieval	Everyday chat
Coding with OpenAI models	Complex tasks and coding → Codex
Coding with Anthropic models	Complex tasks and coding → Claude Code
Dify or a private runtime	Advanced custom

🎁 Preset Shells

Wegent comes with the following preset Shells that can be used immediately:

1. Codex

Name: Codex Runtime: Codex Status: ✅ Available by default Namespace: default

Recommended Scenarios:

Code development with OpenAI models
Feature implementation and refactoring
File, command, and MCP tool operations

2. ClaudeCode

Name: ClaudeCode Runtime: ClaudeCode Status: ✅ Available by default Namespace: default

Recommended Scenarios:

Daily code development
Feature implementation
Code refactoring
Documentation writing

3. Dify

Name: Dify Runtime: Dify Status: ✅ Available Namespace: default

Recommended Scenarios:

Integration with Dify platform
Workflow automation tasks
Multi-turn conversation applications
Agent-chat interactions

🚀 Configuration Steps

Method 1: Use Preset Shells (Recommended for Beginners)

In Agent settings, standard users can choose Complex tasks and coding, then select Codex or Claude Code, without creating a Shell manually.

The system also includes preset Shells such as Codex, ClaudeCode, and Dify. You can reference them directly when creating a Bot through YAML:

apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: my-developer-bot
  namespace: default
spec:
  ghostRef:
    name: my-ghost
    namespace: default
  shellRef:
    name: Codex # Use preset Shell directly
    namespace: default
  modelRef:
    name: my-model
    namespace: default

Method 2: View Existing Shells via Web Interface

Log in to Wegent Web interface (http://localhost:3000)
Navigate to Resource Management → Shell Configuration
View the list of Shells in the system
Select an appropriate Shell for your Bot

Method 3: Create Custom Shell

If you need a custom Shell configuration:

Create via Web Interface

Log in to Wegent Web interface
Navigate to Resource Management → Shell Configuration
Click Create New Shell button
Fill in the following fields:
- Name: Unique identifier for the Shell (lowercase letters and hyphens)
- Namespace: Usually use default
- Runtime Type: Select Codex or ClaudeCode for custom local execution Shells
- Supported Model Providers: (Optional) Specify model providers this Shell supports
Click Submit to create

Configure via YAML File

Create a YAML configuration file (e.g., my-shell.yaml)
Write the configuration content (refer to YAML Configuration Reference below)
Import the configuration via Web interface or API

📝 YAML Configuration Reference

Complete Configuration Structure

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: <shell-name>
  namespace: default
spec:
  runtime: <runtime-type>
  supportModel: []
status:
  state: "Available"

Field Descriptions

metadata Section

Field	Type	Required	Description
`name`	string	Yes	Unique identifier for the Shell, use lowercase letters and hyphens
`namespace`	string	Yes	Namespace, usually use `default`

spec Section

Field	Type	Required	Description
`runtime`	string	Yes	Runtime type. Common values: `Codex`, `ClaudeCode`, `Dify`, `Chat`
`supportModel`	array	No	List of supported model providers, empty array means all models supported

supportModel Explanation:

Omitted or empty array []: Do not filter the model list by provider.
Specified list: Match the model’s spec.modelConfig.env.model, for example ["claude", "openai"]; the runtime name does not add restrictions. Blank provider values are invalid.

status Section

Field	Description
`state`	Shell status: `Available` (available), `Unavailable` (unavailable)

💡 Configuration Examples

Example 1: ClaudeCode Shell (Standard Configuration)

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: ClaudeCode
  namespace: default
spec:
  runtime: ClaudeCode
  supportModel: [] # Supports all model providers
status:
  state: "Available"

Description:

This is the preset ClaudeCode Shell configuration
Supports all types of AI models
Suitable for most development tasks

Example 2: Dify Shell

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: Dify
  namespace: default
spec:
  runtime: Dify
  supportModel: [] # Supports all model providers
status:
  state: "Available"

Description:

Preset Dify Shell configuration
Integrates with Dify platform applications
Supports chat, chatflow, workflow, and agent-chat modes
Suitable for workflow automation and multi-turn conversations

Example 3: Custom Shell (Supports Specific Models Only)

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: custom-claude-shell
  namespace: default
spec:
  runtime: ClaudeCode
  supportModel: ["claude"] # Only supports Anthropic models
status:
  state: "Available"

Description:

Custom Shell configuration
Only supports Anthropic models (Claude series)
Suitable for scenarios with specific model restrictions

Example 4: Development Environment Shell

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: dev-environment-shell
  namespace: development
spec:
  runtime: ClaudeCode
  supportModel: []
status:
  state: "Available"

Description:

Development environment dedicated Shell
Uses separate namespace development
Suitable for multi-environment management

🔧 Shell Configuration and Bot Reference

Referencing Shell in Bot

apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: my-bot
  namespace: default
spec:
  ghostRef:
    name: my-ghost
    namespace: default
  shellRef:
    name: ClaudeCode # Reference Shell
    namespace: default
  modelRef:
    name: my-model
    namespace: default

Cross-Namespace Reference

apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: my-bot
  namespace: team-a
spec:
  ghostRef:
    name: my-ghost
    namespace: team-a
  shellRef:
    name: ClaudeCode
    namespace: default # Reference Shell from default namespace
  modelRef:
    name: my-model
    namespace: team-a

⚠️ FAQ

Q1: How to view available Shells in the system?

Answer: View via the following methods:

Method 1: Web Interface

Log in to Wegent Web interface
Navigate to Resource Management → Shell Configuration
View the Shell list

Method 2: API Query

Visit http://localhost:8000/api/docs
Use Shell-related API endpoints to query

Q2: What's the difference between ClaudeCode and Dify?

Answer:

Feature	ClaudeCode	Dify
Maturity	Mature and stable	Stable
Primary Use	Code development	Workflow automation
Tool Support	Complete	Via Dify platform
Recommendation	✅ Recommended	✅ For workflows

Suggestion:

For code development tasks, use ClaudeCode
For workflow automation and Dify integration, use Dify

Q3: How to check Shell status?

Answer:

View Shell status via Web interface:

Navigate to Resource Management → Shell Configuration
Check the status column for each Shell
Available means usable, Unavailable means not usable

Q4: How to troubleshoot configuration errors?

Answer: Common errors and solutions:

Error 1: Shell status is Unavailable

Check if runtime type is correct (Codex, ClaudeCode, or Dify)
Check if configuration format complies with YAML specification
View backend logs: docker-compose logs backend

Error 2: Bot cannot use Shell

Check if Bot's Shell reference name and namespace are correct
Confirm Shell status is Available
Check if supportModel configuration restricts model providers

Error 3: Cross-namespace reference fails

Confirm Shell exists in target namespace
Check namespace name spelling is correct

Q5: How to choose supportModel?

Answer:

Use empty array [] (Recommended):

Supports all model providers
Maximum flexibility
Suitable for most scenarios

Specify model provider list:

Restricts available model providers
Suitable for scenarios with strict model requirements
Example: ["claude"] only supports Claude models

Q6: Can I modify preset Shells?

Answer:

The preset ClaudeCode Shell is a recommended configuration; it's best not to modify it.

If you need custom configuration:

Create a new Shell resource
Use a different name
Reference the newly created Shell in your Bot

Q7: Can one Shell be used by multiple Bots?

Answer: Yes! This is the recommended approach.

# Multiple Bots sharing the same Shell
---
kind: Bot
metadata:
  name: bot-1
spec:
  shellRef:
    name: ClaudeCode # Shared
    namespace: default
---
kind: Bot
metadata:
  name: bot-2
spec:
  shellRef:
    name: ClaudeCode # Shared
    namespace: default

Model Configuration Guide - Configure AI model parameters

Next Steps

Agent Settings - Configure agents and bots with Shells

Reference Documentation

Core Concepts - Understand Shell's role in the architecture
YAML Specification - Complete configuration format

💬 Get Help

Need assistance?

📖 Check FAQ
🐛 Submit GitHub Issue
💬 Join community discussions

Configure your Shell and empower your Bots with powerful execution capabilities! 🚀

📋 Table of Contents​

🎯 What is a Shell​

Position in Bot Architecture​

Database Relationship​

Shell Resolution Order​

🔍 Shell Functions​

📊 Runtime Selection Guide​

Codex Runtime​

Claude Code Runtime​

Dify Runtime​

Decision Table​

🎁 Preset Shells​

1. Codex​

2. ClaudeCode​

3. Dify​

🚀 Configuration Steps​

Method 1: Use Preset Shells (Recommended for Beginners)​

Method 2: View Existing Shells via Web Interface​

Method 3: Create Custom Shell​

Create via Web Interface​

Configure via YAML File​

📝 YAML Configuration Reference​

Complete Configuration Structure​

Field Descriptions​

metadata Section​

spec Section​

status Section​

💡 Configuration Examples​

Example 1: ClaudeCode Shell (Standard Configuration)​

Example 2: Dify Shell​

Example 3: Custom Shell (Supports Specific Models Only)​

Example 4: Development Environment Shell​

🔧 Shell Configuration and Bot Reference​

Referencing Shell in Bot​

Cross-Namespace Reference​

⚠️ FAQ​

Q1: How to view available Shells in the system?​

Q2: What's the difference between ClaudeCode and Dify?​

Q3: How to check Shell status?​

Q4: How to troubleshoot configuration errors?​

Q5: How to choose supportModel?​

Q6: Can I modify preset Shells?​

Q7: Can one Shell be used by multiple Bots?​

🔗 Related Resources​

Related Configuration Guides​

Next Steps​

Reference Documentation​

💬 Get Help​

📋 Table of Contents

🎯 What is a Shell

Position in Bot Architecture

Database Relationship

Shell Resolution Order

🔍 Shell Functions

📊 Runtime Selection Guide

Codex Runtime

Claude Code Runtime

Dify Runtime

Decision Table

🎁 Preset Shells

1. Codex

2. ClaudeCode

3. Dify

🚀 Configuration Steps

Method 1: Use Preset Shells (Recommended for Beginners)

Method 2: View Existing Shells via Web Interface

Method 3: Create Custom Shell

Create via Web Interface

Configure via YAML File

📝 YAML Configuration Reference

Complete Configuration Structure

Field Descriptions

metadata Section

spec Section

status Section

💡 Configuration Examples

Example 1: ClaudeCode Shell (Standard Configuration)

Example 2: Dify Shell

Example 3: Custom Shell (Supports Specific Models Only)

Example 4: Development Environment Shell

🔧 Shell Configuration and Bot Reference

Referencing Shell in Bot

Cross-Namespace Reference

⚠️ FAQ

Q1: How to view available Shells in the system?

Q2: What's the difference between ClaudeCode and Dify?

Q3: How to check Shell status?

Q4: How to troubleshoot configuration errors?

Q5: How to choose supportModel?

Q6: Can I modify preset Shells?

Q7: Can one Shell be used by multiple Bots?

🔗 Related Resources

Related Configuration Guides

Next Steps

Reference Documentation

💬 Get Help