AI教程

opencode-rust 入门：基于 Rust 的 AI 编程代理

了解如何安装 opencode-rust、配置提供商、使用其 TUI 和运行模式、管理代理、连接 MCP 工具，以及使用后台任务排空和轮换代理等高级功能。

AI我搜编辑部2026年10月14日阅读约 10 分钟

什么是 opencode-rust？

opencode-rust 是一个使用 Rust 实现的开源 AI 编程代理。它提供终端用户界面、单次命令执行、HTTP 服务器、Web 支持，以及用于本地 AI 代理工作流的 ACP 集成。

该引擎整合了会话、工具执行、MCP、LSP、提供商路由、SQLite 存储和 TypeScript 插件桥接。它无需 Docker 或其他容器运行时即可运行。Rust 通过流式请求体、基于 SQLite 的对话历史记录、缓存的工具架构，以及带有 LRU 和 TTL 淘汰机制的按目录状态池，帮助控制资源使用量。

选择安装方式

所有受支持的安装方式都会提供 opr 命令，但该命令的行为会根据安装方式而有所不同。

使用 npm 安装

npm 支持 Linux、macOS 和 Windows，并会下载适用于当前平台的预构建二进制包。安装过程中不会编译项目。

npm install -g opencode-rust

npm 启动器是一个 Node 脚本，会将命令分派给引擎。可用的平台软件包包括 macOS ARM64 和 x64、Linux x64 和 ARM64 GNU 构建版本、Linux x64 musl，以及 Windows x64 MSVC。

使用 Homebrew 安装

在 macOS 或 Linux 上，使用以下命令安装 Homebrew formula：

brew install vakandi/tap/opencode-rust

该方式会安装 opr，但不会将 opencode 二进制文件放入 Homebrew 前缀目录，因此不会遮蔽上游 OpenCode CLI。Homebrew 会从源代码构建，因此会将 Rust 工具链作为构建依赖项安装。

从源代码构建

克隆代码仓库并运行安装程序：

git clone https://github.com/vakandi/opencode-rust.git
cd opencode-rust
./install.sh

安装程序会构建发布版二进制文件，并安装 opr 以及代理快捷命令。它会对 Rust 源文件和 Cargo manifest 文件进行指纹校验，因此项目未发生变化时不会重新构建。使用 --force 可强制重新构建。

使用 Homebrew 或源代码安装程序时，opr 本身就是引擎二进制文件。传递标志时，请使用显式子命令：

opr tui --some-flag

使用 npm 时，启动器会将标志分派给 TUI，因此 opr --some-flag 的解释方式有所不同。

准备环境

无论使用哪种安装方式，插件桥接和通过 npx 启动 MCP 服务器都要求 Node.js 18 或更高版本。

首次运行前还需要提供商密钥。例如，在 shell 中设置 Anthropic 密钥：

export ANTHROPIC_API_KEY=sk-ant-...

使用 OpenCode 配置所支持的提供商和凭据配置。请尽可能避免将密钥保存到源代码管理系统和 shell 历史记录中。

运行第一个会话

启动交互式 TUI

使用以下命令启动终端界面：

opr

TUI 是默认的交互界面。它会显示当前代理和模型，流式输出助手内容，并通过 / 弹窗提供命令补全。

运行单次提示

对于运行至完成的自动化提示，请使用 run：

opr run "check this repo for risks"

与简单的提供商调用不同，run 会驱动完整的会话提示循环。工具会执行，等待中的子代理会完成，并且后台工作会在进程退出前排空。

启动 HTTP 服务器

要通过 HTTP 服务器公开引擎，请运行：

opr serve --port 3000

该服务器使用相同的会话引擎，并支持项目的 HTTP、流式处理和代理基础设施。

使用命名代理

TUI 内置 build 和 plan 代理。build 代理是默认的完全访问开发代理，而 plan 用于只读分析和探索。在 TUI 中按 Tab 可切换代理。

源代码安装程序还会为命名代理创建快捷命令：

gilfoyle "fix this failing test"
setbon "write 5 ad hooks"
googlebot "audit my meta tags"

这些快捷命令会使用对应的 --agent 值运行一次提示。调用时未提供提示会将用法信息打印到标准错误，并以状态码 2 退出。

可以在 OpenCode 配置中，以及 oh-my-opencode 代理存储中的 ~/.omo/omo.jsonc 或 ~/.config/omo/omo.jsonc 配置其他代理。这些位置中的代理配置可以覆盖插件默认值，即使显示名称不同，代理仍会使用规范化 slug 进行匹配。

配置项目和会话

