OpenCode CLI 命令行工具完全指南：从基础命令到自动化脚本的实战手册

OpenCode CLI 命令行工具完全指南：从基础命令到自动化脚本的实战手册

引言

大多数开发者接触 OpenCode 时，都是从 opencode 命令启动终端界面（TUI）开始的。但 OpenCode 远不止一个交互式界面——它提供了一套功能完备的命令行工具，让你可以在脚本、自动化流水线、CI/CD 流程中灵活调用 AI 编程能力。本文将全面解析 OpenCode CLI 的每个命令和全局选项，并给出实际可用的自动化场景示例。

基础用法

在终端中直接运行 opencode 会启动 TUI 交互界面。但你也可以传递子命令来执行特定操作：

# 启动 TUI（默认）
opencode

# 使用非交互模式直接提问
opencode run "解释 JavaScript 中闭包的工作原理"

CLI 支持以下全局标志，可在任何子命令前使用：

| 标志 | 简写 | 说明 |
|------|------|------|
| --help | -h | 显示帮助信息 |
| --version | -v | 打印版本号 |
| --print-logs | | 将日志输出到 stderr |
| --log-level | | 设置日志级别（DEBUG、INFO、WARN、ERROR） |
| --pure | | 不加载外部插件运行 |

核心命令详解

opencode run — 非交互模式执行

这是最有用的命令之一。它允许你在不启动 TUI 的情况下直接向 OpenCode 发送指令，非常适合脚本化和自动化场景：

# 直接提问
opencode run "Go 语言中 context 包的用途是什么"

# 带文件上下文提问
opencode run --file src/main.go "给这个文件添加错误处理"

# 指定模型
opencode run -m anthropic/claude-sonnet-4-5 "优化这段代码的性能"

# 继续上一次会话
opencode run --continue "继续之前的重构"

# 自动批准权限（跳过确认）
opencode run --auto "更新所有依赖包版本"

关键参数：

  • --file / -f — 将文件附加到消息中
  • --model / -m — 指定模型（格式：provider/model）
  • --agent — 指定使用哪个 Agent
  • --continue / -c — 继续上一次会话
  • --share — 自动分享会话
  • --auto — 自动批准未明确拒绝的权限
  • --attach — 附加到正在运行的 OpenCode 服务
  • --format json — 以 JSON 格式输出结果，适合程序解析

opencode serve — 启动后端服务

启动一个无界面的 HTTP 服务器，为 API 访问提供支持：

# 默认端口启动
opencode serve

# 指定端口和主机名
opencode serve --port 4096 --hostname 0.0.0.0

# 启用 mDNS 网络发现
opencode serve --mdns

结合 OPENCODE_SERVER_PASSWORD 环境变量可以启用 HTTP Basic 认证，确保安全性。

opencode web — 启动 Web 界面

与 serve 类似，但会自动在浏览器中打开 Web 界面：

opencode web --port 4096

opencode session — 会话管理

查看和管理所有历史会话：

# 列出所有会话
opencode session list

# 列出最近 10 条会话（表格格式）
opencode session list -n 10 --format table

# 以 JSON 格式输出（方便脚本处理）
opencode session list --format json

# 删除特定会话
opencode session delete <sessionID>

opencode attach — 远程连接 TUI

将 TUI 连接到远程 OpenCode 后端，实现远程开发：

# 在一台机器上启动后端
opencode web --port 4096 --hostname 0.0.0.0

# 在另一台机器上连接
opencode attach http://10.20.30.40:4096

opencode auth — 认证管理

管理所有 LLM 提供商的 API 密钥：

# 交互式登录
opencode auth login

# 直接指定提供商登录
opencode auth login --provider anthropic

# 列出已认证的提供商
opencode auth list
opencode auth ls   # 简写

# 登出提供商
opencode auth logout

认证信息存储在 ~/.local/share/opencode/auth.json 中。OpenCode 启动时会自动加载该文件以及环境变量和项目 .env 文件中的密钥。

opencode models — 模型查询

列出你配置的所有提供商中的可用模型：

# 列出所有模型
opencode models

# 按提供商筛选
opencode models anthropic

# 刷新模型缓存（新增模型时使用）
opencode models --refresh

# 查看详细元数据（包含费用信息）
opencode models --verbose

模型的输出格式为 provider/model，可以直接用于配置文件或 -m 参数。

opencode stats — 使用统计

查看令牌消耗和费用统计：

# 查看所有统计
opencode stats

# 查看最近 7 天统计
opencode stats --days 7

# 查看模型使用分布
opencode stats --models

# 按工具维度统计
opencode stats --tools

这对于预算管理和用量监控非常有价值。

opencode agent — Agent 管理

创建和管理自定义 Agent：

# 交互式创建 Agent
opencode agent create

# 非交互式创建（指定所有参数）
opencode agent create \
  --path .opencode/agents/code-review.md \
  --description "代码审查专家" \
  --mode subagent \
  --permissions read,grep,webfetch \
  --model anthropic/claude-sonnet-4-5

# 列出所有 Agent
opencode agent list

