OpenCode Deployment (Direct Use) ​

This manual describes how to deploy and use OpenCode directly on openEuler. Installing witty normally completes the OpenCode deployment and configuration automatically; this section applies to advanced scenarios where Witty CLI is bypassed and OpenCode is managed manually.

Regular users should follow Witty CLI one-click deployment; no manual OpenCode deployment is required.

Environment Requirements ​

• Operating System: openEuler 24.03 LTS SP3 or later
• Dependencies:
  • nodejs >= 20, from the everything repository
  • opencode, from the update repository
• System Permissions: sudo privileges are required

Installing OpenCode ​

sudo dnf install nodejs opencode

Verify the installation:

opencode --version

Witty Managed Configuration ​

After installing Witty, witty-agent-loader aggregates the managed OpenCode configuration in /etc/opencode/opencode.json. That file is a generated artifact and should not be maintained by hand.

Managed Directories ​

Key Points of the Generated Configuration ​

The generated /etc/opencode/opencode.json typically contains:

{
  "$schema": "https://opencode.ai/config.json",
  "skills": {
    "paths": ["/usr/share/witty/opencode/skills"]
  },
  "agent": {
    "witty-builtin-agent": {
      "description": "Knowledge Q&A, command lookup, fault diagnosis, solution planning, and visual reports",
      "mode": "primary",
      "prompt": "{file:/usr/share/witty/opencode/agents/witty-builtin-agent/witty-builtin-agent.md}",
      "color": "#5F87FF",
      "permission": { "*": "ask", "read": { "*": "allow", "*.env": "ask" }, "bash": "allow" }
    }
  },
  "mcp": {
    "openeuler_portal": {
      "type": "local",
      "command": ["npx", "-y", "openeuler-portal-mcp"],
      "enabled": true
    }
  }
}

• skills.paths always points to /usr/share/witty/opencode/skills; the set of directories changes automatically when Skill subpackages are installed or removed;
• fields such as agent, mcp, and permission come from config.d/ fragments; the loader merges them and rewrites relative {file:...} references to absolute paths;
• the plugin field comes from declarations in each subpackage; plugin entries from multiple subpackages are deduplicated and merged.

Starting OpenCode Directly ​

Headless Service ​

opencode serve --port 4096

This is how Witty connects to OpenCode by default; when server.auto_start = false, start the service manually in this way.

Interactive TUI ​

opencode

opencode starts the interactive terminal interface in the current directory and loads the agent / skill / mcp configuration from /etc/opencode/opencode.json automatically.

Extending ​

Installing Built-in Agents and Skills ​

The built-in agent and skills are installed with Witty and need no extra action. To install additional diagnostic capabilities:

sudo dnf install witty-diagnosis-agent

List the available agents after installation:

opencode agent list

Appendix ​

Manual Deployment Without witty ​

If you do not want to rely on the Witty managed loader, you can maintain /etc/opencode/opencode.json yourself, but you must handle fragment merging and {file:...} path rewriting on your own. This is recommended only for test environments; production environments should keep the Witty managed deployment.

FAQ ​

Q: Where is opencode installed from?

opencode comes from the update repository. If installation fails, confirm that the update repository is enabled in /etc/yum.repos.d/.

Q: How can I confirm that the OpenCode configuration is managed and generated by Witty?

Check whether /etc/opencode/opencode.json exists, and the /doc endpoint and server management items in the output of witty doctor.