Octofriend：多模型切换编码 Agent

Octo 是一个小巧、贴心、零遥测、充满头足类风格的编程助手。Octo 是你的朋友。

npm install --global octofriend

octofriend
# or, for short:
octo

Octo 是一个小巧、贴心、充满头足类风格的编程助手，支持任何兼容 OpenAI 或 Anthropic 的 LLM API。当某个模型陷入困境时，你可以随时在对话中途切换模型。Octo 还可以选择使用我们自行训练并开源的 ML 模型（1、2）——我们也推荐你使用——自动处理主力编程模型在调用工具和编辑代码时遇到的失败：这些 autofix 模型适用于任何编程 LLM。Octo 与 Kimi K2.7-Code、GLM-5.2、GPT-5.6 和 Claude 5 配合得非常好（不过，几乎任何具备 Agent 能力的编程模型都可以使用）。Octo 想要帮助你，因为 Octo 是你的朋友。

Octo 完全没有遥测。将 Octo 与注重隐私的 LLM 提供商配合使用（请容许我们私心推荐一下 Synthetic），意味着你的代码始终属于你自己。当然，你也可以将它与任何兼容 OpenAI API 的提供商、Anthropic，或者运行在自己机器上的本地 LLM 配合使用。

默认情况下，Octo 会查找 Synthetic API key，并使用 Synthetic 私有、零数据保留的搜索 API，为 Octo 的 Web 搜索工具提供支持。只要你在 Octo 的任意位置配置了 Synthetic 模型，Octo 的搜索工具就能直接使用：即使是并非托管在 Synthetic 上的模型，比如 Claude，也可以使用 Octo 的 Web 搜索工具。

如果你不想使用 Synthetic 的搜索 API，但仍然希望使用 Web 搜索工具，可以在 ~/.config/octofriend/octofriend.json5 中配置搜索选项：

{
  // ...the rest of your config,
  search: {
    url: "some_search_api_url",
    apiEnvVar: "SOME_ENV_VAR_FOR_AUTH"
  },
}

搜索工具会按照以下格式向所配置的 URL 发起 POST 请求，该格式同时兼容 Synthetic 和 Exa：

{
  query: "some search query",
}

如果你既没有配置搜索选项，也没有配置任何 Synthetic API key，Octo 的 Agent harness 会自动隐藏 Web 搜索工具，避免 Octo 尝试调用它。

Octo 内置 Docker 支持，无需特殊配置，也无需修改镜像或容器，就能连接到任意 Docker 容器。要让 Octo 在一个已经运行的现有容器中工作——例如，你已经搭建好了 Docker Compose 环境——请运行 octo docker connect your-container-name。

如果希望 Octo 启动一个 Docker 镜像，并在 Octo 退出时将其关闭，可以运行：

# Make sure to add the -- before the docker run args!
octo docker run -- ordinary-docker-run-args

例如，要在 Alpine Linux 容器中启动 Octo：

octo docker run -- -d -i -t alpine /bin/sh

Octo 的所有 shell 命令、文件系统编辑和读取操作都会在容器内部进行。不过，Octo 仍会通过宿主机使用你在配置中定义的 MCP server（因为这些 MCP server 很可能运行在你的机器上，而不是容器内）。如果 Octo 使用内置的 fetch 工具，它也会从你的机器发起 HTTP 请求。这样一来，你便可以使用任意容器，即便容器中没有安装 wget 或 curl。

Octo 会查找以下命名形式的指令文件：

Octo 会使用找到的第一个文件。因此，如果你希望 Octo 和 Claude 使用不同的指令，只需同时准备 OCTO.md 和 CLAUDE.md，Octo 就会忽略你的 CLAUDE.md。

Octo 会在当前目录以及它的每一级父目录中搜索规则，一直查找到你的主目录为止，并包含主目录本身。所有规则文件都会合并：因此，如果你既希望使用项目专属规则，又希望应用全局通用规则，可以在项目中添加一个 OCTO.md，同时在主目录中添加一个全局 OCTO.md。

如果你不想让主目录显得杂乱，也可以将全局规则文件放在 ~/.config/octofriend/OCTO.md。

Octo 支持 Agent Skills 规范，可以通过它提供可复用、依赖上下文的指令。例如，如果你想针对 Octo 进行代码审查的方式提供特殊指令，可以编写一个代码审查 Skill 文件，Octo 会在需要执行代码审查时智能加载这个 Skill。你可以在 Agent Skills 网站上找到完整的 Skill 规范，不过本质上，它们就是带有标签的 Markdown，还可以选择附带脚本。下面是一个非常简单的代码审查 Skill 示例：

---
name: "pr-review"
description: "Review Github pull requests"
---

To load a Github pull request, run the fetch tool twice:

## First fetch

