opencode - 快速入门 - Seepine's Blog

本文演示一套 opencode 快速入门配置：关闭分享、固定模型、接入自定义 Provider、限制危险命令，并调整 TUI 快捷键。

示例配置偏向个人开发环境，可按需删减。若部署到公网或多人共用环境，务必重新检查端口、密码和权限策略。

一、配置

1. 配置目标

opencode 安装后即可启动。为了更适合日常开发使用，本文先完成一套基础配置，再演示如何接入自定义模型服务：

禁用分享，避免误把会话内容上传到 opencode 后端。
禁用模型信息自动拉取，避免自定义模型被远端模型列表干扰。
配置权限白名单，常用只读命令自动放行，危险命令直接拒绝。
配置 MCP，例如 chrome-devtools-mcp 和 llmstxt-mcp。
配置 TUI 快捷键，尽量接近 Claude Code 的操作体验。

本文配置文件主要涉及两个位置：

1 2	~/.config/opencode/opencode.jsonc ~/.config/opencode/tui.jsonc

2. 设置环境变量

建议先在 ~/.zshrc 或 ~/.bashrc 中配置环境变量。

# opencode
export OPENCODE_DISABLE_MODELS_FETCH=1
export OPENCODE_SERVER_PASSWORD="<your-password>"

oc() {
  # oc 启动全自动模式，建议在容器中或虚拟机才开启auto模式
  echo "opencode --auto $*"
  opencode --auto "$@"
}
# opencode end

几个变量说明：

OPENCODE_DISABLE_MODELS_FETCH=1：禁用自动更新模型信息。自定义 Provider 或中转服务建议关闭。
OPENCODE_SERVER_PASSWORD：opencode Web 登录密码，用户名默认为 opencode。

修改后执行以下命令让配置生效：

1	source ~/.zshrc

若使用的是 Bash，则执行：

1	source ~/.bashrc

3. 主配置文件

编辑 ~/.config/opencode/opencode.jsonc。

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false,  // 禁用自动更新
  "share": "disabled",  // 禁用分享，避免上传会话内容

  // opencode web 启动配置，建议同时配置 OPENCODE_SERVER_PASSWORD，访问时使用账号 opencode 和该密码登录
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0"
  },

  // 权限配置
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    },
    "edit": {
      "*": "allow",
      ".git/*": "deny"
    },
    "bash": {
      // 越后面的规则优先级越高，兜底 ask 放前面
      "*": "ask",

      // 常用只读命令直接允许
      "rg *": "allow",
      "ls *": "allow",
      "rtk git diff*": "allow",
      "rtk git status*": "allow",
      "git diff*": "allow",
      "git status*": "allow",

      // 危险命令直接拒绝
      "rm -rf*": "deny",

      // 常用检查命令直接允许
      "pnpm check*": "allow",
      "pnpm lint*": "allow",
      "bun check*": "allow",
      "bun lint*": "allow"
    },

    // 安全防护：跳出当前项目目录时询问
    "external_directory": "ask"
  },

  // mcp 配置，按需选择
  "mcp": {
    "chrome-dev": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "chrome-devtools-mcp@latest",
        "--no-usage-statistics"
      ]
    },
    "llmstxt": {
      "type": "local",
      "command": ["npx", "-y", "llmstxt-mcp"]
    }
  },

  "model": "{env:OPENCODE_DEFAULT_MODEL}",

  // 禁用 opencode 默认 Provider，避免排到自定义 Provider 前面
  // 若需要官方 Provider，可按需删除
  "disabled_providers": ["opencode"],

  // 自定义提供商在后面章节详细说明
  "provider": {
  }
}

4. TUI 配置文件

编辑 ~/.config/opencode/tui.jsonc。

{
  "$schema": "https://opencode.ai/tui.json",

  "keybinds": {
    // 默认支持 ctrl+z 挂起，临时跑命令例如 pnpm i，再使用 fg 恢复
    // 若怕误触 ctrl+z，可改为：
    // "terminal_suspend": "none"

    // 接近 Claude Code 的体验：ctrl+c 优先清空输入，再停止 agent，最后才退出
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    "session_interrupt": "escape,ctrl+c",
    "input_clear": "ctrl+c"
  },

  // 开启 TUI 桌面通知
  "attention": {
    "enabled": true
  }
}

此处最主要的调整是 ctrl+c 行为，特别是如果习惯了 Claude Code 的操作。

二、自定义 Provider

自定义提供商拆成两个常见场景，自行按需选择，当然也可以多个模型提供商共存。

1. OpenAI Chat / Responses

先配置环境变量。

1
2
3

export OPENCODE_OPENAI_BASE_URL=https://api.openai.com/v1
export OPENCODE_OPENAI_API_KEY=<your-api-key>
export OPENCODE_DEFAULT_MODEL=my-openai/gpt-5.5

{
  "model": "{env:OPENCODE_DEFAULT_MODEL}",
  "provider": {
    "my-openai": {
      "name": "my-openai",
      "npm": "@ai-sdk/openai-compatible",
      // Responses 接口使用这个
      // "npm": "@ai-sdk/openai",
      "options": {
        "baseURL": "{env:OPENCODE_OPENAI_BASE_URL}",
        "apiKey": "{env:OPENCODE_OPENAI_API_KEY}"
      },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "tool_call": true,
          // 开启思考
          "reasoning": true,
          // 附件多模态功能
          "attachment": true,
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          },
          // 配置上下文
          "limit": {
            "context": 1050000,
            "input": 922000,
            "output": 128000
          }
        }
      }
    }
  }
}