配置文件会从工作目录开始向上搜索并合并。支持的项目级文件名包括：

opencode.jsonc
opencode.json
.opencode/opencode.jsonc
.opencode/opencode.json

全局默认配置存储在 ~/.config/opencode/opencode.json 或其 JSONC 等效文件中。代理定义也可以存储在上文所述的 oh-my-opencode 位置。

会话存储在 SQLite 中，并支持创建、继续、分叉、导入和导出，以及父子关系。要查看数据库位置，请使用：

opr db path

要查看其他运行时位置，包括代理池使用的数据目录，请使用：

opr debug paths

使用 MCP 工具

opencode-rust 支持通过 stdio 和 HTTP 使用 MCP。MCP 服务器从配置中加载，在 90 秒启动时限内并行启动，并注册到代理每轮使用的同一个工具注册表中。

这意味着，MCP 服务器公开的工具可以访问模型，并作为代理执行轮次的一部分运行。启动会话前，请确保 Node.js 和所需的 MCP 服务器软件包均已可用。

该项目使用以换行符分隔的 JSON 作为 MCP stdio 传输格式。这与 LSP 的 Content-Length 帧格式不同，因此 MCP 服务器配置应针对兼容 MCP 的传输方式和定义。

确保后台工作完成

run 命令支持用于排空后台任务的超时时间：

opr run --wait-background-timeout 120 "run the requested task"

主轮次结束后，引擎会等待会话进入空闲状态，流式传输 oh-my-opencode 记录的子任务帧，并检查继续执行状态。默认超时时间为 120 秒。

排空操作会选择快速失败，而不是无限等待：缺少数据库、缺少账本、损坏的 JSON 以及过期的活动条目，都会被视为没有剩余工作。根据工作流的不同限制需求，可以使用更短或更长的超时时间。

配置轮换代理

引擎包含一个本地 HTTP 和 CONNECT 转发器，可在住宅代理候选项之间进行轮换。它大约每 120 秒选择一次最久未使用的上游代理，在使用前探测候选项，并将被拒绝的条目隔离。

默认池文件位于：

macOS：~/Library/Application Support/opencode/proxy-pool.txt
Linux：~/.local/share/opencode/proxy-pool.txt
Windows：%LOCALAPPDATA%\opencode\proxy-pool.txt

设置 OPENCODE_PATHS_ROOT 可以更改数据位置。生成的代理池路径为 $OPENCODE_PATHS_ROOT/opencode/proxy-pool.txt。

条目使用主机和端口，并可选择提供凭据和元数据：

198.51.100.10:8080
203.0.113.24:1080
198.51.100.31:3128:myuser:mypass
203.0.113.77:8000 | note:rotates hourly

请保持文件只包含裸条目。虽然一些示例中会将以 # 开头的行显示为注释，但解析器并未实现注释语法；此类行会作为格式错误的条目被忽略。失败的候选项和所有权信息会保存在同级的 proxy-quarantine.json 和 proxy-claims.json 文件中。

代理必须通过 opencode_proxy::start() 启动，而不能手动导出代理变量。客户端必须在构建提供商注册表之前接收代理配置。空的或无法读取的代理池会返回错误，而不会启动一个导致每个请求都失败的监听器。

探索命令界面

CLI 包含用于交互操作、会话、服务、配置、身份验证、代理、调试、MCP、数据传输和维护的命令：

tui      attach   run      serve    web      acp      models
session  stats    db       config   auth     agent    debug
mcp      export   import   github   pr       upgrade  uninstall
generate version

实用的 run 选项包括 --continue、--session、--fork、--agent、--format、--title、--dir、--port、--variant、--thinking 和 --wait-background-timeout。

开发与验证

如果你正在开发该仓库，可以使用以下命令运行工作区测试和检查：

cargo test --workspace
cargo build --release --bin opencode
cargo clippy --workspace --all-targets

该仓库按功能组织为多个 crate，涵盖 CLI、服务器、会话、代理、工具、提供商、MCP、插件、LSP、存储、TUI、权限、路径、代理转发及相关实用工具。每个 crate 的文档位于 docs/ 目录中。

结语

opencode-rust 提供了一个基于 Rust 的 OpenCode 引擎，具备交互式 TUI、完整的会话执行、可配置代理、MCP 和插件集成、SQLite 存储以及 HTTP 访问功能。你可以从 npm、Homebrew 或源码构建开始，配置提供商密钥，然后根据工作流使用 opr、opr run 或 opr serve。

该项目基于 MIT 许可证发布，与 OpenCode 团队无关联。