opencode mcp — MCP 服务器管理

管理 Model Context Protocol 服务器：

# 交互式添加 MCP 服务器
opencode mcp add

# 列出所有配置的 MCP 服务器
opencode mcp list
opencode mcp ls

# MCP OAuth 认证管理
opencode mcp auth <server-name>
opencode mcp auth list

# 诊断 MCP 连接问题
opencode mcp debug <server-name>

opencode export / import — 会话导入导出

# 将会话导出为 JSON
opencode export <sessionID>
opencode export <sessionID> --sanitize  # 脱敏敏感数据

# 从文件或分享链接导入会话
opencode import session.json
opencode import https://opncd.ai/s/abc123

opencode plugin — 插件管理

安装插件扩展 OpenCode 功能：

# 安装插件
opencode plugin opencode-helicone-session
opencode plug @my-org/custom-plugin  # 简写

# 全局安装
opencode plugin -g my-plugin

# 强制覆盖
opencode plugin -f my-plugin

opencode pr — 代码审查工作流

快速检出 GitHub PR 并启动 OpenCode：

opencode pr 42

这条命令会自动拉取 PR #42 的代码分支并启动 OpenCode 进行审查。

opencode upgrade / uninstall — 版本管理

# 升级到最新版本
opencode upgrade

# 升级到指定版本
opencode upgrade v0.1.48

# 卸载（可选择保留配置和数据）
opencode uninstall --keep-config --keep-data

环境变量配置

OpenCode 通过环境变量提供了丰富的配置能力：

# === 核心配置 ===
export OPENCODE_CONFIG=/path/to/custom-config.json   # 指定配置文件路径
export OPENCODE_CONFIG_DIR=/path/to/config-dir        # 指定配置目录
export OPENCODE_CONFIG_CONTENT='{"model":"..."}'      # 内联 JSON 配置
export OPENCODE_TUI_CONFIG=/path/to/tui-config.json   # TUI 配置文件路径

# === 网络代理（企业环境必备） ===
export HTTPS_PROXY=http://proxy.company.com:8080      # HTTPS 代理
export HTTP_PROXY=http://proxy.company.com:8080        # HTTP 代理
export NO_PROXY=localhost,127.0.0.1                    # 绕过代理的地址

# === 权限与行为控制 ===
export OPENCODE_PERMISSION='{"bash":"ask","edit":"ask"}'  # 权限配置
export OPENCODE_DISABLE_AUTOUPDATE=true                    # 禁用自动更新
export OPENCODE_DISABLE_AUTOCOMPACT=true                   # 禁用自动上下文压缩
export OPENCODE_DISABLE_PRUNE=true                         # 禁用旧数据清理
export OPENCODE_DISABLE_MOUSE=true                         # 禁用鼠标捕获

# === 服务端认证 ===
export OPENCODE_SERVER_PASSWORD=my-secret                  # 启用 Basic Auth
export OPENCODE_SERVER_USERNAME=admin                      # 自定义用户名

# === LSP 控制 ===
export OPENCODE_DISABLE_LSP_DOWNLOAD=true                  # 禁用自动 LSP 下载

# === Claude Code 兼容 ===
export OPENCODE_DISABLE_CLAUDE_CODE=true                   # 禁用读取 .claude 配置

配置变量替换

在 opencode.json 中可以使用变量引用环境变量和文件内容：

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

{env:VAR_NAME} 引用环境变量，{file:path} 引用文件内容——这让敏感信息的管理更加安全灵活。

实战场景

场景一：每日代码审查脚本

#!/bin/bash
# 审查今日变更的代码
git diff --name-only HEAD~1 | while read file; do
  opencode run --file "$file" \
    "Review this file for bugs, security issues, and performance problems. Output in JSON format."
done

场景二：持续集成流水线集成

# GitHub Actions 示例
- name: Auto-fix lint issues
  run: |
    opencode run --auto \
      "Fix all lint warnings in the src/ directory. Run 'npm run lint' after changes to verify."

场景三：远程团队协作

# 开发机启动共享服务
opencode serve --port 4096 --mdns
# 队友从另一台机器连接 TUI
opencode attach http://dev-machine.local:4096

场景四：批量重构脚本

# 对多个文件执行相同的重构操作
for file in src/**/*.ts; do
  opencode run --file "$file" \
    "Convert CommonJS require() to ES6 import syntax in this file."
done

总结

OpenCode CLI 远不止一个启动命令——它是一个完整的工具生态系统。opencode run 让你的 AI 编程助手可以被脚本和流水线调用；opencode serve 和 opencode attach 支持远程协作架构；opencode session、stats、export 提供了完备的数据管理能力。结合丰富的环境变量和配置变量替换，你可以精确控制 OpenCode 在各种环境中的行为。

掌握这些 CLI 命令，意味着你已经从单纯使用 AI 编程助手，进化到了能够将 AI 能力深度集成到自动化工作流中的高级阶段。无论是个人效率提升还是团队协作落地，OpenCode CLI 都是不可或缺的核心工具。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客