还在手动敲命令？OpenCode CLI 这 10+ 实用命令让你的开发效率起飞

OpenCode 命令使用教程

熟练使用 CLI 命令是高效驾驭 OpenCode 的基础。OpenCode 提供了丰富的命令行工具集——从启动交互界面（TUI）、执行非交互任务，到管理模型与代理、部署远程服务、集成 GitHub 等工作流——覆盖了本地开发到自动化运维的全场景。本文将系统讲解 OpenCode CLI 基础命令、核心功能、TUI 自定义命令、快捷键配置以及环境变量，同时补充实战场景与最佳实践，帮助开发者全面掌握 OpenCode 的使用方法。

一、快速入门：基础启动与全局标志

1.1 基础启动命令

OpenCode CLI 无参数运行时，默认启动终端交互界面（TUI），这是最常用的使用方式：

# 启动默认 TUI 交互界面
opencode

# 指定项目目录，启动 TUI 并绑定对应项目
opencode [项目路径]

1.2 全局通用标志

所有 OpenCode 命令均支持以下全局标志，用于基础功能控制：

示例：

# 查看 OpenCode 版本
opencode -v

# 查看 run 命令帮助
opencode run -h

二、核心 CLI 命令详解

OpenCode 提供十余类细分命令，覆盖交互运行、服务部署、代理管理、认证授权、会话运维、第三方集成等场景，下面按功能分类逐一讲解。

2.1 交互运行类命令

2.1.1 run（非交互执行指令）

run 是高频命令，用于非交互模式直接传入提示词执行任务，适配脚本编写、自动化批量处理、快速问答等场景，无需启动完整 TUI。
语法：

opencode run [提示词内容]

常用标志：

实战示例：

# 快速提问：解释 JavaScript 闭包
opencode run "Explain how closures work in JavaScript"

# 指定模型并附加代码文件提问
opencode run -m anthropic/claude-3.5-sonnet -f main.go "优化这段 Go 代码"

# 连接本地 serve 服务执行指令（双终端配合）
# 终端1：启动无界面服务
opencode serve
# 终端2：连接服务并执行指令
opencode run –attach http://localhost:4096 "讲解 JS async/await 原理"

2.1.2 attach（连接远程后端服务）

用于将本地 TUI 连接到通过 serve 或 web 启动的远程 OpenCode 后端，实现多终端共享远程服务。
语法：

opencode attach [远程服务URL]

附加标志：

• –dir：指定 TUI 启动的工作目录

• –session/-s：接续指定会话 ID

实战示例：

# 终端1：启动带 Web 界面的远程服务，监听 4096 端口
opencode web –port 4096 –hostname 0.0.0.0

# 终端2：本地 TUI 连接远程服务
opencode attach http://10.20.30.40:4096

2.2 代理管理命令（agent）

用于管理 OpenCode 自定义代理，支持创建、查看代理列表。
基础语法：

opencode agent [子命令]

opencode agent create

opencode agent list

2.3 认证凭据命令（auth）

管理 AI 提供商的 API 密钥与登录状态，密钥默认存储路径：~/.local/share/opencode/auth.json。OpenCode 同时兼容环境变量、项目 .env 文件中的密钥配置。
基础语法：

opencode auth [子命令]

opencode auth login

opencode auth list
# 简写形式
opencode auth ls

opencode auth logout

2.4 GitHub 仓库集成命令（github）

专为 GitHub 仓库自动化设计，用于配置和运行 GitHub 代理，对接 GitHub Actions 工作流。
基础语法：

opencode github [子命令]

opencode github install

opencode github run –token "你的GitHub令牌"

2.5 MCP 服务器管理命令（mcp）

管理 Model Context Protocol（MCP）服务器，支持添加、查看、认证、排障等操作。
基础语法：

opencode mcp [子命令]

opencode mcp add

opencode mcp ls

2.6 模型管理命令（models）

查看已配置提供商的所有可用模型，可刷新模型缓存、查看模型费用等元数据。
基础语法：

opencode models [提供商ID]

附加标志：

• –refresh：从 models.dev 刷新本地模型缓存（提供商新增模型时使用）

• –verbose：展示模型详细元数据（包含调用费用、参数等）

示例：

# 查看 Anthropic 提供商下的所有模型
opencode models anthropic

