YAML Configuration Formats

English | 简体中文

This document provides detailed explanations of the YAML configuration formats for each core concept in the Wegent platform. Each definition follows Kubernetes-style declarative API design patterns.

Table of Contents

• 👻 Ghost
• ✨ Skill
• 🧠 Model
• 🐚 Shell
• 🖥 Device
• 🤖 Bot
• 👥 Team
• 🤝 Collaboration
• 💼 Workspace
• 🎯 Task
• 📚 KnowledgeBase
• 🔌 ConnectorApp

---

👻 Ghost

Ghost defines the "soul" of an agent, including personality, capabilities, and behavior patterns.

Complete Configuration Example

apiVersion: agent.wecode.io/v1
kind: Ghost
metadata:
  name: developer-ghost
  namespace: default
spec:
  systemPrompt: |
    You are a senior software engineer, proficient in Git, GitHub MCP, branch management, and code submission workflows. You will use the specified programming language to generate executable code and complete the branch submission and MR (Merge Request) process.
  mcpServers:
    github:
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ghp_xxxxx
      args:
        - run
        - -i
        - --rm
        - -e
        - GITHUB_PERSONAL_ACCESS_TOKEN
        - -e
        - GITHUB_TOOLSETS
        - -e
        - GITHUB_READ_ONLY
        - ghcr.io/github/github-mcp-server
      command: docker

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Ghost
metadata.namespace	string	Yes	Namespace, typically default
spec.systemPrompt	string	Yes	System prompt defining agent personality and capabilities
spec.mcpServers	object	No	MCP server configuration defining agent's tool capabilities
spec.skills	array	No	List of Skill names to associate with this Ghost, e.g., ["skill-1", "skill-2"]

---

✨ Skill

Skill is a Claude Code capability extension package containing executable code and configuration. Skills are uploaded as ZIP packages and deployed to ~/.claude/skills/ when tasks start.

Complete Configuration Example

apiVersion: agent.wecode.io/v1
kind: Skill
metadata:
  name: python-debugger
  namespace: default
spec:
  description: "Python debugging tool with breakpoint and variable inspection support"
  version: "1.0.0"
  author: "WeCode Team"
  tags: ["python", "debugging", "development"]
status:
  state: "Available"
  fileSize: 2048576
  fileHash: "abc123def456..."

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Skill (used in Ghost spec.skills field)
metadata.namespace	string	Yes	Namespace, typically default
spec.description	string	Yes	Skill功能描述 (extracted from SKILL.md frontmatter)
spec.version	string	No	Version number (semantic versioning recommended)
spec.author	string	No	Author name or organization
spec.tags	array	No	Tags for categorization, e.g., ["python", "debugging"]
status.state	string	Yes	Skill status: Available or Unavailable
status.fileSize	integer	No	ZIP package size in bytes
status.fileHash	string	No	SHA256 hash of the ZIP package

ZIP Package Requirements

Skills must be uploaded as ZIP packages containing:

1. SKILL.md (required): Skill documentation with YAML frontmatter
2. Other files: Scripts, configurations, assets, etc.

SKILL.md Format:

---
description: "Your skill description here"
version: "1.0.0"
author: "Your Name"
tags: ["tag1", "tag2"]
---

# Skill Documentation

Detailed description of what this skill does...

Using Skills in Ghosts

Associate skills with a Ghost by adding them to the spec.skills array:

apiVersion: agent.wecode.io/v1
kind: Ghost
metadata:
  name: developer-ghost
  namespace: default
spec:
  systemPrompt: "You are a senior developer..."
  mcpServers: { ... }
  skills:
    - python-debugger
    - code-formatter

When a task starts with this Ghost, the Executor automatically downloads and deploys these skills to ~/.claude/skills/.

🧠 Model

Model defines the AI model configuration, including environment variables and model parameters.

Complete Configuration ClaudeCode Example

apiVersion: agent.wecode.io/v1
kind: Model
metadata:
  name: ClaudeSonnet4
  namespace: default
spec:
  modelGroup: "Primary"
  modelSubGroup: "Fast"
  modelConfig:
    env:
      ANTHROPIC_MODEL: "openrouter,anthropic/claude-sonnet-4"
      ANTHROPIC_BASE_URL: "http://xxxxx"
      ANTHROPIC_AUTH_TOKEN: "sk-xxxxxx"
      ANTHROPIC_DEFAULT_HAIKU_MODEL: "openrouter,anthropic/claude-haiku-4.5"

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Model
metadata.namespace	string	Yes	Namespace, typically default
spec.modelGroup	string	No	First-level display group used by model selectors
spec.modelSubGroup	string	No	Second-level display group under spec.modelGroup
spec.modelConfig	object	Yes	Model configuration object
spec.modelConfig.env	object	Yes	Environment variables configuration
spec.protocol	string	No	Upstream protocol (openai, openai-responses, claude, ...). Inferred from env.model when omitted.
spec.apiFormat	string	No	Upstream API format (responses, chat/completions, ...). Derived from spec.protocol when omitted.
spec.isWeworkAvailable	boolean	No	Whether the model is distributed to the wework desktop client.

