OpenCode guideOpenCode 指南

OpenCode guideOpenCode 指南

Start with engine capabilities, then follow its installation, model sync and workspace guide. Pi remains experimental; engine capabilities differ.先了解各引擎能力，再按目标完成安装、模型同步和工作台配置。Pi 仍为实验版，各引擎功能并不相同。

OpenCode 独立工作台

OpenCode 的运行配置与实际操作分开，不依赖 OpenClaw Gateway。初始受管安装基线为 opencode-ai@1.18.21，实际目标以配置页为准，不代表上游最新版本。

  1. 从侧栏选择 OpenCode，进入「运行与配置」并完成受管安装；完整引擎环境推荐 Node.js 24.16.0+（24.x）与 npm。
  2. 在「通用 → 模型渠道」保存地址、API Key、模型，显式点击「同步到 OpenCode」，按需设置默认模型。
  3. 启动受管服务，进入「工作台」内嵌的 OpenCode Web 界面，添加项目、创建会话并选择模型，发送测试消息验证完整回复。

当前转换支持 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Ollama 的 OpenAI 兼容 /v1；Google Generative AI、OAuth 和结构化 SecretRef 不在此同步路径中。修改渠道需再次同步，配置回读不等于实际调用通过。

网络、项目和数据

默认回环端口 4096，可在配置页修改。端口占用时更换端口，不自动终止外部服务。Web 模式通过面板认证代理内嵌，无需额外对外开放 4096。

受管运行时、配置和凭据位于当前配置根目录的 clawpanel/opencode/；凭据保存在独立文件。Web 项目路径属于面板服务器，Docker 须单独挂载目录。共享登录与项目目录不是多用户代码执行隔离。

更新和卸载

检查更新与在线更新只针对受管安装，先在 staging 安装并核验再切换，切换失败恢复原运行时；运行中更新会停机并尝试重新启动，失败需查看日志。上游新版本不代表全部功能已通过面板验收。

卸载停止受管进程并删除运行时，保留 home/ 下配置、凭据、项目和数据，不等于清除了敏感信息。外部启动实例受管理限制。另见引擎与驱动。

Independent OpenCode workspace

OpenCode separates runtime configuration from its actual workspace and does not require OpenClaw Gateway. The initial managed baseline is opencode-ai@1.18.21. Use the target displayed in configuration; this is not an upstream latest-version claim.

  1. Select OpenCode, open Run & configuration and install its managed runtime. Node.js 24.16.0+ (24.x) and npm are recommended for full engine use.
  2. Save the address, API key and models in General → Model channels, explicitly select Sync to OpenCode, and optionally set the default model.
  3. Start the service and open the embedded OpenCode Web workspace. Add a project, create a session, select a model and verify a complete test reply.

Current conversion covers OpenAI Chat Completions, OpenAI Responses, Anthropic Messages and Ollama's OpenAI-compatible /v1. Google Generative AI, OAuth and structured SecretRef are outside this sync path. Sync after edits; readback does not prove a successful model call.

Networking, projects and data

The default loopback port is 4096, configurable in the panel. Change a conflicting port rather than terminating an external service. Web mode embeds it through the authenticated panel proxy without another public 4096 port.

Managed runtime, configuration and separate credential files live under clawpanel/opencode/ in the current configuration root. Web projects belong to the panel server; mount Docker project directories separately. Shared login and project paths are not multi-user code-execution isolation.

Updates and uninstall

Check/update operations apply only to managed installs: install and verify in staging, switch, and restore on switch failure. Updating a running service causes downtime and attempts a restart; inspect logs if restart fails. Upstream updates are not blanket compatibility acceptance.

Uninstall stops the managed process and removes its runtime but retains configuration, credentials, projects and data under home/; sensitive data is not erased. External instances have management restrictions. See Engines & drivers.

qt.cool