# 全局刷新模型缓存
opencode models –refresh

# 查看全量模型及费用信息
opencode models –verbose

2.7 服务部署命令

2.7.1 serve（无界面 API 服务）

启动纯后台 HTTP 服务，对外提供 OpenCode API 接口，无前端界面。可通过环境变量 OPENCODE_SERVER_PASSWORD 开启 HTTP 基础认证（默认用户名：opencode）。
语法：

opencode serve

附加标志：

• –port：指定监听端口

• –hostname：指定监听主机名

• –mdns：启用 mDNS 服务发现

• –cors：配置允许跨域的浏览器源

2.7.2 web（带 Web 界面服务）

启动 HTTP 服务并自动打开浏览器，通过 Web 界面访问 OpenCode，参数与 serve 完全一致。

# 启动 Web 服务，监听 8080 端口
opencode web –port 8080

2.7.3 acp（ACP 协议服务器）

启动 Agent Client Protocol（ACP）服务器，基于 stdin/stdout 通过 nd-JSON 格式通信。
附加标志：–cwd（指定工作目录）、–port、–hostname。

opencode acp –cwd ./project

2.8 会话管理与统计命令

2.8.1 session（会话管理）

管理所有历史对话会话，核心子命令为 list。
语法：

opencode session list

附加标志：

• -n/–max-count：限制展示最近 N 条会话

• –format：输出格式，支持 table（默认表格）/json

2.8.2 export /import（会话导入导出）

用于会话备份、分享与迁移。

# 导出指定会话为 JSON 文件（不传 ID 则交互式选择）
opencode export [会话ID]

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

2.8.3 stats（用量统计）

统计会话的 Token 消耗、调用费用、模型用量等数据。
附加标志：

• –days：统计最近 N 天数据

• –models：展示模型用量明细

• –project：按项目筛选统计数据

# 统计最近 7 天全项目用量及模型明细
opencode stats –days 7 –models

2.9 运维命令（卸载 / 升级）

2.9.1 uninstall（卸载 OpenCode）

卸载程序并清理相关文件，支持保留配置、模拟删除等操作。
常用标志：

• -c/–keep-config：保留配置文件

• -d/–keep-data：保留会话数据与快照

• –dry-run：模拟删除，仅展示待删除文件（不实际执行）

• -f/–force：跳过确认，强制卸载

# 模拟卸载，保留配置文件
opencode uninstall –dry-run -c

2.9.2 upgrade（版本升级）

升级 OpenCode 至最新版本或指定历史版本。

# 升级到最新版本
opencode upgrade

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

# 指定安装方式升级（curl/npm/pnpm/brew 等）
opencode upgrade –method npm

三、TUI 自定义命令

OpenCode TUI 内置 /init、/undo、/redo、/share、/help 等基础斜杠命令，同时支持自定义命令，用于固化重复提示词、简化高频操作，自定义命令可覆盖同名内置命令。

3.1 命令存放目录

自定义命令分为全局命令和项目级命令，优先级：项目级 > 全局：

3.2 两种创建方式

3.2.1 Markdown 文件（推荐）

在上述目录中创建 .md 文件，文件名即为命令名，文件分为两部分：顶部 frontmatter 配置元数据，正文为提示词模板。

示例：.opencode/commands/test.md（项目级测试命令）

—
description: 运行测试并生成覆盖率报告
agent: build
model: anthropic/claude-3-5-sonnet-20241022
—
运行完整测试套件并输出覆盖率报告，定位失败用例并给出修复方案。

使用方式：进入 TUI 后输入以下指令执行：

/test

3.2.2 JSON 配置（opencode.jsonc）

在项目根目录 opencode.jsonc 中通过 command 节点配置命令，适合集中管理多条自定义命令。

{
"$schema": "https://opencode.ai/config.json",
"command": {
"test": {
"template": "运行完整测试套件并输出覆盖率报告，定位失败用例并给出修复方案。",
"description": "运行测试并生成覆盖率报告",
"agent": "build",
"model": "anthropic/claude-3-5-sonnet-20241022"
}
}
}

3.3 高级占位符语法

自定义命令支持三类占位符，实现动态传参、注入系统信息，大幅提升灵活性。

3.3.1 参数传递

用于向命令传递自定义参数：

