OpenCode CLI 命令行实战指南：不打开 TUI 也能玩转 AI 编程

引言

很多人在使用 OpenCode 时，习惯直接敲 opencode 进入那个漂亮的终端界面（TUI）。但 OpenCode 远不止一个交互式界面那么简单——它内置了一套完整的命令行工具，可以让你非交互式地调用 AI、批量处理任务、管理会话、统计用量、甚至搭建后台服务。这些能力在脚本化、自动化、CI/CD 场景下尤其有用。

本篇文章将带你系统掌握 OpenCode CLI 的常用命令，从最基础的 opencode run 到会话管理、用量统计、服务部署，并给出可以直接复制运行的实战示例。

一、基础概念：CLI 与 TUI

OpenCode 的 CLI（命令行接口）与 TUI（终端用户界面）是两套不同的交互方式：

• TUI：交互式对话界面，适合人工参与编码过程
• CLI：非交互式命令，适合脚本调用和自动化流程

不传任何参数直接运行 opencode，默认进入 TUI；而传入子命令（如 opencode run）则走 CLI 模式。两者共享同一套配置、会话数据和权限系统，切换起来没有成本。

二、opencode run：非交互式编程的核心命令

opencode run 是 CLI 里最常用的命令，它让你可以直接在命令行传入提示词，OpenCode 会执行任务并把结果返回终端，全程不需要打开交互界面。

# 最简单的用法：直接问一个问题
opencode run "解释一下 JavaScript 中的闭包是如何工作的"

# 指定模型，格式为 provider/model
opencode run -m anthropic/claude-sonnet-4 "重构 src/utils.ts 里的 debounce 函数"

# 继续上一个会话
opencode run -c "继续之前的任务，把测试补全"

# 继续指定会话
opencode run -s 你的会话ID "帮我 review 一下刚才的改动"

常用参数一览

| 参数 | 简写 | 说明 |
|------|------|------|
| --continue | -c | 继续上一个会话 |
| --session | -s | 继续指定会话 |
| --fork | | 在继续时复制出一个新会话 |
| --model | -m | 指定模型，如 anthropic/claude-sonnet-4 |
| --agent | | 指定使用的 Agent |
| --file | -f | 附加文件到消息中 |
| --format | | 输出格式：default 或 json |
| --title | | 设置会话标题 |
| --attach | | 附加到运行中的 opencode 服务器 |
| --auto | | 自动批准权限请求 |
| --thinking | | 显示思考过程 |

附加文件给 AI

-f 参数可以把文件内容直接附加到提示词中，非常适合针对具体文件提问：

opencode run -f src/components/UserCard.tsx "这段代码有没有内存泄漏问题？"

输出 JSON 便于程序解析

用 --format json 可以让输出变成结构化的 JSON 事件流，方便在脚本中解析结果：

opencode run --format json "添加一个用于计算斐波那契数列的函数" > result.json

三、会话管理：session / export / import

OpenCode 会把每次对话保存为 session，你可以随时查看、导出、删除，甚至把会话分享到别的机器继续。

# 列出最近 10 个会话
opencode session list -n 10

# 以 JSON 格式列出
opencode session list --format json

# 删除指定会话
opencode session delete 会话ID

# 导出指定会话为 JSON（不带 ID 会提示选择）
opencode export

# 导出并脱敏（会抹掉敏感内容和文件数据）
opencode export --sanitize

# 从文件导入会话
opencode import session.json

# 从 OpenCode 分享链接导入
opencode import https://opncd.ai/s/abc123

会话管理让你在不同终端、不同机器之间无缝切换工作上下文，配合 --continue 使用效果更佳。

四、用量统计：stats

AI 编程最关心的问题之一就是花了多少钱。opencode stats 能帮你统计 Token 消耗和成本：

# 查看全部历史用量
opencode stats

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

# 查看 Top 5 最常用的工具
opencode stats --tools 5

# 查看模型使用占比
opencode stats --models 5

# 只看当前项目的用量
opencode stats --project

这个命令对团队核算成本、个人控制预算非常有帮助。

五、服务部署：serve 与 web

OpenCode 可以作为一个无界面的后台服务运行，通过 HTTP API 对外提供能力，非常适合把 AI 能力集成到自己的应用里。

# 启动无头服务器，默认端口随机
opencode serve

# 指定端口，并设置密码启用 Basic Auth
OPENCODE_SERVER_PASSWORD=your-secret opencode serve --port 4096 --hostname 0.0.0.0

# 启动带 Web 界面的服务器，会自动打开浏览器
opencode web --port 4096

