OpenCode Guide
Navigate: Menu

Intro (入门)

Usage (使用指南)

Configure (详细配置)

Develop (开发)

OpenCode CLI 文档

OpenCode CLI 是一款强大的命令行工具，默认情况下无参数运行时会启动 终端用户界面 (TUI)。同时支持通过命令行参数进行编程式交互，适用于自动化脚本、远程访问及集成开发环境。

基础使用

启动 TUI

直接运行以下命令启动：
opencode
或指定项目路径：
opencode [项目名/路径]

非交互模式

通过 run 命令直接传入提示词，快速获取结果而无需启动 TUI：
opencode run "解释 JavaScript 中的闭包工作原理"

核心选项 (Flags)

参数简写描述
--continue-c继续上一次会话
--session-s指定要继续的会话 ID
--prompt-自定义提示词
--model-m指定使用的模型（提供商/模型名）
--agent-指定要使用的智能体 (Agent)
--file-f附加本地文件到上下文
--format-输出格式 (default | json)
--title-设置会话标题
--port-监听端口
--hostname-监听主机名

命令详解

agent - 管理智能体

用于创建、列出和配置 OpenCode 智能体。
子命令用法描述
createopencode agent create引导创建自定义智能体（含系统提示词和工具配置）
listopencode agent list列出所有可用智能体

auth - 凭证与登录管理

用于配置模型提供商 API 密钥。凭证默认存储于 ~/.local/share/opencode/auth.json。
子命令用法描述
loginopencode auth login交互式配置提供商 API 密钥
list/lsopencode auth list列出所有已认证的提供商
logoutopencode auth logout退出并清除指定提供商的凭证

github - GitHub 自动化管理

子命令用法描述
installopencode github install在仓库中安装 GitHub 智能体（配置 CI/CD 工作流）
runopencode github run运行 GitHub 智能体（通常用于 GitHub Actions）

mcp - 管理模型上下文协议服务器

子命令用法描述
addopencode mcp add引导添加本地或远程 MCP 服务器
list/lsopencode mcp list列出已配置的 MCP 服务器及连接状态
authopencode mcp auth [名称]向 OAuth 启用的 MCP 服务器认证
logoutopencode mcp logout [名称]移除 MCP 服务器的 OAuth 凭证
debugopencode mcp debug <名称>调试 MCP 服务器连接问题

models - 列出可用模型

opencode models [提供商]
  • --refresh：从 models.dev 刷新缓存。
  • --verbose：显示详细模型信息（含成本等元数据）。

run - 非交互式运行

适用于脚本和自动化流程。
opencode run [提示词...]
示例：关联运行中的服务器
# 关联已有服务器运行（避免冷启动）
opencode run --attach http://localhost:4096 "解释 Go 的 Context"

serve / web - 启动服务器

  • serve：启动无头 HTTP API 服务器。
  • web：启动带网页界面的服务器，并自动打开浏览器。
支持参数：--port, --hostname, --mdns, --cors。

session - 管理会话

OpenCode 最核心的会话管理功能，支持导出、导入及统计。
子命令用法描述
listopencode session list列出所有历史会话
statsopencode session stats显示令牌使用量和成本统计
exportopencode session export [ID]导出会话数据为 JSON
importopencode session import <文件/URL>从文件或分享链接导入会话

acp - 快速提交

快速 git add, git commit -m "[消息]", git push 的组合命令。
opencode acp "修复 bug"

uninstall & upgrade

  • opencode uninstall
    卸载（可加 --keep-config --keep-data --dry-run --force）
  • opencode upgrade [版本号]
    升级（不带参数 → 最新版；可指定版本如 v0.1.48）
    选项：--method（curl/npm/pnpm/bun/brew）

全局选项（任何命令都可用）

  • --help / -h
  • --version / -v
  • --print-logs
  • --log-level （DEBUG / INFO / WARN / ERROR）

环境变量

OpenCode 可以通过环境变量进行配置。
变量类型描述
OPENCODE_AUTO_SHAREboolean自动分享会话
OPENCODE_GIT_BASH_PATHstringWindows 上 Git Bash 可执行文件的路径
OPENCODE_CONFIGstring配置文件路径
OPENCODE_CONFIG_DIRstring配置目录路径
OPENCODE_CONFIG_CONTENTstring内联 JSON 配置内容
OPENCODE_DISABLE_AUTOUPDATEboolean禁用自动更新检查
OPENCODE_DISABLE_PRUNEboolean禁用旧数据清理
OPENCODE_DISABLE_TERMINAL_TITLEboolean禁用自动终端标题更新
OPENCODE_PERMISSIONstring内联 JSON 权限配置
OPENCODE_DISABLE_DEFAULT_PLUGINSboolean禁用默认插件
OPENCODE_DISABLE_LSP_DOWNLOADboolean禁用自动 LSP 服务器下载
OPENCODE_ENABLE_EXPERIMENTAL_MODELSboolean启用实验性模型
OPENCODE_DISABLE_AUTOCOMPACTboolean禁用自动上下文压缩
OPENCODE_DISABLE_CLAUDE_CODEboolean禁用从 .claude 读取（提示词 + 技能）
OPENCODE_DISABLE_CLAUDE_CODE_PROMPTboolean禁用读取 ~/.claude/CLAUDE.md
OPENCODE_DISABLE_CLAUDE_CODE_SKILLSboolean禁用加载 .claude/skills
OPENCODE_CLIENTstring客户端标识符（默认为 cli）
OPENCODE_ENABLE_EXAboolean启用 Exa 网络搜索工具
OPENCODE_SERVER_PASSWORDstring为 serve/web 启用基本身份验证
OPENCODE_SERVER_USERNAMEstring覆盖基本身份验证用户名（默认为 opencode）

实验性选项

这些环境变量启用了可能会更改或删除的实验性功能。
变量类型描述
OPENCODE_EXPERIMENTALboolean启用所有实验性功能
OPENCODE_EXPERIMENTAL_ICON_DISCOVERYboolean启用图标发现
OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECTboolean在 TUI 中禁用选中即复制
OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTHnumberBash 命令的最大输出长度
OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MSnumberBash 命令的默认超时时间（毫秒）
OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAXnumberLLM 响应的最大输出 Token 数
OPENCODE_EXPERIMENTAL_FILEWATCHERboolean对整个目录启用文件监听 (File watcher)
OPENCODE_EXPERIMENTAL_OXFMTboolean启用 oxfmt 格式化程序
OPENCODE_EXPERIMENTAL_PLAN_MODEboolean启用实验性计划模式 (Plan mode)
OPENCODE_EXPERIMENTAL_LSP_TOOLboolean启用实验性 LSP 工具