【AI】opencode 使用手册

OpenCode 命令行使用手册

版本 ：基于 OpenCode 1.14+（2026年7月）

注意 ：OpenCode 是 sst.dev 推出的开源 AI 编码 Agent（GitHub: anomalyco/opencode），与已归档的 opencodenet 无关。

---

一、安装

# 推荐：一键安装脚本
curl -fsSL https://opencode.ai/install | bash

# 或 npm
npm install -g opencode-ai

# 验证
opencode --version

---

二、核心 CLI 命令

命令	说明	示例
opencode	启动 TUI（交互式终端界面）	opencode
opencode [project]	在指定项目目录启动	opencode ./my-project
opencode run "<prompt>"	非交互式单次执行（适合脚本/自动化）	opencode run "解释这段代码"
opencode run -f <file> "<prompt>"	附加文件后执行	opencode run -f ./main.ts "优化这个文件"
opencode serve	启动无头 HTTP 服务器（API 模式）	opencode serve --port 4096
opencode web	启动服务器 + Web UI	opencode web
opencode attach <url>	连接到已运行的服务器	opencode attach http://localhost:4096
opencode models	列出所有可用模型	opencode models --refresh
opencode auth login	登录/配置模型提供商	opencode auth login
opencode auth list	列出已认证的提供商	opencode auth ls
opencode auth logout	退出指定提供商	opencode auth logout
opencode agent create	创建自定义 Agent	opencode agent create
opencode agent list	列出所有 Agent	opencode agent list
opencode upgrade	更新到最新版本	opencode upgrade
opencode stats	查看 Token/成本统计	opencode stats
opencode session list	列出所有会话	opencode session list
opencode export [sessionID]	导出会话为 Markdown	opencode export
opencode import <file>	导入会话	opencode import session.json

---

三、TUI 交互命令（斜杠命令）

在 TUI 中输入 / 查看所有命令。

命令	别名	说明
/connect	---	添加模型提供商 + API Key
/init	---	分析仓库，生成 AGENTS.md 项目记忆文件
/models	---	切换模型
/compact	/summarize	压缩会话上下文，释放 Token
/undo	---	撤销上一次修改（需 Git 仓库）
/redo	---	重做
/sessions	---	切换/管理会话
/share	---	分享会话链接
/export	---	导出会话
/help	---	查看帮助
/goal	---	进入 Goal 模式（规划模式）
/plan	---	仅规划，不执行代码

---

四、TUI 快捷键

快捷键	功能
Ctrl+C / Ctrl+D / Ctrl+X → q	退出
Ctrl+P	命令面板
Ctrl+X → n	新建会话
Ctrl+X → l	列出会话
Ctrl+X → e	在外部编辑器打开
Ctrl+X → b	切换侧边栏
Ctrl+X → s	查看状态
F2	快速切换最近使用的模型
End	滚动到底部
Home / Ctrl+G	滚动到顶部
Enter	提交输入
Shift+Enter / Ctrl+Enter	输入框换行
Escape	中断/取消

---

五、输入模式

模式	语法	说明
文件引用	@path/to/file	附加文件到上下文（支持模糊搜索）
文件引用（行范围）	@File#L37-42	附加指定行
Shell 执行	!ls -la	在消息开头执行 shell 命令
自定义命令	/command-name	执行 .opencode/commands/ 下的自定义命令

---

六、配置

全局配置：~/.config/opencode/opencode.json 或项目根目录 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-4-sonnet",
  "small_model": "anthropic/claude-4-haiku",
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "allow"
  }
}

权限配置

{
  "permission": {
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm test": "allow",
      "rm -rf *": "deny"
    },
    "webfetch": "allow",
    "task": {
      "general": "allow",
      "explore": "allow"
    }
  }
}

---

七、自定义命令

在项目根目录创建 .opencode/commands/：

mkdir -p .opencode/commands

创建 plan.md：

---
description: 仅做战略规划，不实现代码
agent: plan
subtask: true
---

为以下需求创建分步计划：$ARGUMENTS
不要编写或修改任何代码。

使用：/plan 重构认证模块

---

八、自动化/脚本示例

# 1. 非交互式问答
opencode run "总结最近10个 git commit"

# 2. 附加文件
opencode run -f ./design.png "根据这个设计图生成代码"

# 3. 连接到服务器避免冷启动
opencode serve --port 4096 &
opencode run --attach http://localhost:4096 "解释 async/await"

# 4. 指定模型
opencode run --model openai/gpt-4o "优化这段算法"

# 5. 使用 Agent
opencode run --agent plan "设计数据库架构"

# 6. 输出 JSON 格式
opencode run --format json "列出项目依赖"

# 7. 继续上次会话
opencode run -c "继续刚才的任务"

# 8. 指定会话
opencode run -s <session-id> "基于之前的上下文..."

---

九、本地模型配置（隐私场景）

# 1. 配置本地 Ollama 提供商
opencode auth login
# 选择 "other" → Provider ID: ollama → API Key: 任意（如 ollama）

# 2. 在 opencode.json 中指定
{
  "model": "ollama/llama3.1:8b"
}

---

十、快速参考

┌─────────────────────────────────────────────┐
│  opencode              → 启动 TUI           │
│  opencode run "..."    → 单次执行           │
│  opencode serve        → 启动 API 服务器    │
│  opencode models       → 查看模型列表       │
│  opencode auth login   → 配置 API Key       │
│  /init                 → 生成 AGENTS.md     │
│  /compact              → 压缩上下文         │
│  @file                 → 引用文件           │
│  !cmd                  → 执行 shell         │
└─────────────────────────────────────────────┘