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.

👻 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.
  baseGhostRef:
    name: system-default-ghost
    namespace: default
    user_id: 0
  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.baseGhostRef`	object	No	Ghost reference used as a capability baseline; one level only
`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"]`

baseGhostRef contains name, namespace, and user_id. At runtime, only the base Ghost's MCP servers, Skills, preloaded Skills, and plugins are inherited. Same-name entries from the current Ghost take precedence, and the current Ghost's systemPrompt is always preserved. Wegent merges the configuration before making one model request; it does not invoke both Ghosts separately. Nested baseGhostRef values are not supported.

Business MCP Server Identity

When spec.mcpServers points to a remote MCP server hosted by a business partner, the server can authenticate the calling Wegent user with the task token Wegent injects into outbound requests. Configure the server's static headers with the ${{task_token}} placeholder; Wegent replaces it with a signed task token when building the request:

spec:
  mcpServers:
    business:
      type: streamable-http
      url: https://mcp.business.example.com/mcp
      headers:
        Authorization: "Bearer ${{task_token}}"

The task token is scoped to the current task (24 hours by default). The business side can resolve the current user by calling GET /api/external/mcp-identity/userinfo with the same Authorization: Bearer <token> header; the response contains only the user's basic information (id, user_name, email) and never exposes git credentials.

✨ 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:

SKILL.md (required): Skill documentation with YAML frontmatter
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:
  isVisible: true
  allowedUsersEnabled: true
  allowedUsers: ["alice", "bob"]
  modelGroup: "Primary"
  modelSubGroup: "Fast"
  capability: "Fast responses for everyday questions and simple tasks"
  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.isVisible`	boolean	No	Whether a public model appears in regular users' model selectors. Defaults to `true`; `false` preserves existing references and runtime resolution.
`spec.allowedUsers`	array	No	User-name whitelist of a public model; only enforced when `allowedUsersEnabled` is `true`. When the switch is off, the list is retained but does not restrict access.
`spec.allowedUsersEnabled`	boolean	No	Explicit switch for whitelist-only mode; when `true`, access is governed strictly by `allowedUsers`, and an empty list denies everyone. When `false`/absent, the model is a normal public model and `allowedUsers` is ignored.
`spec.modelGroup`	string	No	First-level display group used by model selectors
`spec.modelSubGroup`	string	No	Second-level display group under `spec.modelGroup`
`spec.capability`	string/object	No	Summary shown below the model name. Published models use the publication object's `description` field. Omit or leave empty to show only the name; selectors do not display the real model ID.
`spec.modelConfig`	object	Yes	Model configuration object
`spec.modelConfig.env`	object	Yes	Environment variables configuration
`spec.modelConfig.ui`	object	No	Wework model-picker presentation, default-model, and reasoning-effort configuration.
`spec.modelConfig.visionSidecarModel`	object	No	Explicit reference to the model that processes images; omission disables vision delegation.
`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.

Wework model-picker configuration

Decision models set spec.modelType: decision and explicitly declare spec.protocol: systemone or openai, without a chat apiFormat. Provider URL, model ID and credentials remain in spec.modelConfig.env. Enable isWeworkAvailable to select them in the decision workbench. See Decision Models.

Cloud models can provide model-picker metadata through modelConfig.ui. Mark the default model with defaultModel: true, and declare its supported reasoning efforts with reasoningEfforts and defaultReasoningEffort. The default model can also provide multiple named model sets through sliderModelsConfig.presets. Every preset with at least one available slider position is displayed, and defaultPreset selects the initially active model set.

Each preset has a stable unique name, a first-line label, and an ordered models list. An optional description configures the second line. Without a description, the default preset falls back to "Recommended model set" and other presets fall back to "Model set". modelName identifies a Model resource name or model ID. For ambiguous names, provide modelType, namespace, and resourceUserId as the complete resource identity. Presets appear directly under their top-level source, such as "Cloud models", before model-family subgroups. An entry that omits both reasoningEffort and reasoningEfforts selects only the model without setting a reasoning effort; the model need not declare reasoning efforts. Explicitly requested efforts must be supported by the target model; declare them through its own modelConfig.ui.reasoningEfforts. Invisible or unavailable models and unsupported efforts are removed from the preset. The remaining preset is still displayed when at least one valid position remains, and is hidden only when no valid positions remain.

spec:
  isWeworkAvailable: true
  modelConfig:
    env:
      model: openai
      model_id: cloud-sol-upstream
    ui:
      family: cloud-openai
      modelLabel: Cloud Sol
      defaultModel: true
      reasoningEfforts: [low, medium, high]
      defaultReasoningEffort: medium
      sliderModelsConfig:
        defaultPreset: recommended
        presets:
          - name: recommended
            label: Recommended
            description: Recommended for everyday work
            models:
              - modelName: cloud-luna
                reasoningEffort: high
              - modelName: cloud-sol
                reasoningEfforts: [low, medium, high]
          - name: quality
            label: Quality
            description: Prioritize quality
            models:
              - modelName: cloud-terra
                reasoningEfforts: [medium, high]

Vision delegation model reference

A text-only model can explicitly reference another image-capable model in modelConfig.visionSidecarModel. The reference must use the complete resource identity and apiFormat returned by the Backend's authorized model list. The reference is authoritative: Wework only validates its shape, while the Backend's LLM gateway resolves and authorizes the target at call time using the same identity headers. Referencing a model that never declared supportsImage, or one that is not distributed to Wework, therefore still works. Wework never selects a default vision model from sign-in state or model names. A malformed reference leaves the primary model text-only with no image preprocessing; a reference whose target is missing or cannot read images replaces that image with an explicit failure message, so the original image never leaks to the text-only primary model.