First, load the URL for the PR to understand the author's intent.

Your fetch tool does not execute JavaScript. Note that parts of the Github UI
may fail without JS; for example, loading comments might say:

    UH OH!
    There was an error while loading"

This is okay and expected. Don't worry about that.

## Second fetch: load the diff

To load the diff for the PR, fetch the PR URL with a `.diff`
attached to the end. For example, to review
`https://github.com/synthetic-lab/octofriend/pull/66`, you should fetch:

`https://github.com/synthetic-lab/octofriend/pull/66.diff`

The diff is the most important part. The author may be incorrect, or have the
right idea but the wrong implementation. Focus on whether there are any bugs or
unexpected behavior.

我们会自动检测以下位置中的 Skill：

• ~/.config/agents/skills：用于存放全局 Skill 定义。
• .agents/skills：用于存放相对于 Octo 当前工作目录的 Skill。例如，如果你的公司为 Agent 制定了特殊规范，可以把它们放进公司代码仓库的 .agents/skills 目录中进行分发。

如果你还希望 Octo 从更多目录中发现 Skill，可以像下面这样，将这些目录添加到 ~/.config/octofriend/octofriend.json5 配置文件中：

skills: {
  paths: [
    // a list of directory paths containing skills
  ],
},

将 Octo 连接到 MCP server

Octo 开箱即用就能完成许多事情——只要 Bash 写得够多，几乎无所不能——但如果你希望访问 MCP server 中的丰富数据，直接把 MCP server 提供给 Octo 会方便得多，免得它费力地扭动触手，拼凑出正确的 Bash 技巧。首次运行 octofriend 后，你会得到一个位于 ~/.config/octofriend/octofriend.json5 的配置文件。要将 Octo 连接到你常用的 MCP server，请在配置文件中添加以下内容：

mcpServers: {
  serverName: {
    command: "command-string",
    args: [
      "arguments",
      "to",
      "pass",
    ],
  },
},

例如，要将 Octo 接入你的 Linear workspace：

mcpServers: {
  linear: {
    command: "npx",
    args: [ "-y", "mcp-remote", "https://mcp.linear.app/sse" ],
  },
},

将 Octo 与本地 LLM 配合使用

如果你是一位经验相对丰富的用户，可能会希望将 Octo 与本地 LLM 配合使用。假设你已经搭建好了 ollama 或 llama.cpp 之类的本地 LLM API server，那么接入 Octo 非常简单。添加模型时，请务必选择 Add a custom model...。随后，Octo 会要求你输入 API base URL，它可能类似于 http://localhost:3000，具体取决于本地 LLM server 所使用的端口。之后，它会要求你指定一个用于凭证的环境变量；随便使用一个非空环境变量即可正常工作，因为大多数本地 LLM server 本来就会忽略凭证。

你也可以直接编辑位于 ~/.config/octofriend/octofriend.json5 的 Octofriend 配置。只需将以下内容添加到模型列表中：

{
  nickname: "The string to show in the UI for your model name",
  baseUrl: "http://localhost:SOME_PORT",
  apiEnvVar: "any non-empty env var",
  model: "The model string used by the API server, e.g. openai/gpt-oss-20b",
}

默认情况下，Octo 会尽量呈现简洁清爽的 UI。如果你想查看 API 或工具调用底层的错误信息，请在运行 Octo 时，将 OCTO_VERBOSE 环境变量设置为任意真值字符串，例如：

OCTO_VERBOSE=1 octofriend

桌面通知

Octo 中有一个隐藏的 Notifications 菜单，只有配置了桌面通知后才会显示。要配置桌面通知，请在 octofriend.json5 中添加类似下面的配置块：

notifications: {
  notifyCommand: "notify-send Octo 'Finished responding!'",
},

notifications: {
  notifyCommand: 'osascript -e \'display notification "Octo finished!"\'',
},

这样会在通过 ctrl-p 打开的主菜单中启用 Notifications 子菜单。你可以将其设置为以下三种模式之一：

• Octo 下次需要输入时通知
• 本次 session 中，每当 Octo 需要输入时都通知
• 始终在 Octo 需要输入时通知

如果选择最后一个选项，该设置会持久化到你的配置文件中。

默认情况下，对于 session 级通知和持久化通知，Octo 会等待 10 秒后再通知你。如果在此期间收到输入，它就会跳过通知，以免你正在关注并与它聊天时仍不断收到通知。要修改等待时间，请设置：

notifications: {
  notifyCommand: "some command",
  notifyTimeoutMs: 20000, // Or however many milliseconds you want to wait
},

选择使用 canary 版本

如果你想使用尚未发布的 Octo 版本，请 clone 此 repo，并阅读 canary.sh 中的说明，在你的 shell 中安装 canary-octo。