opencode - 常用命令&自定义命令

nlpming
17 阅读2分钟

opencode - 常用命令&自定义命令

基本用法

opencode          # 启动 TUI 界面（默认）
opencode --help   # 查看帮助
opencode --version # 查看版本

TUI 启动

opencode [project]               # 启动 TUI，可指定项目目录
opencode -c                      # 继续上次会话
opencode -s <sessionID>          # 继续指定会话
opencode --fork -s <sessionID>   # Fork 指定会话
opencode -m anthropic/claude-sonnet-4-5  # 指定模型启动
opencode --agent build           # 指定 Agent 启动

TUI 内消息技巧

  • @filename — 模糊搜索并引用文件，文件内容自动加入对话
  • !ls -la — 以 ! 开头直接运行 shell 命令，输出作为工具结果
  • /command — 输入 / 执行 slash 命令

TUI Slash 命令

默认 leader 键为 ctrl+x。

命令快捷键说明
/helpctrl+x h显示帮助
/new /clearctrl+x n开始新会话
/sessions /resumectrl+x l列出并切换会话
/modelsctrl+x m列出可用模型
/themesctrl+x t列出可用主题
/compact /summarizectrl+x c压缩当前会话上下文
/sharectrl+x s分享当前会话
/unshare取消分享
/undoctrl+x u撤销上条消息及文件变更（需 Git）
/redoctrl+x r重做已撤销的消息（需 Git）
/editorctrl+x e用外部编辑器撰写消息
/exportctrl+x x导出对话为 Markdown 并打开编辑器
/detailsctrl+x d切换工具执行详情显示
/thinking切换模型思考过程显示
/initctrl+x i引导创建/更新 AGENTS.md
/connect添加提供商 API Key
/exit /quit /qctrl+x q退出 opencode

TUI 编辑器配置

/editor 和 /export 命令使用 EDITOR 环境变量指定的编辑器：

export EDITOR=vim
export EDITOR="code --wait"   # VS Code 需加 --wait
export EDITOR="cursor --wait"

TUI 配置文件（tui.json）

与 opencode.json 同目录，单独控制界面行为：

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "keybinds": { "leader": "ctrl+x" },
  "scroll_speed": 3,
  "scroll_acceleration": { "enabled": true },
  "diff_style": "auto",   // auto | stacked
  "mouse": true
}

使用 OPENCODE_TUI_CONFIG 环境变量可指定自定义 TUI 配置路径。

run — 非交互模式

直接传入提示词，适合脚本和自动化：

opencode run "解释 Go 中 context 的用法"
opencode run -m anthropic/claude-sonnet-4-5 "审查这段代码"
opencode run -f main.go "分析这个文件"           # 附加文件
opencode run -c "继续上次的任务"                  # 继续上次会话
opencode run --share "生成一份报告"               # 运行并分享会话

# 附加到已运行的 serve 实例（避免 MCP 冷启动）
opencode serve
opencode run --attach http://localhost:4096 "解释 async/await"
参数说明
-c / --continue继续上次会话
-s / --session指定会话 ID
--forkFork 会话后继续
-m / --model指定模型
--agent指定 Agent
-f / --file附加文件
--share分享会话
--attach附加到运行中的服务
--format输出格式：default 或 json
--dangerously-skip-permissions自动批准权限（慎用）

serve / web / attach — 服务命令

opencode serve                              # 启动无界面 HTTP API 服务
opencode serve --port 4096 --hostname 0.0.0.0  # 对外暴露
OPENCODE_SERVER_PASSWORD=xxx opencode serve # 启用认证

opencode web                                # 启动带 Web UI 的服务
opencode web --port 4096 --hostname 0.0.0.0 --mdns

opencode attach http://localhost:4096       # 将 TUI 附加到远程服务

auth — 认证管理

opencode auth login    # 配置 API Key（交互式）
opencode auth list     # 列出已认证的提供商
opencode auth ls       # 同上（简写）
opencode auth logout   # 退出指定提供商

凭证存储在 ~/.local/share/opencode/auth.json。

models — 模型管理

opencode models                  # 列出所有可用模型
opencode models anthropic        # 过滤指定提供商
opencode models --refresh        # 刷新模型缓存
opencode models --verbose        # 显示详细信息（含费用）

session — 会话管理