Model Selector Grouping

Model selectors display models as modelGroup → modelSubGroup → model. These fields are stored in spec, not metadata.labels, so grouping is part of the Model resource definition. Models without these fields are shown under the default ungrouped/uncategorized buckets. Grouping only affects display and search behavior; it does not change model protocol, credentials, permissions, or runtime selection.

Common Environment Variables for ClaudeCode

Variable Name	Description	Example Value
ANTHROPIC_MODEL	Main model configuration	openrouter,anthropic/claude-sonnet-4
ANTHROPIC_BASE_URL	API base URL	http://xxxxx
ANTHROPIC_AUTH_TOKEN	Authentication token	sk-xxxxxx
ANTHROPIC_DEFAULT_HAIKU_MODEL	Fast model configuration	openrouter,anthropic/claude-haiku-4.5

---

🐚 Shell

Shell defines the agent's runtime environment, specifying the runtime type, base image, and supported models.

Complete Configuration Example

apiVersion: agent.wecode.io/v1
kind: Shell
metadata:
  name: ClaudeCode
  namespace: default
  labels:
    type: local_engine
spec:
  shellType: ClaudeCode
  supportModel: []
  baseImage: ghcr.io/wecode-ai/wegent-base-python3.12:1.0.1
status:
  state: Available

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Shell
metadata.namespace	string	Yes	Namespace, typically default
metadata.labels	object	No	Labels for categorization, e.g., type: local_engine or type: external_api
spec.shellType	string	Yes	Shell type, such as ClaudeCode, Agno, Dify
spec.supportModel	array	No	List of supported model types
spec.baseImage	string	No	Docker base image for local engine shells (required for local_engine type)
status.state	string	No	Shell status: Available or Unavailable

Shell Types

Type	Label	Description
ClaudeCode	local_engine	Claude Code runtime, requires baseImage
Agno	local_engine	Agno runtime, requires baseImage
Dify	external_api	Dify external API runtime, no baseImage needed

Labels

Label	Values	Description
type	local_engine, external_api	Indicates whether the shell runs locally or connects to external API

---

🖥 Device

Device defines an execution device. Device records are usually created automatically by the local executor, cloud device service, or remote Docker device entrypoint. Users normally should not create them by hand.

Remote Docker Device Example

apiVersion: agent.wecode.io/v1
kind: Device
metadata:
  name: 7b7c9d64-xxxx-xxxx-xxxx-3f70c6f4a931
  namespace: default
  displayName: alice-remote-a931
spec:
  deviceId: 7b7c9d64-xxxx-xxxx-xxxx-3f70c6f4a931
  displayName: alice-remote-a931
  deviceType: remote
  connectionMode: websocket
  bindShell: claudecode
  isDefault: false
  capabilities: null
  remoteConfig:
    provider: docker
    image: ghcr.io/wecode-ai/wegent-device:latest
    deviceId: 7b7c9d64-xxxx-xxxx-xxxx-3f70c6f4a931
    deviceName: alice-remote-a931
    backendUrl: https://backend.example.com
    publicBaseUrl: http://localhost:17888
    createdAt: "2026-06-17T10:00:00"
status:
  state: Available

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Device resource name, usually the same as spec.deviceId
metadata.namespace	string	Yes	Namespace, typically default
spec.deviceId	string	Yes	Device ID used by executor registration and heartbeat
spec.displayName	string	No	Display name in the frontend
spec.deviceType	local, cloud, remote	Yes	Device type; remote means a user-managed Docker container or remote host
spec.connectionMode	websocket	Yes	How the device connects to the backend
spec.bindShell	claudecode, openclaw	No	Shell runtime bound to the device
spec.isDefault	boolean	No	Whether this is the default device for its type
spec.capabilities	array or null	No	Device capability tags
spec.cloudConfig	object	No	Cloud device metadata, used only by cloud devices
spec.remoteConfig	object	No	Remote device metadata, used only by remote devices

