Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

电脑基础操作

这篇教程讲 WorkBuddy、OpenCode 和 Codex 使用时会用到的电脑基础操作。
如果你已经熟悉终端、命令和 JSON 配置文件，可以直接进入 OpenCode 安装与配置（推荐）。

先确认你的电脑系统

安装包必须与操作系统匹配，不能混用。
按 Windows + R，输入 winver，再按 Enter。
弹出的窗口会显示 Windows 版本。大多数电脑使用 64 位 Windows，应下载文件名包含 x64 或 64-bit 的安装包。

认识常见安装包

文件后缀适用系统如何安装
.msi、.exeWindows双击文件，按照安装向导操作
.pkg、.dmgmacOS双击打开；PKG 按向导安装，DMG 通常拖入 Applications
.debDebian、Ubuntu双击后使用软件中心安装
.rpmFedora、RHEL双击后使用软件中心安装
.zip、.tar.gz、.tar.xz压缩包需要解压和手动配置，新手优先选择上面的安装包
下载时优先选择 MSI、PKG、DMG、DEB 或 RPM。除非教程明确要求，否则新手不要下载“源代码”或压缩包。

如何下载和找到文件

  1. 点击教程中的下载链接。
  2. 浏览器询问保存位置时，可以直接选择 下载 文件夹。
  3. 下载完成后，点击浏览器右上角的下载图标。Windows 浏览器通常也可以按 Ctrl+J 打开下载记录。
  4. 点击文件名或 在文件夹中显示。
  5. 双击安装包开始安装。
只从教程列出的官网地址下载安装包。不要使用搜索结果中的广告下载站，也不要运行来源不明的安装程序。

如何打开命令行窗口

命令行窗口是输入安装命令的地方。教程中的代码不能粘贴到浏览器地址栏、搜索框或聊天窗口。
普通打开方式：
  1. 点击屏幕底部的 开始菜单。
  2. 输入 PowerShell。
  3. 点击 Windows PowerShell 或 PowerShell。
需要管理员权限时：
  1. 在搜索结果中右键点击 PowerShell。
  2. 选择 以管理员身份运行。
  3. 系统询问“是否允许此应用更改你的设备”时，点击 是。

如何复制并执行命令

例如教程显示：
npm install -g opencode-ai
正确操作：
  1. 只复制灰色代码框中的命令，不要复制代码框外的说明文字。
  2. 点击 PowerShell 或终端窗口。
  3. 粘贴命令。
  4. 按 Enter 执行。
  5. 等待命令执行结束，再执行下一条。
系统复制粘贴
WindowsCtrl+CCtrl+V 或鼠标右键
macOSCommand+CCommand+V
Linux 终端Ctrl+Shift+CCtrl+Shift+V
不要复制命令前面的 $、>、PS C:\> 等提示符。教程代码框中没有这些提示符时，不需要自己添加。

命令执行后看起来没有反应

  • 有些安装命令需要下载文件，请等待几分钟。
  • 光标仍在闪烁，且没有出现新的输入行，通常表示命令还在运行。
  • 出现新的输入行，表示上一条命令已经结束。
  • 不要连续多次按 Enter 或重复运行安装命令。

如何停止卡住的命令

先等待一段时间。如果确认命令长时间没有变化，可以点击终端窗口并按 Ctrl+C 停止。这里的 Ctrl+C 表示停止命令，不是复制文字。

认识文件路径

文件路径表示文件在电脑中的位置。
写法含义
~当前用户的个人文件夹，macOS 和 Linux 使用
$HOME当前用户的个人文件夹，PowerShell、macOS 和 Linux 可识别
%USERPROFILE%Windows 当前用户的个人文件夹
/macOS 和 Linux 的路径分隔符
\Windows 常用的路径分隔符
OpenCode 的全局配置文件位置：
  • Windows：%USERPROFILE%\.config\opencode\opencode.json
  • macOS：~/.config/opencode/opencode.json
  • Linux：~/.config/opencode/opencode.json
以点开头的 .config 文件夹通常是隐藏文件夹。看不到它是正常的，安装教程中的命令会自动创建并打开它。

如何编辑配置文件

OpenCode 使用 opencode.json 保存模型和接口配置。JSON 是纯文本文件，不是 Word 文档。Codex 订阅用户通常不需要编辑配置文件。

Windows 使用记事本

安装教程会用命令自动打开记事本。粘贴配置后：
  1. 按 Ctrl+S 保存。
  2. 如果出现“另存为”，将 保存类型 选择为 所有文件。
  3. 文件名填写 opencode.json。
  4. 编码选择 UTF-8。
文件不能保存为 opencode.json.txt。如果名称错误，OpenCode 将无法读取配置。

macOS 和 Linux 使用 nano

安装教程会在终端中打开 nano 编辑器：
  1. 粘贴配置内容。
  2. 按 Ctrl+O 保存。
  3. 按 Enter 确认文件名。
  4. 按 Ctrl+X 退出。
nano 底部显示的 ^O 表示 Ctrl+O，不是输入 ^ 字符。

JSON 配置注意事项

正确的 JSON 使用英文符号：
{
  "name": "TokenFlash",
  "enabled": true
}
常见错误：
  • 使用中文引号 “ ”，正确写法是英文双引号 " "。
  • 使用中文逗号 ，，正确写法是英文逗号 ,。
  • 最后一项后面多写了逗号。
  • 不小心删除了 {、}、[ 或 ]。
  • 只复制了配置的一部分。
建议直接完整复制教程中的配置，只替换明确要求修改的 API Key，不要手动调整其他符号。

什么是 API Key

API Key 类似服务密码，用于确认账户身份和扣除调用额度。
不要把 API Key 发给他人，不要上传到 GitHub，不要在公开截图中展示，也不要让远程协助人员复制。API Key 泄露后应立即前往控制台删除并重新创建。
复制 API Key 时注意：
  • 不要复制前后的空格。
  • 不要添加中文引号。
  • 粘贴到 JSON 后，要保留原有英文双引号。

为什么修改后要重启

很多程序只在启动时读取配置。修改 opencode.json 后：
  1. 保存配置文件。
  2. 完全退出 OpenCode CLI 或桌面端。
  3. 重新打开 OpenCode。
  4. 再检查模型列表。
只关闭项目窗口但没有退出程序，配置可能不会重新加载。

遇到错误时怎么求助

不要只说“安装不了”。请提供以下信息：
  1. 你的操作系统，例如 Windows 11、macOS 15 或 Ubuntu 24.04。
  2. 正在执行教程的哪一步。
  3. 输入的命令，API Key 必须用 *** 遮住。
  4. 完整错误文字或截图。
  5. node -v、npm -v 和 opencode --version 的输出。
在 PowerShell 或终端中，可以用鼠标选中错误文字后复制。发送截图前，先检查画面中是否包含 API Key、用户名或其他隐私信息。

安装相关名词

名词简单说明
Node.js运行 OpenCode CLI 所需的基础环境
npm随 Node.js 安装的软件包管理工具，用来安装 OpenCode
NVM管理多个 Node.js 版本的工具，官网安装包失败时再使用
CLI在 PowerShell 或终端中运行的命令行版本
桌面端可以点击操作的图形界面版本
JSONOpenCode 配置文件使用的文本格式
API Key连接 TokenFlash 服务的账户密钥
Base URLOpenCode 请求模型时使用的接口地址
PATH系统查找 node、npm、opencode 命令的位置列表
完成这些基础操作后，按照你的目标继续阅读 WorkBuddy 日常任务入门、OpenCode 代码任务安装与配置 或 Codex 订阅与项目协作。