The Wegent web vision model dropdown only lists candidates that declare modelCapabilities.supportsImage: true, so image-capable models should carry that field. When an existing reference points at a model outside that candidate list, the dropdown keeps the reference and marks it as currently unselectable, so saving the model does not discard it.

apiFormat must match the upstream protocol the referenced model actually speaks: openai-responses, openai-chat-completions, or anthropic-messages. Most Model CRDs only declare spec.modelConfig.env.model, in which case the protocol is inferred from that field (claude maps to Anthropic Messages, openai maps to OpenAI Chat Completions).

spec:
  protocol: openai-responses
  apiFormat: responses
  modelConfig:
    env:
      model: openai
      model_id: deepseek-v4-pro
      base_url: https://example.com/v1
      api_key: ${WECODE_USER_API_KEY}
    visionSidecarModel:
      modelName: openai-gpt-5.6-luna
      modelType: public
      namespace: default
      resourceUserId: 0
      apiFormat: openai-responses

Field	Type	Required	Description
`modelName`	string	Yes	Referenced Model's `metadata.name`.
`modelType`	string	Yes	Resource source: `public`, `user`, or `group`.
`namespace`	string	Yes	Referenced Model's namespace.
`resourceUserId`	integer	Yes	Resource owner ID of the referenced Model.
`apiFormat`	string	Yes	`openai-responses`, `openai-chat-completions`, or `anthropic-messages`.

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
  clientIp: 10.0.0.24
  runtimeTransferHost: 10.0.0.24
  runtimeTransferPort: 17888
  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
    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.clientIp`	string	No	Client IP observed by Backend from the device connection
`spec.runtimeTransferHost`	string	No	Executor-reported device address reachable from other machines
`spec.runtimeTransferPort`	integer	No	Effective Executor session gateway listening port
`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

runtimeTransferHost must be reachable from other machines; loopback, unspecified, link-local, and multicast addresses are not used to build device access URLs. The Executor reports runtimeTransferPort; Backend uses the default port 17888 when a legacy Executor does not report it. Backend builds a remote device's browser-facing address from the device address it observes, falling back to runtimeTransferHost, and appends runtimeTransferPort. 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.

🤖 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.

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

Table of Contents​

👻 Ghost​

Complete Configuration Example​

Field Description​

Business MCP Server Identity​

✨ Skill​

Complete Configuration Example​

Field Description​

ZIP Package Requirements​

Using Skills in Ghosts​

🧠 Model​

Complete Configuration ClaudeCode Example​

Field Description​

Wework model-picker configuration​

Vision delegation model reference​

Model Selector Grouping​

Common Environment Variables for ClaudeCode​

🐚 Shell​

Complete Configuration Example​

Field Description​

Shell Types​

Labels​

🖥 Device​

Remote Docker Device Example​

Field Description​

🤖 Bot​

Complete Configuration Example​

Field Description​

Reference Format​

👥 Team​

Complete Configuration Example for ClaudeCode Model​

Field Description​

Member Configuration​

Collaboration Models​

📚 KnowledgeBase​

Retrieval Configuration​

Summary-Related Configuration​

Runtime Summary Fields​

Code wiki fields​

🤝 Collaboration​

Complete Configuration Example for ClaudeCode​

Field Description​

Workflow Configuration​

💼 Workspace​

Complete Configuration Example​

Field Description​

Repository Configuration​

🎯 Task​

Complete Configuration Example​

Field Description​

Knowledge Base Scopes​

External Knowledge Source Bindings​

Task Status​

🔌 ConnectorApp​

Complete Example​

Field Reference​

Best Practices​

1. Naming Conventions​

2. Namespaces​

3. Reference Management​

4. Status Management​

5. Configuration Validation​

Related Documentation​

Table of Contents

👻 Ghost

Complete Configuration Example

Field Description

Business MCP Server Identity

✨ Skill

Complete Configuration Example

Field Description

ZIP Package Requirements

Using Skills in Ghosts

🧠 Model

Complete Configuration ClaudeCode Example

Field Description

Wework model-picker configuration

Vision delegation model reference

Model Selector Grouping

Common Environment Variables for ClaudeCode

🐚 Shell

Complete Configuration Example

Field Description

Shell Types

Labels

🖥 Device

Remote Docker Device Example

Field Description

🤖 Bot

Complete Configuration Example

Field Description

Reference Format

👥 Team

Complete Configuration Example for ClaudeCode Model

Field Description

Member Configuration

Collaboration Models

📚 KnowledgeBase

Retrieval Configuration

Summary-Related Configuration

Runtime Summary Fields

Code wiki fields

🤝 Collaboration

Complete Configuration Example for ClaudeCode

Field Description

Workflow Configuration

💼 Workspace

Complete Configuration Example

Field Description

Repository Configuration

🎯 Task

Complete Configuration Example

Field Description

Knowledge Base Scopes

External Knowledge Source Bindings

Task Status

🔌 ConnectorApp

Complete Example

Field Reference

Best Practices

1. Naming Conventions

2. Namespaces

3. Reference Management

4. Status Management

5. Configuration Validation

Related Documentation