remoteConfig stores only non-sensitive metadata. The WEGENT_AUTH_TOKEN returned in the remote Docker startup command is a newly created remote device API key and is not written to the Device CRD. backendUrl is the URL the container uses to reach Backend and is derived from the current Backend environment; publicBaseUrl is the browser-facing URL for the device session gateway.

---

🤖 Bot

Bot is a complete agent instance that combines Ghost, Shell, and Model.

Complete Configuration Example

apiVersion: agent.wecode.io/v1
kind: Bot
metadata:
  name: developer-bot
  namespace: default
spec:
  ghostRef:
    name: developer-ghost
    namespace: default
  shellRef:
    name: ClaudeCode
    namespace: default
  modelRef:
    name: ClaudeSonnet4
    namespace: default

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Bot
metadata.namespace	string	Yes	Namespace, typically default
spec.ghostRef	object	Yes	Ghost reference
spec.shellRef	object	Yes	Shell reference
spec.modelRef	object	Yes	Model reference

Reference Format

All references follow the same format:

name: "resource-name"
namespace: "default"

---

👥 Team

Team defines a collaborative team of multiple Bots, specifying member roles and collaboration patterns.

Complete Configuration Example for ClaudeCode Model

apiVersion: agent.wecode.io/v1
kind: Team
metadata:
  name: dev-team
  namespace: default
spec:
  members:
    - role: "leader"
      botRef:
        name: developer-bot
        namespace: default
      prompt: ""
      contextPassing: "previous_bot"
  collaborationModel: "pipeline"

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Team
metadata.namespace	string	Yes	Namespace, typically default
spec.members	array	Yes	List of team members
spec.collaborationModel	string	Yes	Collaboration model

Member Configuration

Field	Type	Required	Description
role	string	No	Member role, such as leader
botRef	object	Yes	Bot reference
prompt	string	No	Member-specific prompt
contextPassing	string	No	Message passed to the next pipeline stage after this stage completes: none, original_user, previous_bot, original_and_previous

Collaboration Models

Model	Description
pipeline	Pipeline mode, execute in sequence
route	Route mode, route based on conditions
coordinate	Coordinate mode, members coordinate
collaborate	Concurrent mode, members execute simultaneously

---

📚 KnowledgeBase

KnowledgeBase is used to manage document knowledge bases, retrieval configuration, and summary capabilities.

Retrieval Configuration

Field	Type	Required	Description
spec.retrievalConfig	object	No	RAG retrieval configuration. Missing or null means the knowledge base has no RAG configuration
spec.retrievalConfig.retriever_name	string	Yes*	Retriever name
spec.retrievalConfig.retriever_namespace	string	No	Namespace where the retriever is defined, defaults to default
spec.retrievalConfig.embedding_config.model_name	string	Yes*	Embedding model name
spec.retrievalConfig.embedding_config.model_namespace	string	No	Namespace where the embedding model is defined, defaults to default
spec.retrievalConfig.retrieval_mode	string	No	Retrieval mode: vector, keyword, or hybrid
spec.retrievalConfig.top_k	integer	No	Number of results to return
spec.retrievalConfig.score_threshold	number	No	Minimum relevance threshold
spec.retrievalConfig.hybrid_weights	object	No	Hybrid retrieval weights

retriever_name and embedding_config.model_name are required only when spec.retrievalConfig exists. By default, the backend automatically fills in a missing retriever and embedding model during creation; if the create request explicitly uses no-RAG mode, or if no usable defaults are available, it does not write retrievalConfig. The create request field rag_config_mode expresses creation intent only and is not persisted as a KnowledgeBase YAML field. The persisted stable states are either a complete retrievalConfig or no retrievalConfig.

Summary-Related Configuration

Field	Type	Required	Description
spec.summaryEnabled	boolean	No	Whether automatic summary generation is enabled
spec.summaryModelRef.name	string	No	Summary model name
spec.summaryModelRef.namespace	string	No	Namespace where the summary model is defined
spec.summaryModelRef.type	string	No	Summary model type: public, user, or group

Runtime Summary Fields

spec.summary is maintained by the system at runtime and is not intended to be authored directly in YAML. Common fields include:

Field	Description
short_summary	AI-generated short summary
long_summary	AI-generated long summary
manual_long_summary	Manually edited knowledge base long summary; takes priority for display and context injection
topics	AI-generated topic tags
status	Summary state: pending, generating, completed, failed
manual_updated_at	Last manual summary update time
manual_updated_by	Last manual summary editor

Notes:

• Manual summary does not stop AI summary generation from continuing
• When manual_long_summary exists, the system uses it first for UI display and chat-context injection
• After using Restore AI Summary, the system falls back to the latest long_summary

---

Code wiki fields