示例 1：创建组件命令 .opencode/commands/component.md

—
description: 创建 TypeScript React 组件
—
创建名为 $ARGUMENTS 的 React + TypeScript 组件，补充基础类型定义。

使用：/component Button，$ARGUMENTS 会被替换为 Button。

示例 2：多参数文件创建命令

—
description: 新建文件
—
在 $2 目录下创建文件 $1，文件内容：$3

使用：/create-file config.json src "{"key":"value"}"。

3.3.2 Shell 输出注入

使用 !+shell命令 将终端命令输出注入提示词，自动读取系统 / 项目实时状态。

注意：Shell 命令以当前项目根目录为执行路径，请勿执行包含敏感信息或高危操作的指令。

示例（查看 Git 最近提交）：

—
description: 评审近期代码提交
—
以下是最近 10 条 Git 提交记录：
!`git log –oneline -10`
基于提交记录给出代码优化建议。

3.3.3 文件引用

使用 @文件路径 引用项目文件，文件内容会自动加载到对话上下文。

—
description: 代码评审
—
评审 @src/components/Button.tsx 组件，检查性能问题并优化。

3.4 核心配置字段说明

四、TUI 快捷键配置与使用

OpenCode TUI 提供全套快捷键，支持自定义修改，默认采用 前导键（Leader Key） 机制，避免与终端原生快捷键冲突。

4.1 前导键机制

• 默认前导键：ctrl+x，绝大多数组合快捷键需要先按前导键，再按功能键。

• 示例：新建会话快捷键 <leader>n，实际操作：按下 ctrl+x → 松开 → 按下 n。

4.2 常用默认快捷键

4.2.1 全局功能快捷键

4.2.2 输入框专属快捷键（Emacs 风格）

输入框内置文本编辑快捷键，无需配置，通用所有终端：

4.3 自定义快捷键

快捷键配置文件为 tui.json，仅需修改需要自定义的项，未配置项沿用默认值；将快捷键设为 none 可禁用该功能。

基础配置示例：

{
"$schema": "https://opencode.ai/tui.json",
"keybinds": {
// 修改前导键为 ctrl+z
"leader": "ctrl+z",
// 禁用会话压缩快捷键
"session_compact": "none",
// 绑定多快捷键到消息复制功能
"messages_copy": "<leader>y, ctrl+shift+c"
}
}

4.4 Windows Terminal 适配（Shift+Enter）

部分 Windows 终端默认不识别 Shift+Enter，需手动修改配置：

"actions": [
{
"command": { "action": "sendInput", "input": "\\u001b[13;2u" },
"id": "User.sendInput.ShiftEnterCustom"
}
]

"keybindings": [
{ "keys": "shift+enter", "id": "User.sendInput.ShiftEnterCustom" }
]

五、环境变量配置

OpenCode 支持通过环境变量实现全局配置，分为基础配置、服务安全、功能开关、实验性功能四大类，可临时在终端设置，或写入系统环境变量永久生效。

5.1 常用基础环境变量

5.2 服务认证环境变量

用于 serve/web 服务开启密码认证：

• OPENCODE_SERVER_PASSWORD：设置服务访问密码（必填）

• OPENCODE_SERVER_USERNAME：自定义登录用户名（默认：opencode）

5.3 功能开关环境变量

5.4 实验性功能变量

以 OPENCODE_EXPERIMENTAL_ 为前缀，用于启用内测功能，例如：

• OPENCODE_EXPERIMENTAL：一次性启用所有实验功能

• OPENCODE_EXPERIMENTAL_PLAN_MODE：启用计划模式

• OPENCODE_EXPERIMENTAL_FILEWATCHER：启用全局文件监听

六、实战最佳实践

# 批量检查当前目录所有 JS 文件语法
opencode run "检查当前目录所有 JS 文件语法错误并给出修复建议"

七、总结

OpenCode CLI 是连接开发者与 AI 能力的核心入口，整体能力可分为三大板块：

日常交互式开发优先使用 TUI + 自定义命令；自动化、CI/CD 场景使用 opencode run + GitHub 代理；多人远程协作推荐 serve/web + attach 组合。熟练掌握以上命令与配置，可充分发挥 OpenCode 在代码开发、审查、自动化运维中的价值。