2. Anthropic

1
2
3

export OPENCODE_ANTHROPIC_BASE_URL=https://api.anthropic.com/v1
export OPENCODE_ANTHROPIC_API_KEY=<your-api-key>
export OPENCODE_DEFAULT_MODEL=my-anthropic/minimax-m3

Provider 配置如下。

{
  "model": "{env:OPENCODE_DEFAULT_MODEL}",
  "provider": {
    "my-anthropic": {
      "name": "my-anthropic",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "{env:OPENCODE_ANTHROPIC_BASE_URL}",
        "apiKey": "{env:OPENCODE_ANTHROPIC_API_KEY}"
      },
      "models": {
        "minimax-m3": {
          "name": "minimax-m3",
          "tool_call": true,
          // anthropic 接口的模型思考配置
          "options": {
            "thinking": {
              "type": "enabled",
              "budgetTokens": 16000
            }
          },
          // 多模态
          "attachment": true,
          "modalities": {
            "input": ["text", "image", "pdf"],
            "output": ["text"]
          },
          // 上下文
          "limit": {
            "context": 1050000,
            "input": 922000,
            "output": 128000
          }
        }
      }
    }
  }
}

3. 注意点

提供商标识不能和默认的重复，所以建议自定义提供商标识增加前缀

{
  "provider": {
    "my-openai": {
    },
    "my-anthropic": {
    }
  }
}

是否支持思考、是否多模态、以及上下文数量，建议问 AI 后修改，或者直接去除

三、启动验证

1. 检查配置是否加载

可以执行：

1	opencode debug config

重点确认以下内容：

share 是否为 disabled。
permission 是否按预期加载。
model 是否解析为环境变量中的值。
provider 自定义模型提供商是否正确。

2. 启动 TUI

opencode

若需要全自动模式，可以使用上面定义的函数：

oc

3. 启动 Web

1	opencode web

然后访问：

1	http://127.0.0.1:4096

如果是在局域网其他设备访问，将 127.0.0.1 替换为运行 opencode 的机器 IP。

输入用户名和密码

用户名：opencode
密码：环境变量设置的密码

四、添加全局指令 AGENTS.md

除了每个项目中添加 AGENTS.md 文件之外，建议也添加全局指令，编辑 ~/.config/opencode/AGENTS.md，并输入你设置的指令即可

- 使用中文交流
- 任务开始前，使用 karpathy-guidelines 技能协助思考
- 需要搜索查看文档时，优先使用 llmstxt 相关工具
- 若用户没有要求，不要执行 `git commit/pull/push` 这类敏感操作

五、添加技能

https://github.com/seepine/skills

执行命令安装技能合集，包含编码实践、协作流程等入侵性低的技能，若不需要claude和codex，可去掉 -a claude-code -a codex 参数

1	npx -y skills add https://github.com/seepine/skills -a opencode -a claude-code -a codex -g

编码实践

Skill	描述
`karpathy-guidelines`	降低 LLM 编码时的常见问题，强调简单、克制、明确假设和可验证结果。
`code-simplifier`	在代码修改后进行简化和清理，提升可读性与一致性，同时保持功能不变。

协作流程

Skill	描述
`git-guide`	基于 git 开发指南，阐述如何使用 Fork 和 PR 通过 git 协同开发。
`gh-cli`	GitHub CLI 使用参考，用于通过命令行管理 GitHub 仓库、Issue、PR 和 Actions 等。
`gitea-cli`	Gitea CLI 使用参考，用于通过命令行管理 Gitea 仓库、Issue、PR、评审和 Actions 等。
`gitea-workflow`	Gitea 工单处理工作流，用于认领工单、创建分支、提交 PR 和根据评审意见修订。

文案推广

Skill	描述
`copywriting-formula`	使用“现象 + 危害 + 原因 + 解决办法”公式撰写和改写更有转化感的文案。

六、添加MCP

1. MCP 配置

编辑 ~/.config/opencode/opencode.jsonc。

{
  // ...

  // mcp 配置
  "mcp": {
    "chrome-dev": {
      // stdio 类型
      "type": "local",
      "command": [
        "npx",
        "-y",
        "chrome-devtools-mcp@latest",
        "--no-usage-statistics"
      ]
    },
    "llmstxt": {
      "type": "local",
      "command": ["npx", "-y", "llmstxt-mcp"],
      "env": {}
    },
    "web-search": {
      // http 类型
      "type": "remote",
      "url": "https://example.com/remote-api/mcp/",
      "headers": {
        "Authorization": "Bearer xxxxxxxxx"
      },
    }
    // 添加更多...
  },

  // ...
}

2. 测试 MCP

启动后可以在左下角看到 MCP 服务数量，也可以在对话框中通过命令 /mcps 配置每个MCP的启用禁用

opencode

以 llmstxt 为例测试是否成功，在对话输入以下内容

1
2
3

使用 llmstxt 添加以下文档
- bunDocs: https://bun.com/llms.txt
- vuejsDocs: https://cn.vuejs.org/llms.txt

llmstxt-mcp 是一个文档管理 MCP，让所有agent都拥有类似于 TRAE 的 Docs 管理功能，目前常见的语言或框架官网，基本都已提供 llms.txt 文件链接