A knowledge base with spec.kbType = "code_wiki" is generated by an agent from a source repository. Every field below is written by the system and should not be edited by hand.

Field	Type	Description
spec.kbType	string	notebook, classic or code_wiki. Cannot move into or out of code_wiki
spec.source.sourceType	string	github, gitlab or gitea
spec.source.sourceUrl	string	Repository URL, derived at creation with any credentials stripped
spec.source.projectName	string	owner/repo
spec.source.sourceDomain	string	Repository host
spec.publishedGenerationId	integer	Sole authority for which version is live; 0 when nothing is
spec.lastPublishedAt	string	When that version was published, written with the pointer
spec.lastPublishedCommit	string	Commit the live version documents
spec.pageOrder	array	Page paths in display order; hierarchy comes from the paths, order only from here
spec.pendingIndexCleanup	array	Vector store references owed for removed pages, retried at the next publish

Invariants:

• publishedGenerationId is the only authority. Never infer the live version from the newest completed generation: one can finish and still be refused by the publish gate.
• Ownership is the creator, in the default namespace. Owning it is what makes the ordinary knowledge base ACL apply; repository access separately decides who may create one and who may regenerate it.
• One repository has one wiki, enforced by the UNIQUE on wiki_projects.source_url.
• Generated pages carry origin = generated; the projection only adds and removes those, so user content is never touched.

---

🤝 Collaboration

Collaboration defines the interaction patterns and workflows between Bots in a Team.

Complete Configuration Example for ClaudeCode

apiVersion: agent.wecode.io/v1
kind: Collaboration
metadata:
  name: workflow-collaboration
  namespace: default
spec:
  type: "workflow"
  config:
    steps:
      - name: "planning"
        participants:
          - "planner-bot"
      - name: "development"
        participants:
          - "developer-bot"
      - name: "review"
        participants:
          - "reviewer-bot"

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Collaboration
metadata.namespace	string	Yes	Namespace, typically default
spec.type	string	Yes	Collaboration type
spec.config	object	Yes	Collaboration configuration

Workflow Configuration

Field	Type	Description
steps	array	List of workflow steps
steps.name	string	Step name
steps.participants	array	List of participants

---

💼 Workspace

Workspace defines the team's working environment, including code repository and branch information.

Complete Configuration Example

apiVersion: agent.wecode.io/v1
kind: Workspace
metadata:
  name: project-workspace
  namespace: default
spec:
  repository:
    gitUrl: "https://github.com/user/repo.git"
    gitRepo: "{user}/{repo}"
    branchName: "main"
    gitDomain: "github.com"

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Workspace
metadata.namespace	string	Yes	Namespace, typically default
spec.repository	object	Yes	Repository configuration

Repository Configuration

Field	Type	Required	Description
gitUrl	string	Yes	Git repository URL
gitRepo	string	Yes	Repository path format
branchName	string	Yes	Default branch name
gitDomain	string	Yes	Git domain

---

🎯 Task

Task defines the task to be executed, associating Team and Workspace.

Complete Configuration Example

apiVersion: agent.wecode.io/v1
kind: Task
metadata:
  name: implement-feature
  namespace: default
spec:
  title: "Implement new feature"
  prompt: "Task description"
  teamRef:
    name: dev-team
    namespace: default
  workspaceRef:
    name: project-workspace
    namespace: default
  knowledgeBaseScopes:
    - id: 101
      namespace: default
      name: Product Docs
      scopeRestricted: true
      folderIds: [12]
      explicitDocumentIds: null
      includeSubfolders: true
  externalKnowledgeRefs:
    - provider: ap
      mode: explicit
      id: kb-1
      name: External Product Docs
      scope: organization
      target_type: document
      node_id: document:node-1
      document_id: node-1
      target_name: api-reference.md

Field Description

Field	Type	Required	Description
metadata.name	string	Yes	Unique identifier for the Task
metadata.namespace	string	Yes	Namespace, typically default
spec.title	string	Yes	Task title
spec.prompt	string	Yes	Task description
spec.teamRef	object	Yes	Team reference
spec.workspaceRef	object	Yes	Workspace reference
spec.knowledgeBaseScopes	array	No	Knowledge-base access scopes bound by /api/v1/responses, used to inherit folder/document scope in follow-up turns
spec.externalKnowledgeRefs	array	No	Task-level external knowledge source bindings maintained by chat context selection and the task knowledge management entry

Knowledge Base Scopes

spec.knowledgeBaseScopes is maintained automatically by the OpenAPI Responses knowledge-base tool. When a folder or document scope is enabled, follow-up requests with previous_response_id inherit the scope and re-resolve folder membership for the current turn.

