Back to Details

installing-tribal

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Installing Tribal

安装Tribal

Configuring Tribal

配置Tribal

This skill walks through the four steps that configure Tribal: install the binary, run 
tribal bootstrap
, run 
tribal check
, and wire the MCP config into your harness. An optional fifth step extends the check suite with provider readiness probes before the user's first ingest. Follow the steps in order.
If 
using-tribal
should activate after configuration is complete, this skill hands off at the end.
本技能将引导完成配置Tribal的四个步骤：安装二进制文件、运行
tribal bootstrap
、运行
tribal check
，以及将MCP配置接入你的harness。可选的第五步会在用户首次导入前，通过提供商就绪探测扩展检查套件。请按顺序执行步骤。
如果配置完成后应激活
using-tribal
技能，本技能会在最后移交控制权。

Before you start

开始之前

IMPORTANT: Load 
references/consent.md
 before doing anything else. It is the ask-first protocol for credential-bearing files. This skill touches several of those during wire-up, and skipping the protocol risks reading or writing user secrets without consent.
Also load 
references/platforms.md
. It carries the detection one-liner (
uname -sm
) and the single source for what varies across macOS Intel, macOS Apple Silicon, and Linux. The steps below assume the active platform is known.
重要提示： 在进行任何操作前，请先查看
references/consent.md
。这是针对含凭证文件的“先询问”协议。本技能在连接过程中会接触多个此类文件，跳过该协议可能会在未经许可的情况下读取或写入用户的机密信息。
同时查看
references/platforms.md
。其中包含检测单行命令(
uname -sm
)，以及macOS Intel、macOS Apple Silicon和Linux平台之间差异的唯一来源。以下步骤假设已确定当前使用的平台。

Step 1: Install the binary

步骤1：安装二进制文件

Three install paths, below. Which one fits is the user's call, because the consequences land on them: the binary (Homebrew on macOS, the shell installer on Linux) is the lightest to run, upgrade, and remove, but needs a Postgres they supply; Docker Compose bundles its own Postgres but leaves a long-running container, HTTP transport, and secrets in a 
.env
to manage. The binary is the simpler default for most, but it is a trade-off to put to the user, not a choice to make for them, so confirm the path before installing.
以下提供三种安装路径，选择哪种由用户决定，因为后果由他们承担：二进制文件（macOS使用Homebrew，Linux使用shell安装程序）运行、升级和卸载最轻便，但需要用户自行提供Postgres；Docker Compose会捆绑自身的Postgres，但需要管理长期运行的容器、HTTP传输和
.env
中的机密。二进制文件对大多数用户来说是更简单的默认选择，但这是需要交给用户权衡的选择，而非替他们决定，因此在安装前请确认路径。

Homebrew (macOS)

Homebrew（macOS）

bash
brew install tribal-memory/homebrew-tap/tribal
Installs a 
tribal
binary on PATH. Homebrew resolves the architecture. The harness can spawn the binary per session, or run it as a long-running server (Step 2).
bash
brew install tribal-memory/homebrew-tap/tribal
会在PATH中安装
tribal
二进制文件。Homebrew会自动适配架构。harness可以在每个会话中启动该二进制文件，也可以将其作为长期运行的服务器运行（步骤2）。

Shell installer (macOS and Linux)

Shell安装程序（macOS和Linux）

bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/tribal-memory/tribal/releases/latest/download/tribal-installer.sh | sh
Targets macOS and Linux. Same end state as Homebrew: a single binary on PATH.
bash
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/tribal-memory/tribal/releases/latest/download/tribal-installer.sh | sh
适用于macOS和Linux。最终状态与Homebrew安装相同：PATH中存在单个二进制文件。

Docker Compose (containerised)

Docker Compose（容器化）

