跳到主要内容
AI教程

如何为本地优先的 AI 编程代理设置 Shim

了解如何安装 Shim、连接本地或托管的 AI 模型、运行编程代理任务、管理会话、加载 Agent Skills、配置 MCP 服务器并应用安全的权限设置。本教程涵盖对话式控制和完整的命令行界面，同时介绍 Shim 的本地优先设计与安全边界。

AI我搜编辑部阅读约 12 分钟
如何为本地优先的 AI 编程代理设置 Shim

什么是 Shim？

Shim 是一款面向终端用户的小型、本地优先 AI 代理工具。它提供了一个通用接口，用于连接受支持的模型 API、Agent Skills 和 Model Context Protocol 服务器，无需桌面应用、后台守护进程、数据库、Docker、Node.js 或 Python。

Shim 以静态二进制文件形式分发，使用普通 JSON 进行配置，并使用仅追加的 JSONL 文件保存会话。API 密钥从环境变量读取，而不会写入 Shim 的配置。

Shim 是代理工具，而不是推理引擎。本地模型权重必须通过 Ollama、LM Studio、llama.cpp 或其他兼容服务等推理服务器运行。托管模型必须通过受支持的 HTTP API 提供。

主要功能

  • 对话式与显式控制：使用自然语言输入管理请求，或使用完整的可脚本化 CLI。
  • 本地命令路由：可选的本地小型模型能够将管理请求转换为允许使用的 Shim 命令。
  • 多个模型提供商：Shim 支持兼容 OpenAI 的 API、Anthropic Messages、本地提供商预设和自定义端点。
  • Agent Skills：Shim 会发现 SKILL.md 文件，并仅在需要时加载其中的完整指令。
  • MCP 集成：连接 stdio 或 Streamable HTTP MCP 服务器，并向代理提供其工具。
  • 权限控制：可选择只读、需要确认或自动执行。
  • 可移植状态：配置和会话使用普通 JSON 与 JSONL 文件。
  • 无遥测：网络活动仅限于明确发起的模型调用、技能下载、本地发现以及已配置的 MCP 服务器。

安装 Shim

选项 1：下载发行版

从 Shim 发行版页面下载适用于 Windows、macOS 或 Linux 的静态二进制文件。将可执行文件放入系统 PATH，然后初始化 Shim：

shim setup
shim

在 PowerShell 中直接从当前目录运行下载的可执行文件时，请使用 .\shim.exe。

选项 2：使用 Go 安装

如果已安装 Go 1.25 或更高版本，可使用以下命令安装 Shim：

go install github.com/Balanov/shim/cmd/shim@v0.1.0
shim setup

选项 3：从源代码构建

克隆代码仓库，运行测试并构建二进制文件：

git clone https://github.com/Balanov/shim.git
cd shim
go test ./...
go build -trimpath -ldflags="-s -w" -o shim ./cmd/shim
./shim setup

代码仓库还包含适用于 Windows 的 scripts/build.ps1 和适用于 Unix 系统的 scripts/build.sh。

连接模型

发现本地模型服务器

如果 Ollama、LM Studio、llama.cpp 或其他兼容的本地服务器已经在运行，可让 Shim 发现并配置可用模型：

shim model discover --add

Shim 不包含模型权重，也不会静默下载模型。运行本地模型的工作仍由模型服务器负责。

添加托管提供商

Shim 为 OpenAI、OpenRouter、Anthropic、Gemini、GitHub Models、Hugging Face 以及多个本地提供商提供预设。在添加模型之前，请先在环境中设置提供商凭据。

例如，PowerShell 用户可以这样配置 OpenRouter：

$env:OPENROUTER_API_KEY = "..."
shim model add openrouter your/model --name main --use
shim model test main

其他凭据变量包括 OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY、GITHUB_TOKEN 和 HF_TOKEN。对于持久化凭据，请使用操作系统或 Shell 的标准密钥管理机制。不要将 API 密钥放入 Shim 的项目配置中。

添加托管模型的示例包括：

shim model add openrouter anthropic/claude-sonnet-4.5 --name claude --use
shim model add openai gpt-5 --name gpt --use
shim model add huggingface org/model --name hf --use

添加自定义端点

对于任何受支持的兼容 OpenAI 的端点，请提供其基础 URL 和模型标识符：

shim model add custom my-model --name mine \
  --base-url http://127.0.0.1:8000/v1 --use

自定义提供商可以使用兼容 OpenAI 或 Anthropic 的适配器。自定义服务的凭据可选，并且可以配置。

运行第一个代理任务

执行一次性运行

检查代码仓库最安全的方式是执行只读运行：

shim run --read-only "explain this repository"

对于需要编辑文件并执行验证命令的任务，请使用 --yes 批准本次运行中的操作，并使用 --verbose 获取更多输出：

shim run --yes --verbose "fix the tests and verify the result"

仅当你信任工作区、模型和请求的任务时，才使用 --yes。

启动交互式终端

不带子命令运行 Shim，即可启动交互式会话：

shim

