垦荒学园
  • 中文

      • 配置与 CLI 参考

      本章汇总 opencode.json、环境变量与常用 CLI 命令。

      配置文件

      路径用途
      ~/.config/opencode/opencode.json全局默认
      ./opencode.json项目级（Git 根向上查找）
      ~/.config/opencode/tui.jsonTUI 主题、快捷键
      .opencode/agents/自定义 Agent Markdown
      .opencode/commands/自定义斜杠命令
      .opencode/skills/Skills（若启用）

      环境变量：

      变量作用
      OPENCODE_CONFIG额外配置文件路径
      OPENCODE_CONFIG_CONTENT内联 JSON 覆盖
      Provider 相关各厂商 API_KEY（见 /connect 文档）

      opencode.json 结构概览

      {
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6",
  "provider": {},
  "agent": {},
  "permission": {},
  "mcp": {},
  "lsp": {},
  "instructions": []
}

      model 与 provider

      • model：默认 provider/model-id 字符串
      • provider：各厂商 endpoint、apiKey 引用等
      • TUI /connect 可交互配置，避免明文写入仓库

      instructions

      字符串数组，追加到系统提示（类似全局 rules）：

      {
  "instructions": [
    "始终用中文回复",
    "修改前先运行相关测试"
  ]
}

      常用 CLI

      安装与更新

      # 官方安装脚本（见 opencode.ai）
curl -fsSL https://opencode.ai/install | bash

# 或包管理器
npm i -g opencode-ai
# brew install opencode 等

      交互式 TUI

      cd your-project
opencode

      非交互 run

      opencode run "为 README 添加安装章节"

      适合脚本、CI 辅助（注意 permission 与 API 成本）。

      服务化

      opencode serve          # API
opencode web            # Web UI
opencode acp            # Agent Client Protocol

      Agent 管理

      opencode agent create
opencode agent list

      其他

      opencode --help
opencode version

      具体子命令以本地 opencode --help 为准，版本迭代较快。

      TUI 斜杠命令（常用）

      命令作用
      /init生成 AGENTS.md
      /connect配置 LLM Provider
      /share分享会话链接
      /help帮助
      /clear清屏
      /exit退出

      自定义命令放在 .opencode/commands/*.md。

      自定义斜杠命令

      .opencode/commands/test-and-fix.md：

      ---
description: 跑测试并修复失败用例
---

请执行项目测试命令（见 AGENTS.md），若有失败则逐个修复并再次运行直到通过。

      TUI 输入 /test-and-fix 即可注入该 prompt 模板。

      OpenCode Zen

      OpenCode 提供 Zen curated 模型列表（优化过的模型组合与路由），适合不想自行折腾 Provider 的用户。在官网或 TUI /connect 中了解当前可用模型与定价。

      75+ Provider

      OpenCode 支持 Anthropic、OpenAI、Google、本地 Ollama、OpenRouter 等。配置方式因 Provider 而异：

      • API Key 环境变量
      • 自定义 baseURL（兼容 OpenAI API 的网关）
      • 本地模型无需联网

      团队建议： 在 opencode.json 中锁定 model，避免成员误用昂贵模型。

      与 Git 协作

      • 将 opencode.json（无密钥）与 AGENTS.md 提交仓库
      • 不要提交含 API Key 的配置；用环境变量或本地 global 配置
      • .gitignore 可选忽略 .opencode/cache 等本地缓存

      下一步