opencode session list             # 列出所有会话
opencode session list -n 10       # 最近 10 条
opencode session list --format json  # JSON 格式输出

opencode export <sessionID>       # 导出会话为 JSON
opencode export                   # 交互式选择会话导出

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

agent — Agent 管理

opencode agent list               # 列出所有 Agent
opencode agent create             # 交互式创建 Agent

# 非交互式创建
opencode agent create \
  --description "专注于代码审查的助手" \
  --mode primary \
  --permissions bash,read,edit,grep \
  --model anthropic/claude-sonnet-4-5

mcp — MCP 服务器管理

opencode mcp list               # 列出已配置的 MCP 服务器
opencode mcp ls                 # 同上（简写）
opencode mcp add                # 交互式添加 MCP 服务器
opencode mcp auth [name]        # OAuth 认证
opencode mcp auth list          # 列出支持 OAuth 的服务器
opencode mcp logout [name]      # 移除 OAuth 凭证
opencode mcp debug <name>       # 调试 OAuth 连接问题

stats — 用量统计

opencode stats                   # 查看 token 用量和费用统计
opencode stats --days 7          # 最近 7 天
opencode stats --models 5        # 显示 Top 5 模型用量
opencode stats --tools 10        # 显示 Top 10 工具用量
opencode stats --project myapp   # 过滤指定项目

github — GitHub 集成

opencode github install          # 在仓库中安装 GitHub Agent
opencode github run              # 运行 GitHub Agent（通常在 CI 中使用）
opencode github run --event pull_request --token <token>

upgrade / uninstall

opencode upgrade                 # 升级到最新版本
opencode upgrade v0.1.48         # 升级到指定版本
opencode upgrade -m brew         # 指定安装方式（curl/npm/pnpm/bun/brew）

opencode uninstall               # 卸载 opencode
opencode uninstall --keep-config # 保留配置文件
opencode uninstall --keep-data   # 保留会话数据
opencode uninstall --dry-run     # 预览将删除的内容
opencode uninstall -f            # 跳过确认直接卸载

自定义命令

自定义命令让你预设提示词模板，在 TUI 中用 /命令名 触发。

创建方式一：Markdown 文件

将 .md 文件放入以下目录，文件名即命令名：

  • 全局：~/.config/opencode/commands/
  • 项目：.opencode/commands/
---
description: 运行测试并显示覆盖率
agent: build
model: anthropic/claude-sonnet-4-5
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

在 TUI 中使用：

/test

创建方式二：opencode.json 配置

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.",
      "description": "运行测试",
      "agent": "build",
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}

命令选项

选项必填说明
template是发送给 LLM 的提示词
description否TUI 中显示的描述
agent否指定执行的 Agent，默认使用当前 Agent
model否覆盖默认模型
subtask否强制作为子任务执行，不污染主上下文

提示词占位符

传入参数：

---
description: 创建 React 组件
---

Create a new React component named $ARGUMENTS with TypeScript support.

/component Button       # $ARGUMENTS → Button

多个参数用位置变量：

Create a file named $1 in the directory $2 with content: $3

/create-file config.json src "{}"

注入 shell 命令输出：

---
description: 分析测试覆盖率
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements.

引用文件内容：

---
description: 审查组件
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

注意：  自定义命令可覆盖内置命令（如 /help、/undo 等）。

全局参数

参数简写说明
--help-h显示帮助
--version-v打印版本号
--print-logs将日志输出到 stderr
--log-level日志级别：DEBUG / INFO / WARN / ERROR

常用环境变量

变量说明
OPENCODE_SERVER_PASSWORD启用 serve/web 的 HTTP Basic Auth
OPENCODE_SERVER_USERNAME覆盖认证用户名（默认 opencode）
OPENCODE_CONFIG自定义配置文件路径
OPENCODE_CONFIG_CONTENT内联 JSON 配置
OPENCODE_CONFIG_DIR配置目录路径
OPENCODE_PERMISSION内联 JSON 权限配置
OPENCODE_AUTO_SHARE自动分享会话
OPENCODE_DISABLE_AUTOUPDATE禁用自动更新检查
OPENCODE_DISABLE_AUTOCOMPACT禁用自动上下文压缩
OPENCODE_DISABLE_MOUSE禁用 TUI 鼠标支持
avatar
文章
阅读
粉丝