然后可以输入如下代理请求：

fix the failing tests in this repository

运行 shim help 可查看完整的命令列表。

使用自然语言控制 Shim

Shim 能识别用于常见英语和俄语管理操作的确定性离线短语。对于其他语言或更灵活的解释，请将模型配置为命令路由器：

shim router use ollama/qwen3:4b

路由器接收非命令式的聊天文本，并判断其代表配置请求还是普通代理任务。当它提出会修改状态的命令时，Shim 会在执行前请求确认。

如果路由过程必须保留在本机，请使用回环模型端点。路由器只负责管理命令解释；选定的主模型则使用其支持的语言处理普通对话。

添加代理技能

Shim 会在配置文件旁的全局 skills/ 目录，以及工作区目录 .shim/skills/、.agents/skills/ 和 .claude/skills/ 中发现 SKILL.md 文件。

系统提示词最初只会加入技能名称和描述。完整指令会通过 load_skill 按需加载，从而减少不必要的提示词内容。

可从仓库引用、GitHub URL 或本地路径添加技能：

shim skill add owner/repository
shim skill add https://github.com/owner/repository
shim skill add ./local/skill-or-collection

使用以下命令检查和管理已安装的技能：

shim skill list
shim skill show name
shim skill remove name

技能包含不受信任的指令。使用前请先检查，尤其是当它们要求执行 shell 命令或访问网络时。

连接 MCP 服务器

添加 Stdio 服务器

以下示例会为当前目录注册 MCP 文件系统服务器，列出其工具，并直接调用其中一个工具：

shim mcp add filesystem npx -y @modelcontextprotocol/server-filesystem .
shim mcp tools filesystem
shim mcp call filesystem list_allowed_directories '{}'

添加可流式传输的 HTTP 服务器

提供名称和 URL，即可注册远程可流式传输 HTTP 端点：

shim mcp add internal https://mcp.example.com/mcp

使用以下命令列出或移除已配置的服务器：

shim mcp list
shim mcp remove filesystem

MCP 工具会以类似 mcp_filesystem_list_allowed_directories 的名称公开。在默认权限模式下，调用 MCP 需要确认。

可以通过 Shim 的 JSON 配置添加 HTTP 标头和 stdio 环境变量。值支持 ${ENV_VAR} 展开，因此可以将密钥保留在环境变量中，而不是配置文件内。

选择权限模式

Shim 默认使用 ask 模式。读取、列出和搜索工作区文件均获允许，而文件写入、编辑、shell 命令和 MCP 调用需要确认。

使用以下命令选择全局权限策略：

shim permissions read-only
shim permissions ask
shim permissions auto
  • read-only：禁用写入、shell 命令和 MCP 调用。
  • ask：对具有重要影响的操作请求确认。
  • auto：允许代理执行操作而不弹出确认提示。

对于临时更改，建议使用 shim run --read-only 或 shim run --yes，而不是修改全局默认设置。

Shim 不是操作系统级沙箱。Shell 命令和 MCP 服务器会使用你用户账户的权限运行。对于不受信任的工作负载，请使用容器、虚拟机或操作系统沙箱。

Shim 的文件工具会拒绝从工作区进行的词法路径遍历和符号链接逃逸，但这些检查无法限制恶意进程。请将模型输出、仓库内容、技能和 MCP 响应视为不受信任的数据。

管理会话和配置

检查会话、启动全新会话，或继续之前的会话：

shim session list
shim session new
shim run --resume SESSION_ID "continue"

排查问题时，可使用诊断和配置命令：

shim status
shim doctor
shim config path
shim config show

主配置文件位于操作系统用户配置位置下的 shim/config.json。可以使用 SHIM_CONFIG 环境变量或 --config 选项覆盖该路径。会话记录以仅追加的 JSONL 文件形式存储在配置文件旁。

高级提示

  1. 以只读模式启动。 在允许编辑或执行命令前，使用 --read-only 分析仓库。
  2. 测试模型配置。 添加提供商后，运行 shim model test NAME 验证连接和凭据。
  3. 保持路由在本地。 当自然语言命令分类必须保留在你的计算机上时，将回环模型指定为路由器。
  4. 使用环境变量展开处理 MCP 密钥。 在配置中引用 ${ENV_VAR}，而不是直接存储密钥值。
  5. 优先使用单次运行权限。 对单个任务使用 --read-only 和 --yes，不要让全局策略一直处于 auto。
  6. 检查第三方指令。 检查下载的技能，并在授予 shell、文件系统或网络访问权限前考虑 MCP 服务器的行为。
  7. 先运行诊断。 shim status 和 shim doctor 等命令可以帮助在代理运行前发现配置问题。

结语

Shim 提供了一个紧凑的终端层，用于连接受支持的模型 API、代理技能和 MCP 服务器。其静态二进制文件、纯文件配置、基于环境的凭据以及明确的权限模式，适合希望使用轻量且可检查的 AI 代理工作流的用户。请从只读任务开始，验证每个提供商或工具，仅在必要时授予更广泛的权限。