Field	Type	Required	Description
id	integer	No	Knowledge base ID, preferred when present
namespace	string	No	Knowledge base namespace, defaults to default
name	string	Yes	Knowledge base name
scopeRestricted	boolean	No	Whether access is restricted to the listed folders or documents
folderIds	array	No	Allowed folder IDs. 0 means documents directly under the root folder
explicitDocumentIds	array	No	Explicitly allowed document IDs
includeSubfolders	boolean	No	Whether folder scope includes subfolders, defaults to true

External Knowledge Source Bindings

spec.externalKnowledgeRefs is a runtime field describing the external knowledge sources bound to the current Task. It is maintained by chat send handling and the task knowledge management APIs. It is not used for Ghost, Bot, or Team default configuration.

Field	Type	Required	Description
provider	string	Yes	External knowledge provider id
mode	string	No	Binding mode, defaults to explicit; explicit requires id
id	string	Conditionally	Stable provider-owned source ID
name	string	No	Source display name
scope	string	No	Provider-interpretable scope
target_type	string	No	knowledge_base, folder, or document; missing values are treated as whole-source bindings
node_id	string	No	Provider-neutral node ID
document_id	string	No	Provider-neutral document ID
parent_id	string	No	Provider-neutral parent node ID
target_name	string	No	Folder or document target display name

Task Status

Status	Description
PENDING	Waiting for execution
RUNNING	Currently executing
COMPLETED	Execution completed
FAILED	Execution failed
CANCELLED	Execution cancelled
DELETE	Task deleted

---

🔌 ConnectorApp

ConnectorApp defines an external app connection published by administrators for Wework/Codex. Resources are stored in the kinds table, metadata.name is the app slug, and the current namespace is system. In normal operation, maintain these resources through System Administration → App Connections in Wegent Web instead of hand-writing YAML.

Complete Example

apiVersion: agent.wecode.io/v1
kind: ConnectorApp
metadata:
  name: ticket-api
  namespace: system
  displayName: Ticket API
spec:
  name: Ticket API
  description: Search and read internal tickets
  iconUrl: https://example.com/ticket-icon.png
  enabled: true
  visibility: roles
  allowedRoles:
    - admin
  authType: none
  transport: http
  mcpUrl: https://tickets.example.com/api
  providerHeadersEncrypted: "base64-encrypted-json"
  toolAllowlist:
    - get_ticket
  httpTools:
    - name: get_ticket
      description: Get one ticket
      method: GET
      path: /tickets/{id}
      input_schema:
        type: object
        properties:
          id:
            type: string
        required:
          - id
      argument_locations:
        id: path
      timeout_seconds: 30

Field Reference

Field	Type	Required	Description
metadata.name	string	Yes	Unique Connector App slug, also used as the tool-name prefix
metadata.namespace	string	Yes	Currently system
spec.name	string	Yes	Display name
spec.description	string	No	App description
spec.iconUrl	string	No	Icon URL
spec.enabled	boolean	Yes	Whether the app is enabled; disabled apps are hidden from catalogs/runtime
spec.visibility	string	Yes	all or roles
spec.allowedRoles	array	No	User roles allowed when visibility: roles
spec.authType	string	Yes	Currently only none is supported
spec.transport	string	Yes	streamable-http, sse, or http
spec.mcpUrl	string	Yes	MCP endpoint or HTTP API base URL
spec.providerHeadersEncrypted	string	No	Fixed provider headers JSON encrypted with the project sensitive-data tool
spec.toolAllowlist	array	No	Upstream tool names allowed for discovery and invocation
spec.httpTools	array	Conditionally	Required for transport: http; maps ordinary HTTP APIs to MCP tools

providerHeadersEncrypted must be an encrypted JSON string. The administrator API accepts plaintext provider_headers and encrypts them before storage; do not commit plaintext API keys, service tokens, or headers in hand-written YAML.

---

Best Practices

1. Naming Conventions

• Use lowercase letters, numbers, and hyphens
• Avoid special characters and spaces
• Names should be descriptive

2. Namespaces

• Use default namespace by default
• Use different namespaces in multi-tenant environments

3. Reference Management

• Ensure referenced resources exist
• Use the same namespace
• Avoid circular references

4. Status Management

• Regularly check resource status
• Handle unavailable resources promptly
• Monitor task execution progress

5. Configuration Validation

• Use YAML syntax validation tools
• Check required fields
• Validate reference relationships

---

Related Documentation

• Quick Start Guide
• Architecture Design
• Development Guide
• Contribution Guide