# 在另一台终端里，把 TUI 附加到运行中的服务
opencode attach http://10.20.30.40:4096

一个典型的优化技巧是：先启动一个常驻的 opencode serve，再用 opencode run --attach 去复用它的进程，这样可以避免每次运行都重新冷启动 MCP 服务器，速度明显更快：

# 终端一：启动常驻服务
opencode serve

# 终端二：附加到服务上执行任务
opencode run --attach http://localhost:4096 "解释一下 async/await 的用法"

六、认证与模型管理

OpenCode 的认证信息保存在 ~/.local/share/opencode/auth.json 中，命令行提供了完整的增删查操作：

# 交互式登录某个提供商（如 anthropic）
opencode auth login

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

# 查看已认证的提供商列表
opencode auth list

# 退出登录
opencode auth logout

查看所有可用模型，方便确认配置里的模型名：

# 列出所有已配置提供商下的模型
opencode models

# 只看某一个提供商
opencode models anthropic

# 刷新模型缓存（提供商新出了模型时很有用）
opencode models --refresh

# 显示模型的详细元数据（包括价格）
opencode models --verbose

七、Agent 与 MCP 管理

前面发布的文章介绍过 Agent 和 MCP，CLI 也提供了对应的管理命令，而且可以完全非交互式地创建 Agent：

# 列出所有 Agent
opencode agent list

# 交互式创建 Agent
opencode agent create

# 非交互式创建：直接指定路径、描述、模式、权限
opencode agent create --path .opencode/agent --description "只读代码审查" --mode subagent --permissions read,grep,glob

# 添加 MCP 服务器
opencode mcp add

# 查看 MCP 服务器及连接状态
opencode mcp list

注意 --permissions 参数：传入的权限会被允许，没有列出的全部默认拒绝，这是创建受限 Agent 的快捷方式。

八、其他实用命令

# 查看当前版本
opencode --version

# 升级到最新版（可指定安装方式）
opencode upgrade

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

# 查看数据库文件路径
opencode db path

# 直接用 SQL 查询数据库（格式可选 json 或 tsv）
opencode db "select id, title from session limit 10;" --format json

# 安装插件并更新配置
opencode plugin some-plugin

# 完整卸载并清理相关文件（先看会删什么）
opencode uninstall --dry-run

九、权限控制与环境变量

CLI 模式下同样受 permission 配置约束。使用 --auto 可以自动批准非显式拒绝的权限请求，适合无人值守的自动化任务：

opencode run --auto "运行测试并修复失败的用例"

需要注意的是，显式配置为 deny 的规则即使加了 --auto 也依然会被强制执行，这是一个安全兜底。

常用环境变量也值得了解：

# 指定配置文件路径
export OPENCODE_CONFIG=/path/to/opencode.json

# 内联 JSON 配置内容（适合 CI 场景）
export OPENCODE_CONFIG_CONTENT='{"model":"anthropic/claude-sonnet-4"}'

# 内联权限配置
export OPENCODE_PERMISSION='{"bash":{"*":"ask","git *":"allow"}}'

# 为 serve/web 设置 Basic Auth 密码
export OPENCODE_SERVER_PASSWORD=your-secret

# 禁止自动更新检查
export OPENCODE_DISABLE_AUTOUPDATE=1

十、实战：写一个自动化脚本

把以上命令组合起来，我们可以写一个简单的 bash 脚本，实现"批量对多个文件做代码审查"的自动化流程：

#!/bin/bash
# code-review.sh - 批量审查当前 Git 改动的文件

# 1. 获取本次改动的文件列表
files=$(git diff --name-only HEAD)

# 2. 对每个文件逐个交给 OpenCode 审查
for file in $files; do
  echo "=== 审查 $file ==="
  opencode run --auto -f "$file" \
    "请以资深工程师的视角审查此文件，指出潜在 bug、安全问题，并给出修改建议。"
done

# 3. 最后汇总一次用量统计
opencode stats --days 1

这个脚本可以直接扔进 Git hook 或 CI 里使用，让 AI 成为代码质量检查流水线的一环。

总结

OpenCode CLI 是一套被很多人忽略的宝藏能力。它不仅支持非交互式的 opencode run，还涵盖了会话管理、用量统计、后台服务、认证管理、Agent/MCP 运维等方方面面。掌握了这些命令，你就能把 AI 编程能力彻底融入自己的脚本和自动化流程，而不只是停留在交互式对话层面。

建议从今天开始，尝试用 opencode run 替代一些简单的提问，用 opencode stats 盯紧用量，再把 serve + attach 组合用起来，你会发现 AI 编程的效率上限又被拉高了一截。