Runs Tribal as a long-running server in a container, alongside a bundled Postgres. The harness wires to the container over the network. Requires HTTP transport (Step 2 explains why).
The only file the user needs is 
docker-compose.yml
; the entrypoint is baked into the published image. The image tag is pinned inside that file, so the compose file and the image must come from the same release. Take the compose file from the latest release, into a fresh directory.
IMPORTANT: reusing an existing local checkout is a trap. A stale checkout pins an old image tag in its compose file, so 
docker compose up
silently runs that old version; that is why the steps fetch into a fresh directory. If a checkout is reused, bringing it to the latest release tag first (
git fetch --tags
, then check out that tag) avoids the stale pin.
One way to fetch the release compose into a clean directory:
bash
tag=$(curl -fsSL https://api.github.com/repos/tribal-memory/tribal/releases/latest | jq -r .tag_name)
mkdir tribal-docker && cd tribal-docker
curl -fsSL "https://raw.githubusercontent.com/tribal-memory/tribal/$tag/docker-compose.yml" -o docker-compose.yml
curl -fsSL "https://raw.githubusercontent.com/tribal-memory/tribal/$tag/.env.example" -o .env.example
在容器中运行Tribal作为长期运行的服务器，并附带捆绑的Postgres。harness通过网络连接到容器。需要HTTP传输（步骤2会解释原因）。
用户仅需要
docker-compose.yml
文件；入口点已内置在发布的镜像中。镜像标签固定在该文件内，因此compose文件和镜像必须来自同一版本。请从最新版本中获取compose文件，并放入新目录中。
重要提示： 重用现有本地检出版本是一个陷阱。过时的检出版本会在其compose文件中固定旧的镜像标签，因此
docker compose up
会静默运行旧版本；这就是为什么步骤要求将文件下载到新目录的原因。如果要重用检出版本，请先将其更新到最新版本标签（
git fetch --tags
，然后检出该标签），以避免过时的固定标签。
将版本compose文件下载到干净目录的一种方法：
bash
tag=$(curl -fsSL https://api.github.com/repos/tribal-memory/tribal/releases/latest | jq -r .tag_name)
mkdir tribal-docker && cd tribal-docker
curl -fsSL "https://raw.githubusercontent.com/tribal-memory/tribal/$tag/docker-compose.yml" -o docker-compose.yml
curl -fsSL "https://raw.githubusercontent.com/tribal-memory/tribal/$tag/.env.example" -o .env.example

Cloud provider? Create .env from .env.example and set its key first (see below).

使用云提供商？从.env.example创建.env并先设置其密钥（见下文）。

docker compose up

`docker compose` reads `.env`, not `.env.example`, so copy the template to `.env` and edit that one. With no `.env` (or its defaults), the stack runs on a local Ollama.

**IMPORTANT:** for a cloud provider, set the provider, model, and key in `.env` before that first `docker compose up`. Tribal validates provider config at startup, so a cloud provider without its key fails to boot the container, not just the first ingest.

The example's model values are placeholders, and not every current model works: some are reasoning models Tribal cannot yet drive. Confirm the model against [`references/providers.md`](references/providers.md) rather than uncommenting the example blind.
docker compose up

`docker compose`读取的是`.env`而非`.env.example`，因此请将模板复制到`.env`并编辑该文件。如果没有`.env`（或使用其默认值），堆栈将在本地Ollama上运行。

**重要提示：** 对于云提供商，请在首次运行`docker compose up`前，在`.env`中设置提供商、模型和密钥。Tribal会在启动时验证提供商配置，因此没有密钥的云提供商将无法启动容器，而不仅仅是首次导入失败。

示例中的模型值是占位符，并非所有当前模型都可用：有些是Tribal目前无法驱动的推理模型。请对照[`references/providers.md`](references/providers.md)确认模型，而非盲目取消注释示例。

Verify the install

验证安装

For the direct install paths (Homebrew, shell installer), success is a version string from a fresh shell:
bash
tribal --version
If the command is not found, the installer wrote a PATH update to the shell's rc file that the current session has not re-read. Resolution depends on the active shell; see 
references/platforms.md
.
For the Docker Compose path, success is the 
tribal
service reporting 
Up
:
bash
docker compose ps
The binary lives inside the container; the host does not need it on PATH.
If the 
tribal
service is not 
Up
while Postgres reports healthy, a likely cause is host port 8725 already in use by a previous Tribal stack or another process. Identify what holds it before retrying: a stale Tribal stack can be torn down with the user's agreement; anything else, flag rather than stop. Mapping a free host port is also an option, remembering that the port mapping and 
TRIBAL_PUBLIC_MCP_URL
move together.
对于直接安装路径（Homebrew、shell安装程序），成功的标志是在新shell中能获取版本字符串：
bash
tribal --version
如果命令未找到，说明安装程序已将PATH更新写入shell的rc文件，但当前会话尚未重新读取。解决方法取决于当前使用的shell，请查看
references/platforms.md
。
对于Docker Compose路径，成功的标志是
tribal
服务显示为
Up
：
bash
docker compose ps
二进制文件位于容器内部；主机不需要将其添加到PATH中。
如果
tribal
服务未显示为
Up
，但Postgres报告健康，可能的原因是主机端口8725已被之前的Tribal堆栈或其他进程占用。在重试前请确定占用端口的进程：经用户同意后可以关闭过时的Tribal堆栈；其他进程则需标记而非停止。也可以映射一个空闲的主机端口，记住端口映射和
TRIBAL_PUBLIC_MCP_URL
需要同步修改。

Step 2: Run 
tribal bootstrap

步骤2：运行
tribal bootstrap

tribal bootstrap
composes setup, project registration, credential persistence, and MCP config emission into one run. Invoke it from inside the git repository the user wants Tribal to know about; bootstrap registers that repository as the project.
bash
tribal bootstrap
The stderr output enumerates the next steps with concrete commands appropriate to the chosen transport, the install state, and whether credentials were written successfully. Treat it as the canonical run-book. The rest of this skill is the meta-frame around that output: what to configure before running bootstrap, what the trade-offs mean, and what to do when the output cannot anticipate the user's environment.
For scripted consumers, 
--json
emits the same data as a structured object on stdout (no next-steps prose). The shape is documented in 
references/bootstrap-output.md
.
bash
tribal bootstrap --json
tribal bootstrap
将设置、项目注册、凭证持久化和MCP配置生成整合为一次运行。请在用户希望Tribal关联的git仓库内部调用它；bootstrap会将该仓库注册为项目。
bash
tribal bootstrap
stderr输出会列出后续步骤，并提供适合所选传输方式、安装状态以及凭证是否写入成功的具体命令。请将其视为权威操作手册。本技能的其余部分是围绕该输出的元框架：运行bootstrap前需要配置什么、权衡意味着什么，以及当输出无法预测用户环境时该怎么做。
对于脚本化使用者，
--json
参数会在stdout中以结构化对象形式输出相同数据（无后续步骤说明文字）。数据结构记录在
references/bootstrap-output.md
中。
bash
tribal bootstrap --json

The database URL

数据库URL

Bootstrap needs a Postgres database with the 
pgvector
extension. The connection URL has three resolution channels, in order of precedence: the 
--database-url
flag, the 
TRIBAL_DATABASE__URL
environment variable, and the 
database.url
field in the resolved config file.
A local Postgres URL looks like 
postgresql://user:pass@localhost:5432/tribal
. The Docker Compose path provides a local Postgres out of the box.
Managed Postgres providers (Neon, Supabase, AWS RDS, and similar) usually require an 
sslmode=require
parameter and may need provider-specific additions. The Neon shape, for instance, is 
postgresql://<user>:<password>@<host>.neon.tech/<database>?sslmode=require
. The provider's dashboard or documentation is the canonical source for the exact URL.
Bootstrap需要一个带有
pgvector
扩展的Postgres数据库。连接URL有三种解析渠道，优先级从高到低：
--database-url
标志、
TRIBAL_DATABASE__URL
环境变量，以及解析后配置文件中的
database.url
字段。
本地Postgres URL格式类似
postgresql://user:pass@localhost:5432/tribal
。Docker Compose路径会默认提供本地Postgres。
托管Postgres提供商（Neon、Supabase、AWS RDS等）通常需要
sslmode=require
参数，可能还需要提供商特定的附加参数。例如Neon的格式为
postgresql://<user>:<password>@<host>.neon.tech/<database>?sslmode=require
。确切的URL请以提供商的控制台或文档为准。

Transport choice

传输方式选择

The 
--transport
flag picks the connection shape between the harness and the Tribal MCP server. Three values: 
stdio
, 
http
, 
sse
. The choice has lifecycle consequences.
  • Stdio is the default for direct binary installs. The harness spawns 
    tribal
    as a subprocess per session and tears it down at session end. No long-lived process to manage.
  • HTTP is required for the Docker Compose path (the harness on the host cannot reach into a container's stdio). It is also a valid choice for direct binary installs that want a persistent server reachable from multiple sessions.
  • SSE behaves like HTTP for wire-up. Less commonly used.
bash
tribal bootstrap --transport http
--transport
标志用于选择harness与Tribal MCP服务器之间的连接类型。有三个可选值：
stdio
、
http
、
sse
。该选择会影响生命周期管理。
  • Stdio是直接二进制安装的默认选项。harness会在每个会话中启动
    tribal
    作为子进程，并在会话结束时终止它。无需管理长期运行的进程。
  • HTTP是Docker Compose路径的必需选项（主机上的harness无法访问容器的stdio）。对于希望从多个会话访问持久服务器的直接二进制安装，这也是一个有效的选择。
  • SSE在连接配置上与HTTP类似。使用频率较低。
bash
tribal bootstrap --transport http

HTTP and SSE: the server lifecycle is the user's

HTTP和SSE：服务器生命周期由用户管理

For HTTP or SSE transports, the wire-up assumes a 
tribal serve
process is running and bound to the registered project ID. Bootstrap's stderr output gives the exact 
tribal serve
invocation to run; it does not start the server itself.
How that process runs is for the user to decide. Options include a separate terminal window, a terminal pane (tmux, screen), a backgrounded subprocess, or a service manager (launchd, systemd). The user picks based on their environment.
For the Docker Compose path, the container already runs 
tribal serve
as its entrypoint. Nothing additional to manage.
对于HTTP或SSE传输方式，连接配置假设
tribal serve
进程正在运行并绑定到已注册的项目ID。Bootstrap的stderr输出会给出确切的
tribal serve
调用命令；它不会自行启动服务器。
该进程的运行方式由用户决定。选项包括单独的终端窗口、终端面板（tmux、screen）、后台子进程或服务管理器（launchd、systemd）。用户会根据自身环境选择合适的方式。
对于Docker Compose路径，容器已将
tribal serve
作为其入口点运行。无需额外管理。

Choosing providers and models

选择提供商和模型

By default Tribal uses a local Ollama. To use a cloud provider, or a non-default local model, set the provider and model for the embedding stage and for each inference stage. 
tribal bootstrap
accepts these as flags (
--embedding-provider
, 
--embedding-model
, and 
--inference-<stage>-provider
/ 
--inference-<stage>-model
); they can equally be set by environment variable or in the config file. The full set of channels, the per-install-path specifics (the Docker Compose path configures providers through 
.env
, not the config file), and current model IDs live in 
references/providers.md
.
默认情况下，Tribal使用本地Ollama。要使用云提供商或非默认本地模型，请为嵌入阶段和每个推理阶段设置提供商和模型。
tribal bootstrap
接受这些参数作为标志（
--embedding-provider
、
--embedding-model
以及
--inference-<stage>-provider
/
--inference-<stage>-model
）；也可以通过环境变量或配置文件设置。完整的配置渠道、各安装路径的具体要求（Docker Compose路径通过
.env
而非配置文件配置提供商）以及当前模型ID记录在
references/providers.md
中。

Re-running bootstrap

重新运行bootstrap

Re-running 
tribal bootstrap
against the same git repository is safe. It reuses the existing project, mints a fresh bearer token, and re-emits the MCP config. Useful when the user wants new credentials, a different transport, or a clean MCP config snippet.
针对同一git仓库重新运行
tribal bootstrap
是安全的。它会重用现有项目，生成新的Bearer令牌，并重新生成MCP配置。当用户需要新凭证、不同传输方式或干净的MCP配置片段时非常有用。

Step 3: Run 
tribal check

步骤3：运行
tribal check

Bootstrap's stderr output directs the user to run 
tribal check
. The check command is the canonical diagnostic: it surfaces every configurable failure with a 
remediation
field that names the next action.
bash
tribal check
For programmatic consumption, use 
--json
. The shape and the walkthrough pattern (act on programmatic remediations, hand off on sensitive ones) live in 
references/tribal-check-remediation.md
.
bash
tribal check --json
Bootstrap的stderr输出会引导用户运行
tribal check
。该检查命令是权威诊断工具：它会显示所有可配置的故障，并附带
remediation
字段说明下一步操作。
bash
tribal check
对于程序化使用，请使用
--json
参数。数据结构和处理模式（执行程序化修复，移交敏感修复操作）记录在
references/tribal-check-remediation.md
中。
bash
tribal check --json

On the Docker Compose path

Docker Compose路径下的操作

Run 
tribal check
inside the container, and thread in the project id so the project-resolution check has context:
bash
docker compose exec tribal sh -c 'TRIBAL_PROJECT_ID=$(cat /var/lib/tribal/tribal/project_id) tribal check'
Without the project id, the check reports a 
project_resolution
warning even when the install is healthy.
在容器内运行
tribal check
，并传入项目ID，以便项目解析检查有上下文：
bash
docker compose exec tribal sh -c 'TRIBAL_PROJECT_ID=$(cat /var/lib/tribal/tribal/project_id) tribal check'
如果没有项目ID，即使安装正常，检查也会报告
project_resolution
警告。

When 
tribal check
reports 
ok: true
but something is still wrong

当
tribal check
报告
ok: true
但仍存在问题时

tribal check
covers the configurable surface. Network-level issues (VPN blocking the database path, firewall rules, DNS flakes) can mean Tribal reports healthy while the user cannot do real work. 
references/failure-modes.md
 covers this disambiguation.
tribal check
覆盖了可配置的层面。网络级问题（VPN阻止数据库路径、防火墙规则、DNS故障）可能导致Tribal报告健康，但用户无法实际使用。
references/failure-modes.md
涵盖了这种情况的区分方法。

Step 4: Wire Tribal into your harness's MCP config

步骤4：将Tribal接入harness的MCP配置

Bootstrap's stderr output gives the wire-up command directly for Claude Code (
claude mcp add-json tribal "$(tribal mcp-config)"
). For other harnesses, the same canonical 
tribal mcp-config
output is the source of truth; the translation to each harness's native shape lives in 
references/harnesses/
.
bash
tribal mcp-config
The command always emits JSON to stdout (no 
--json
flag); warnings, if any, go to stderr. The shape (transport discriminator, stdio vs HTTP fields, where the bearer token lives) is documented in 
references/bootstrap-output.md
. The agent should run the command and inspect the live output rather than relying on a memorised shape.
On the Docker Compose path, thread the project id in, the same as 
tribal check
; without it, 
tribal mcp-config
returns empty:
bash
docker compose exec -T tribal sh -c 'TRIBAL_PROJECT_ID=$(cat /var/lib/tribal/tribal/project_id) tribal mcp-config'
When you only need to confirm the shape rather than wire it, note that the output carries the bearer token in its 
Authorization
header; see 
references/consent.md
 for inspecting it without printing the value to the transcript.
IMPORTANT: the newly-wired server does not appear in the current session until the harness loads it; the Tribal MCP tools will be missing until then. Most harnesses need a session restart; some can reload in-session (Claude Code, via 
/reload-plugins
). The per-harness reference notes which applies; tell the user as part of the handoff.
Bootstrap的stderr输出直接给出了针对Claude Code的接入命令(
claude mcp add-json tribal "$(tribal mcp-config)"
)。对于其他harness，相同的权威
tribal mcp-config
输出是唯一的参考来源；转换为各harness原生格式的方法记录在
references/harnesses/
中。
bash
tribal mcp-config
该命令始终会在stdout中输出JSON（无需
--json
标志）；如有警告，会输出到stderr。数据结构（传输区分符、stdio与HTTP字段、Bearer令牌的位置）记录在
references/bootstrap-output.md
中。代理应运行该命令并检查实时输出，而非依赖记忆中的结构。
在Docker Compose路径下，需传入项目ID，与
tribal check
相同；如果没有项目ID，
tribal mcp-config
会返回空值：
bash
docker compose exec -T tribal sh -c 'TRIBAL_PROJECT_ID=$(cat /var/lib/tribal/tribal/project_id) tribal mcp-config'
当仅需要确认结构而非接入时，请注意输出的
Authorization
头中包含Bearer令牌；查看
references/consent.md
了解如何在不将值打印到记录中的情况下检查它。
重要提示： 新接入的服务器在harness加载前不会出现在当前会话中；在此之前，Tribal MCP工具将不可用。大多数harness需要重启会话；有些可以在会话中重新加载（Claude Code通过
/reload-plugins
）。各harness的参考文档会说明适用哪种方式；请在移交控制权时告知用户。

Per-harness translations

各harness的转换方法

The container around the MCP entry varies per harness: the primary configuration file, its format, the key name, and the wrapper field shape all differ. The translation from Tribal's canonical shape to a given harness's native shape lives in 
references/harnesses/
. Each file there names the harness, its primary config-file path, the field shape it expects, a 
jq
snippet that produces that shape from 
tribal mcp-config
, and how to verify the harness has loaded the server.
To wire Tribal into a specific harness, read the corresponding file under that directory.
MCP入口的容器因harness而异：主配置文件、格式、键名和包装字段结构都不同。从Tribal的权威结构转换为特定harness原生结构的方法记录在
references/harnesses/
中。该目录下的每个文件都说明了对应的harness、主配置文件路径、预期的字段结构、从
tribal mcp-config
生成该结构的
jq
代码片段，以及如何验证harness已加载服务器。
要将Tribal接入特定harness，请读取该目录下对应的文件。

When there is no reference file for the user's harness

当用户的harness没有参考文件时

The files in 
references/harnesses/
 cover the named target harnesses. For any harness without a dedicated file, the canonical 
tribal mcp-config
output is still the source of truth. Read the harness's own MCP configuration documentation, identify the field shape it expects, and produce the translation with the user. If the wire-up works and the user is willing to contribute it back, the path is a pull request against 
tribal-memory/skills
.
references/harnesses/
中的文件涵盖了指定的目标harness。对于没有专用文件的harness，权威的
tribal mcp-config
输出仍然是唯一的参考来源。请阅读harness自身的MCP配置文档，确定它预期的字段结构，并与用户一起完成转换。如果接入成功且用户愿意贡献，可通过向
tribal-memory/skills
提交拉取请求的方式添加。

Scope: project by default

范围：默认按项目

Most harnesses support per-project and per-user scope for MCP server entries. The recommended default is project scope: a config file at the repository root rather than in the user's home directory. This keeps each repository's Tribal project ID bound to its own MCP entry, so switching repositories switches Tribal projects automatically. User scope is a valid choice when the user wants Tribal available in repositories that have not been bootstrapped, or when they prefer a single global configuration. The per-harness reference files name the scope flags or file paths.
IMPORTANT (HTTP and SSE transports): the MCP entry for HTTP or SSE carries the bearer token in an 
Authorization
header. Wiring that entry at project scope places the token in the harness's project-scoped config file, which is commonly tracked in version control. For HTTP or SSE, prefer a scope the harness keeps out of version control (user scope, or a local uncommitted file). Stdio entries carry no token and are unaffected.
大多数harness支持MCP服务器条目的按项目和按用户范围。推荐的默认选项是按项目范围：配置文件位于仓库根目录而非用户主目录。这样可以将每个仓库的Tribal项目ID绑定到其自身的MCP条目，切换仓库时会自动切换Tribal项目。当用户希望在未bootstrap的仓库中使用Tribal，或偏好单一全局配置时，按用户范围是有效的选择。各harness的参考文件会说明范围标志或文件路径。
重要提示（HTTP和SSE传输方式）： HTTP或SSE的MCP条目在
Authorization
头中携带Bearer令牌。按项目范围接入会将令牌放在harness的项目范围配置文件中，该文件通常会被纳入版本控制。对于HTTP或SSE，偏好使用harness不纳入版本控制的范围（按用户范围或本地未提交的文件）。Stdio条目不携带令牌，不受影响。

Consent before writing

写入前需获得同意

Wiring up the harness usually means editing the harness's primary configuration file (typically a JSON or TOML at a path under 
~/.<harness>/
). Those files are covered by the consent protocol; the agent must ask the user before reading or writing them. See 
references/consent.md
.
Where the harness exposes a CLI for adding MCP servers (a 
<harness> mcp add
style command), prefer it. The CLI is the authorisation surface: it edits the config file as part of the user's authorised invocation, with no separate consent step needed. Direct file edits do require consent.
接入harness通常意味着编辑harness的主配置文件（通常是
~/.<harness>/
路径下的JSON或TOML文件）。这些文件受同意协议约束；代理在读取或写入前必须询问用户。请查看
references/consent.md
。
如果harness提供了添加MCP服务器的CLI（如
<harness> mcp add
类命令），请优先使用。CLI是授权层面：它会作为用户授权调用的一部分编辑配置文件，无需单独的同意步骤。直接编辑文件则需要获得同意。

Step 5: (Optional) Verify provider readiness

步骤5：（可选）验证提供商就绪状态

tribal check --providers
extends the diagnostic suite with fatal probes against the embedding and inference providers. Running it is the gate for the user's first real ingest: bootstrap and the standard 
tribal check
complete without touching providers, so a healthy install can still fail to do real work until the providers are configured. An ingest attempted before this probe passes fails on the provider itself, which the standard check never contacted, so the natural order is to clear 
--providers
before the first ingest.
bash
tribal check --providers
Bootstrap's stderr output prompts this step as part of the numbered next steps. Run it once the user has configured their provider (a local Ollama with the required models pulled, or API keys for a cloud provider set in the environment).
The remediation pattern is the same as for the core check suite: programmatic remediations the agent performs autonomously, sensitive ones (API keys, environment variables) relayed to the user. See 
references/tribal-check-remediation.md
.
tribal check --providers
会扩展诊断套件，对嵌入和推理提供商进行致命探测。运行该命令是用户首次实际导入的前置条件：bootstrap和标准
tribal check
完成时不会接触提供商，因此即使安装正常，在提供商配置完成前仍可能无法实际工作。在该探测通过前尝试导入会因提供商本身失败，而标准检查从未联系过提供商，因此自然的顺序是在首次导入前通过
--providers
检查。
bash
tribal check --providers
Bootstrap的stderr输出会将此步骤作为编号后续步骤的一部分提示。在用户配置好提供商（已拉取所需模型的本地Ollama，或已在环境中设置云提供商的API密钥）后运行该命令。
修复模式与核心检查套件相同：代理可自主执行程序化修复，敏感修复操作（API密钥、环境变量）则转交给用户。请查看
references/tribal-check-remediation.md
。

Getting API keys to Tribal

将API密钥传递给Tribal

If the user has configured a cloud provider, the API key must reach the 
tribal
process. The channels, and which applies to each install path, are in 
references/providers.md
: a directly-installed binary reads it from the config file, a stage-specific 
TRIBAL_..._API_KEY
, or the standard 
OPENAI_API_KEY
/ 
ANTHROPIC_API_KEY
; the Docker Compose path takes it from 
.env
, since the config file inside the container does not drive provider routing. Writing a config or environment file is sensitive; the consent protocol in 
references/consent.md
 applies.
For a one-time check without persistence, prepend the key: 
OPENAI_API_KEY=<key> tribal check --providers
.
When the key is supplied through the environment rather than a file Tribal reads on every invocation, the process that consumes it must be (re)started after the value is set: a harness-spawned stdio server needs the harness relaunched; an HTTP server or the Docker stack needs that process restarted. The agent cannot reload another process's environment for itself. The signal that a restart is needed is 
tribal check --providers
failing on a provider auth check, not a direct inspection of the environment.
如果用户配置了云提供商，API密钥必须传递给
tribal
进程。配置渠道以及各安装路径适用的渠道记录在
references/providers.md
中：直接安装的二进制文件从配置文件、阶段特定的
TRIBAL_..._API_KEY
或标准的
OPENAI_API_KEY
/
ANTHROPIC_API_KEY
读取；Docker Compose路径从
.env
读取，因为容器内的配置文件不驱动提供商路由。写入配置或环境文件属于敏感操作；适用
references/consent.md
中的同意协议。
对于无需持久化的一次性检查，可以在命令前添加密钥：
OPENAI_API_KEY=<key> tribal check --providers
。
当密钥通过环境而非Tribal每次调用读取的文件提供时，消费该密钥的进程必须在设置值后（重新）启动：harness启动的stdio服务器需要重启harness；HTTP服务器或Docker堆栈需要重启该进程。代理无法自行重新加载另一个进程的环境。需要重启的信号是
tribal check --providers
在提供商认证检查中失败，而非直接检查环境。

What can go wrong here

可能出现的问题

Install-time failures fall into a small set of patterns, almost all of them with structured guidance built into the binary or the reference files:
  • Bootstrap itself fails. The standard error names the failure inline. Common cases: database unreachable, git remote undetectable (pass 
    --remote <url>
    ), credentials write failure (the token is shown inline for manual save).
  • tribal --version
    returns "command not found"     after install. The installer wrote to a PATH the current shell has not re-read. Covered in Step 1's verification subsection.
  • tribal check
    fails on first run.     Surface the 
    remediation
    field per the pattern in 
    references/tribal-check-remediation.md
    .
  • Runtime or network-level issues (worker death, transport errors, VPN blocking the database, prompt I/O). 
    references/failure-modes.md
     covers the patterns.
When in doubt: bootstrap's standard error is the first source of truth; 
tribal check
is the next; the failure-modes reference handles the long tail.
安装时的故障分为几种常见模式，几乎所有模式都在二进制文件或参考文件中有结构化指导：
  • Bootstrap本身失败。 标准错误会内联说明故障。常见情况：数据库无法访问、git远程仓库无法检测到（传入
    --remote <url>
    ）、凭证写入失败（令牌会内联显示以便手动保存）。
  • 安装后
    tribal --version
    返回“command not found”。     安装程序已将PATH更新写入shell的rc文件，但当前会话尚未重新读取。步骤1的验证小节已涵盖此情况。
  • 首次运行
    tribal check
    失败。     按照
    references/tribal-check-remediation.md
    中的模式显示
    remediation
    字段。
  • 运行时或网络级问题（进程终止、传输错误、VPN阻止数据库、提示I/O）。
    references/failure-modes.md
    涵盖了这些模式。
如有疑问：bootstrap的标准错误是首要参考来源；
tribal check
是次要来源；故障模式参考文件处理长尾问题。

You're done

完成配置

Configuration is complete. The user's harness now has Tribal wired as an MCP server, and the providers (if configured) are verified.
Remember the reload step from Step 4: the Tribal tools appear only after the harness reloads (or restarts). Make sure the user has done this before relying on Tribal.
For day-to-day use (capturing knowledge, querying it, traversing the graph, diagnosing issues), the 
using-tribal
skill takes over. It activates whenever the user signals they want to save an insight, recall prior context, or approach a problem where Tribal might already have relevant knowledge.
配置已完成。用户的harness现在已将Tribal作为MCP服务器接入，并且（如果已配置）提供商已通过验证。
请记住步骤4中的重新加载步骤：只有在harness重新加载（或重启）后，Tribal工具才会出现。在依赖Tribal前，请确保用户已完成此操作。
对于日常使用（捕获知识、查询知识、遍历图谱、诊断问题），
using-tribal
技能会接管。当用户表示想要保存见解、回忆先前上下文，或处理Tribal可能已有相关知识的问题时，该技能会激活。

References

参考文档

The skill body is the entry point; the files below carry the depth.
  • references/consent.md
    : read first. The ask-first protocol for credential-bearing files. Applies to every file write this skill might do.
  • references/platforms.md
    : read early. Detection one-liner and what varies across macOS Intel, macOS Apple Silicon, and Linux.
  • references/bootstrap-output.md
    : read when parsing 
    tribal bootstrap --json
    or 
    tribal mcp-config
    output.
  • references/providers.md
    : read when selecting or configuring embedding or inference providers and models, including cloud-provider setup and current model IDs.
  • references/tribal-check-remediation.md
    : read when handling 
    tribal check
    failures, including from 
    --providers
    .
  • references/harnesses/
    : read when wiring Tribal into a specific harness. Each file under the directory covers one harness.
  • references/failure-modes.md
    : read when something fails outside the check suite (worker death, transport errors, VPN blocking the database, prompt I/O).
本技能主体是入口点；以下文件包含详细内容。
  • references/consent.md
    ：请首先阅读。 针对含凭证文件的“先询问”协议。适用于本技能可能执行的所有文件写入操作。
  • references/platforms.md
    ：请尽早阅读。包含检测单行命令以及macOS Intel、macOS Apple Silicon和Linux平台之间的差异。
  • references/bootstrap-output.md
    ：解析
    tribal bootstrap --json
    或
    tribal mcp-config
    输出时阅读。
  • references/providers.md
    ：选择或配置嵌入或推理提供商和模型（包括云提供商设置和当前模型ID）时阅读。
  • references/tribal-check-remediation.md
    ：处理
    tribal check
    失败（包括
    --providers
    的失败）时阅读。
  • references/harnesses/
    ：将Tribal接入特定harness时阅读。该目录下的每个文件涵盖一个harness。
  • references/failure-modes.md
    ：当检查套件之外出现故障（进程终止、传输错误、VPN阻止数据库、提示I/O）时阅读。