恭喜 了解如何安装 Amp。本手册帮助你充分利用它。

为什么选择 Amp？

Amp 是面向终端和编辑器的前沿编程代理。

• 多模型： GPT-5.6, Claude Fable 5, 快速模型——Amp 会根据每个模型最擅长的任务使用它们。
• 有态度： 你始终在使用 Amp 最好的部分。如果我们自己不使用和喜爱某个功能，我们就会砍掉它。
• 在前沿： Amp 追随模型的发展方向前进。没有向后兼容，没有遗留功能。
• 对话： 你可以保存和分享你与 Amp 的交互。你不会在没有版本控制的情况下写代码吧？

Amp 有 4 种模式： low （面向小型、定义明确任务的快速低成本模式）、 medium （兼顾智能、速度与成本，适合大多数任务）、 high （面向难题的深度推理）、 ultra （面向困难、开放式任务的最强能力模式）。

想要更深入了解？请关注我们的 Raising an Agent 播客 ，我们会在那里分享构建 Amp 过程中的经验。

快速开始

1. 登录：ampcode.com
2. 要在本地使用 Amp CLI，或通过网页进行远程控制： 安装 Amp CLI 并运行 amp。
3. （可选）注册 Amp 月度订阅 以获得包含的 agent 与 orbs 用量。
4. （可选） 关联你的 ChatGPT 订阅 以获得更多 GPT-5.6 用量。

你已准备好使用 Amp!

安装

保持最新

Run amp update.

IDE 集成

登录 ampcode.com/install 并按照说明操作，或者：

• JetBrains（IntelliJ、WebStorm、GoLand 等）： 安装 Amp CLI，然后运行 amp --jetbrains.
• Neovim： 安装 Amp CLI 和 Amp Neovim 插件，然后运行 amp.
• VS Code 及基于 VS Code 的编辑器（Cursor、Windsurf 等）： 安装 Amp CLI，确保你的编辑器正在运行，然后运行 amp.
• Zed： 安装 Amp CLI，确保 Zed 正在运行，然后运行 amp.

通过打开命令面板（Ctrl+O）并选择 ide connect.

使用 Amp

Agent 模式

Amp 有 4 种模式：

• low：面向小型、定义明确任务的快速低成本模式。
• medium：兼顾智能、速度与成本，适合大多数任务。
• high：面向难题的深度推理。
• ultra：面向困难、开放式任务的最强能力模式。

参阅 模型 了解各模式使用的模型。

在 CLI 中通过打开命令面板（Ctrl+O）并输入 mode。

如何编写提示词

为获得最佳效果，请遵循以下准则：

• 明确表达你的需求。不要问"你能做 X 吗？"，直接说"做 X。"
• 每个任务使用一个对话线程。（这里的任务指日常意义上的「你需要完成的事」。）线程和任务 can 可以无限延续，但不应该。不要在同一个线程里既让 agent 写数据库迁移，又让它去改无关文档页的 CSS。
• 不要让模型去猜测。如果你知道如何实现你想要代理做的事情——要查看哪些文件、要运行哪些命令——写在你的提示词中。
• 如果你希望模型不写任何代码，只做调研和规划，请明确说明：「Do not edit any files.」
• 使用 AGENTS.md 文件重复此操作 来指导 Amp 如何运行测试、构建步骤以及避免常见错误。
• 告诉代理如何最好地审查自己的工作：运行什么命令或测试、打开什么 URL、查看哪些日志。反馈对代理的帮助和对我们一样大。

以下是我们在 Amp 中使用过的提示词示例：

• “Make observeThreadGuidanceFiles return Omit<ResolvedGuidanceFile, 'content'>[] and remove that field from its return value, and update the tests. Note that it is omitted because this is used in places that do not need the file contents, and this saves on data transferred over the view API.” (查看对话)
• “Run <build command> and fix all the errors”
• “Look at <local development server url> to see this UI component. Then change it so that it looks more minimal. Frequently check your work by screenshotting the URL”
• “Run git blame on the file I have open and figure out who added that new title”
• “Convert these 5 files to use Tailwind, use one subagent per file”
• “Take a look at git diff — someone helped me build a debug tool to edit a Thread directly in JSON. Please analyze the code and see how it works and how it can be improved. […]” (查看对话)
• “Check git diff --staged and remove the debug statements someone added” (查看对话)
• “Find the commit that added this using git log, look at the whole commit, then help me change this feature”
• “Explain the relationship between class AutoScroller and ViewUpdater using a diagram”
• “Run psql 并重新连接所有的 threads in the databaser to my user (email starts with thorsten)” (查看对话)

如果你在工作区中，使用 Amp 的 工作区线程共享 以互相学习。

AGENTS.md

Amp 会在 AGENTS.md 文件来指导代码库结构、构建/测试命令和约定。

Amp 包含 AGENTS.md 文件：

• AGENTS.md 当前工作目录（或编辑器工作区根目录）中的文件 和 父目录（向上到 $HOME）始终会被包含。
• 子目录 AGENTS.md 文件会在代理读取该子目录中的文件时被包含。
• 系统级指导文件，以及 $HOME/.config/amp/AGENTS.md 和 $HOME/.config/AGENTS.md如果存在，都会始终包含。

如果没有 AGENTS.md 存在于某个目录中，但名为 AGENT.md （没有 S) or CLAUDE.md 的文件确实存在，该文件将被包含。

在具有多个子项目的大型仓库中，我们建议保持顶级 AGENTS.md 通用的，并创建更具体的 AGENTS.md 文件，并在每个子项目的子目录中创建更具体的

要查看 Amp 正在使用的 agent 文件，选择 agents-md list 从命令面板中。

编写 AGENTS.md 文件

Amp 提供生成 AGENTS.md 文件（如果不存在）。你可以创建或更新任何 AGENTS.md 文件，手动或让 Amp 帮你（“Update AGENTS.md based on what I told you in this thread”).

要包含其他文件作为上下文，在 agent 文件中用 @-提及它们。例如：

See @doc/style.md and @specs/**/*.md.

When making commits, see @doc/git-commit-instructions.md.

• 相对路径相对于包含引用的 agent 文件进行解释。
• 绝对路径和 @~/some/path 也受支持。
• 代码块中的 @-提及会被忽略，以避免误判。
• Glob 模式受支持（如 @doc/*.md 或 @.agent/**/*.md).

精细化指导

要提供仅在处理某些文件时适用的指导，你可以指定 globs 在提及文件的 YAML 前言中。

例如，要应用语言特定的编码规则：

1. 将 See @docs/*.md 在你的 AGENTS.md 文件中。

2. 创建文件 docs/typescript-conventions.md 包含：

   ---
   globs:
     - '**/*.ts'
     - '**/*.tsx'
   ---
   
   Follow these TypeScript conventions:
   
   - Never use the `any` type
   - ...

3. 对其他语言重复上述步骤。

带有 globs 的被引用文件，只有当 Amp 读取了与任何 glob 匹配的文件时才会被包含（在上面的示例中，任何 TypeScript 文件）。如果没有 globs 被指定，文件在被 @-提及时始终会被包含。

Glob 模式会隐式添加 **/ 前缀，除非它们以 ../ 或 ./开头，在这种情况下它们引用的是相对于被提及文件的路径。

其他示例：

• 前端特定指导： globs: ["src/components/**", "**/*.tsx"]
• 后端指导： globs: ["server/**", "api/**"]
• 测试指导： globs: ["*.test.ts", "__tests__/*"]

引用其他对话

你可以通过对话 URL（例如 https://ampcode.com/threads/T-7f395a45-7fae-4983-8de0-d02e61d30183）或对话 ID（例如 @T-7f395a45-7fae-4983-8de0-d02e61d30183）在你的提示词中引用其他 Amp 对话。

输入 @@ 来搜索要提及的对话。

对于每个被提及的对话，Amp 会读取并提取与你当前任务相关的信息。这对于从之前的对话中继续工作或复用技术非常有用。

示例：

• Implement the plan from https://ampcode.com/threads/T-7f395a45-7fae-4983-8de0-d02e61d30183
• Apply the same fix from @T-7f395a45-7fae-4983-8de0-d02e61d30183 to the form here

查找对话

Amp 可以搜索你过去的对话和工作区成员的对话，以查找相关对话。你可以按关键词、文件路径、仓库、作者、日期或任务让 Amp 查找对话。

网页 feed 还支持可收藏或分享的 URL 过滤器。使用 /feed?time=7d 可更改活动时间窗口（24h, 72h, 7d, or all). Use /feed?q=label:bug 可按线程查询语法搜索：裸词或引号短语，以及如下过滤器 label:, file:, project:, repo:, ref:, author:, archived:, after:和 before:。例如， /feed?q=label:bug%20after:7d 显示带有以下标签的近期线程： bug label.

示例：

• Find threads where we discussed the monorepo migration
• Show me threads that modified src/server/index.ts
• Find Thorsten's threads on the indexing logic
• Show me my recent threads from the last week
• Which threads worked on task 142?
• Find threads related to this one

归档对话

当你归档一个对话时，它不再出现在你的活跃对话列表中，但仍然可以在网页上查看并 通过 @-提及来引用.

要归档对话，从命令面板中运行 thread: archive （在 CLI 中）。

附加图片

你可以将图片（如截图和图表）附加到你的消息中。

在 CLI 中，按 Ctrl+V 从剪贴板粘贴图片。注意你必须使用 Ctrl+V，而不是 Cmd+V，即使在 macOS 上也是如此。在 Windows 上，如果 Ctrl+V 不起作用，请按 Ctrl+O 并运行 paste image from clipboard 在 Amp 命令面板中执行。

在 Windows 上，图片粘贴在 WezTerm 或 Alacritty 中比在 Windows Terminal 中更可靠。

你也可以通过文件路径 @-提及图片。

提及文件

输入 @ 搜索要提及的文件。

Edit

要在 CLI 中编辑之前的消息，按 Tab 导航到之前的消息，然后按 e.

消息队列

如果 agent 仍在工作时你发送消息，该消息会进入队列，并在 agent 完成后发送。

Press Enter Enter 可更早介入：会在 agent 完成当前步骤（例如一条命令或思考块）后发送消息。

Press Esc Esc 可强制停止 agent 并立即发送你的消息，用于打断当前工作。

项目

项目将仓库与其 Amp 设置、密钥和相关线程关联起来。它可属于你个人，也可属于你的工作区。

项目是可选的：orb 线程可以在 无项目 下运行，CLI 线程会通过匹配检出仓库的 Git remote 自动加入项目。Orb 规格、密钥与环境变量、提交作者以及 setup 文件详见 Orbs 手册。

仓库

仓库可以是已有仓库——位于 GitHub 或任意 Git URL——也可以是 Amp 创建并托管的新仓库。克隆 Amp 托管的仓库请使用 amp clone owner/project-name (owner 是用户或工作区名称）。

变更工作流

该 变更工作流 设置决定线程变更侧边栏中的主要操作： Ship 会直接提交并推送到 origin/main; 推送到分支 会推送当前分支，并在 GitHub 上返回 pull request URL。

若要自动创建 pull request，请添加「使用 gh pr create创建 pull request，并在 PR 描述中嵌入截图或视频的公开产物 URL」到你的 AGENTS.md (gh 在 orbs 中已预装并完成认证）。

Orbs

Orbs 是可运行 Amp 线程的远程机器，让你的笔记本可以去做别的事或休息一下。了解如何创建与配置，请参阅 Orbs 手册。

Runners

你可以从 ampcode.com，在任何能运行 amp 的机器上远程启动 Amp 线程。

为此，你需要一个充当 runner 的 Amp 实例。

你可以通过将 amp.remoteThreadCreation.enabled 设为 true。使用命令 amp: enable remote thread creation 开启。每个 TUI 会在你启动时所在的目录中接受新线程。

运行 amp --no-tui 可启动仅 runner 模式的 Amp 实例。它会在当前目录等待并运行远程创建的线程，且不打开 TUI。传入 --runner-id <id> 可指定稳定的 runner ID，例如 amp --no-tui --runner-id grandmas-garage-server。Runner ID 必须是合法主机名，大小写不敏感，但会保留你提供的大小写。若要从 ampcode.com 访问其终端，请传入 --remote-control-terminal。

工具

Amp 代表你运行工具和 shell 命令来检查代码、运行测试并快速迭代。

默认情况下，Amp 在运行工具前不会请求批准。

Amp 会基于工作区中的内容行动。不受信任的仓库、MCP 服务器和其他外部输入都可能影响 Amp 的行为。如果你经常处理不受信任的来源，请考虑创建自定义策略插件，或使用隔离的开发环境。

内置工具

你可以通过运行以下命令查看 Amp 的内置工具 amp tools list （在 CLI 中）。

Agent 技能

技能是指令和资源的集合，教导代理如何执行特定任务。Amp 包含内置技能，你可以安装或创建自己的技能——可以是项目特定的（.agents/skills/）或用户级别的（~/.config/agents/skills/ 或 ~/.agents/skills/).

创建技能

Amp 有一个内置的 building-skills 技能，可以创建适合你的代码库、工作流和系统的技能。要创建一个，只需提问：

Create a skill for deploying to staging

要求"项目特定技能"以保存到当前项目，或"用户级技能"以跨所有项目个人使用。项目技能存放在 .agents/skills/ 中，可以提交到 git，这样你的团队就能自动获取它们。

技能优先级（先匹配的优先）：

• ~/.config/agents/skills/
• ~/.agents/skills/
• ~/.config/amp/skills/
• .agents/skills/
• .claude/skills/
• ~/.claude/skills/
• 插件、旧版 toolbox 目录，以及内置 skills

查看技能

要查看已安装的技能，请使用命令面板（Ctrl+O 在 CLI 中）：

• skill: list ——查看已安装的技能

技能格式

每个技能是一个包含 SKILL.md 文件的目录，带有 YAML 前言：

---
name: my-skill
description: A description of what this skill does
---

# My Skill Instructions

Detailed instructions for the agent...

该 name 和 description 始终对模型可见，并决定何时调用该技能。名称必须唯一——项目特定技能优先于用户级技能，两者都覆盖内置技能。 SKILL.md 内容仅在技能被调用时按需加载。

技能可以在同一目录中包含捆绑的资源（脚本、模板等），代理可以相对于技能文件来访问这些资源。

技能中的 MCP 服务器

技能可以通过包含一个 mcp.json 文件来捆绑 MCP 服务器。服务器在 Amp 启动时启动，但其工具在技能加载前保持隐藏。这是使用 MCP 服务器的推荐方式——与直接将服务器添加到 Amp 配置相比，它保持工具列表整洁并减少上下文膨胀。

示例 mcp.json （本地命令式服务器）：

{
	"chrome-devtools": {
		"command": "npx",
		"args": ["-y", "chrome-devtools-mcp@latest"],
		"includeTools": ["navigate_*", "take_screenshot", "click", "fill*"]
	}
}

示例 mcp.json （远程 HTTP 服务器）：

{
	"linear": {
		"url": "https://mcp.linear.app/sse",
		"includeTools": ["list_issues", "create_issue", "update_issue"]
	}
}

本地服务器字段：

• command (string）——要运行的命令
• args (string[]，可选）——命令参数
• env (object，可选）——环境变量

远程服务器字段：

• url (string）——服务器端点
• headers (object，可选）——随请求发送的 HTTP 头

通用字段：

• includeTools (string[]，可选但推荐）——工具名称或 glob 模式，用于过滤暴露的工具

子代理

对于适合独立执行的复杂任务，Amp 有时会派生 subagent。每个 subagent 拥有自己的上下文窗口，并可使用文件编辑和终端命令等工具。

子代理最适用于可以分解为独立部分的多步骤任务、产生大量输出但完成后不再需要的操作、在不同代码区域的并行工作，以及在协调复杂工作时保持主对话上下文的整洁。

但是，子代理是隔离工作的——它们无法相互通信，你无法在任务中途引导它们，它们从零开始而没有你对话中积累的上下文，主代理只接收它们的最终总结而不是监控它们的逐步工作。

Amp 会自动为合适任务使用 subagent，主要在 medium 模式中，偶尔也会在其他模式中。你可以通过提及 subagent 或建议并行工作来鼓励其使用。

Oracle

Amp 可以使用一个强大的“第二意见”模型，该模型更适合复杂的推理或分析任务，但代价是稍慢、稍贵，且不如主代理的模型适合日常代码编辑任务。

这个模型通过一个名为 oracle，当前使用 GPT-5.6 Sol，推理级别为 high。在 high 模式中，主 agent 使用 GPT-5.6 Sol，此时 oracle 改为 Claude Fable 5——第二意见始终来自另一款前沿模型。

主代理可以自主决定在调试或审查复杂代码时向 oracle 寻求帮助。我们有意不强制主代理 始终 使用 oracle，因为成本更高且推理速度更慢。

我们建议在你认为有帮助的时候明确要求 Amp 的主代理使用 oracle。以下是我们自己使用 Amp 的一些示例：

• “Use the oracle to review the last commit’s changes. I want to make sure that the actual logic for when an idle or requires-user-input notification sound plays has not changed.”
• “Ask the oracle whether there isn’t a better solution.”
• “I have a bug in these files: … It shows up when I run this command: … Help me fix this bug. Use the oracle as much as possible, since it’s smart.”
• “Analyze how the functions foobar 和 barfoo are used. Then I want you to work a lot with the oracle to figure out how we can refactor the duplication between them while keeping changes backwards compatible.”

参阅 GPT-5 oracle 发布公告 了解更多信息。

Librarian

Amp 可以使用 Librarian 子代理搜索远程代码库。 Librarian 可以搜索和读取 GitHub 上的所有公开代码以及你的私有 GitHub 仓库。

当你需要进行跨仓库研究时，或者例如当你想让它读取你正在使用的框架和库的代码时，告诉 Amp 召唤 Librarian。 Librarian 的回答通常更长、更详细，因为我们将其设计为提供深入的解释。 Librarian 只会搜索仓库默认分支上的代码。

你可能需要明确提示主代理使用 Librarian。以下是一些示例：

• “Explain how new versions of our documentation are deployed when we release. Search our docs and infra repositories to see how they get to X.Y.sourcegraph.com.”
• “I have a bug in this validation code using Zod, it’s throwing a weird error. Ask the Librarian to investigate why the error is happening and show me the logic causing it.”
• “Use the Librarian to investigate the foo service - were there any recent changes to the API endpoints I am using in bar? If so, what are they and when were they merged?”

参阅 Librarian 发布公告 了解更多信息。

GitHub

你需要在 你的设置 中配置与 GitHub 的连接才能使用它。 如果你想让 Librarian 能够查看你的私有仓库，你需要在配置 GitHub 连接时选择它们。 参阅 GitHub 的文档了解 安装 和 授权 GitHub 应用了解更多信息。

Painter

Amp 可通过 Painter 工具生成和编辑图像，由 GPT Image 2 驱动。

当你需要创建 UI 原型图、应用图标、主页横幅图或编辑现有图片（如遮盖截图中的敏感信息）时，告诉 Amp 使用 Painter。 你还可以在提示词中 @-提及图片文件来提供最多 3 张参考图片，用于风格指导或编辑。

你可能需要明确提示 Amp 使用 Painter。以下是一些示例：

• “Use the painter to create a UI mockup for my settings page.”
• “Use the painter to generate an app icon for my CLI tool. Dark background with a glowing terminal cursor in cyan.”
• “Use the painter to redact any visible API keys or passwords in this terminal screenshot.”

参阅 Painter 发布公告 了解更多信息。

代码审查

Amp 可以审查你的代码中的 bug、安全问题、性能问题和风格违规——运行 amp review （在 CLI 中）或直接让主代理审查你的更改。

检查项

检查项是用户定义的审查标准，适用于代码库的特定部分。它们让你将团队约定、安全不变量和 linter 无法捕获的最佳实践编码化。在代码审查期间，Amp 会为每个检查项生成一个单独的子代理。

在 .agents/checks/ 目录中创建 Markdown 文件，带有 YAML 前言：

示例 (.agents/checks/perf.md):

---
name: performance
description: Flags common performance anti-patterns
severity-default: medium
tools: [Grep, Read]
---

Look for these patterns:

- Nested loops over the same collection (O(n²) → O(n) with a Set/Map)
- Repeated `array.includes()` in a loop
- Sorting inside a loop
- String concatenation in a loop (use array + join)

Report the line, why it matters, and how to fix it.

检查项可以在项目和全局位置定义：

• .agents/checks/ ——适用于整个代码库
• api/.agents/checks/ ——仅适用于 api/
• $HOME/.config/amp/checks/ 或 $HOME/.config/agents/checks/ ——全局检查项，适用于所有审查

更近的项目检查项会覆盖来自父目录和全局的同名检查项。

MCP

你可以使用 MCP（模型上下文协议） 服务器来添加额外的工具，可以是本地的或远程的。

对于大多数用例，我们建议 在技能中捆绑 MCP 服务器 via mcp.json 而不是将它们添加到你的用户设置中。这样可以保持工具列表整洁，只在需要时加载 MCP 工具。

如果通过技能加载 MCP 不合适（如果它必须始终在上下文窗口中可用），通过 CLI 或在你的 配置文件:

$ amp mcp add context7 -- npx -y @upstash/context7-mcp
$ amp mcp add linear https://mcp.linear.app/sse

MCP 服务器使用与 技能中的 MCP 服务器—command/args/env 用于本地服务器， url/headers 用于远程。在配置文件中，设置 amp.mcpServers and use ${VAR_NAME} 语法来引用环境变量：

"amp.mcpServers": {
    "playwright": {
        "command": "npx",
        "args": ["-y", "@playwright/mcp@latest", "--headless"]
    },
    "linear": {
        "url": "https://mcp.linear.app/sse"
    },
    "sourcegraph": {
        "url": "${SRC_ENDPOINT}/.api/mcp/v1",
        "headers": { "Authorization": "token ${SRC_ACCESS_TOKEN}" }
    }
}

许多远程服务器通过 OAuth自动处理身份验证。对于需要手动认证的服务器，直接传递 headers 或使用 手动 OAuth 注册.

MCP 服务器加载顺序

当相同的 MCP 服务器名称出现在多个位置时，Amp 使用以下优先级（从高到低）：

1. CLI 标志（--mcp-config)
2. 用户/工作区配置（amp.mcpServers)
3. 技能（仅在上述未配置时加载）

这意味着你可以在需要时用自己的配置覆盖技能提供的 MCP 服务器。

工作区 MCP 服务器信任

工作区设置中的 MCP 服务器（.amp/settings.json）需要明确批准才能运行。这可以防止在你打开项目时不受信任的代码自动执行。

当工作区 MCP 服务器等待批准时，你会看到 awaiting approval 在 amp mcp doctor 输出。要批准：

$ amp mcp approve my-server

在 CLI 中，当首次检测到工作区服务器时，系统会提示你批准。

全局设置中的 MCP 服务器（~/.config/amp/settings.json）或通过 --mcp-config 传递的不需要批准。

MCP 最佳实践

可用工具过多会降低模型性能，因此为了获得最佳效果，请有选择性地使用：

• 在技能中捆绑 MCP 服务器 而不是全局添加——工具在技能加载前保持隐藏。
• 使用暴露少量高级工具且具有高质量描述的 MCP 服务器。
• 禁用你不使用的 MCP 工具，或考虑改用 CLI 工具。

远程 MCP 服务器的 OAuth

一些 MCP 服务器如 Linear 支持自动 OAuth 客户端注册。当你添加这样的服务器时，Amp 会在启动时自动在浏览器中启动 OAuth 流程。

Note: Orbs 尚不支持需要 OAuth 认证的 MCP 服务器，我们很快会加入支持。

$ amp mcp add my-server https://example.com/.api/mcp/v1

$ amp mcp oauth login my-server \
  --server-url https://example.com/.api/mcp/v1 \
  --client-id your-client-id \
  --client-secret your-client-secret \
  --scopes "openid,profile,email,user:all"

$ amp mcp oauth logout my-server

权限

Amp 在运行工具前不会请求批准。

该 Plugin API 允许你自定义此行为。

如果 Amp 在你的设置中检测到 amp.permissions, amp.guardedFiles.allowlist, or amp.dangerouslyAllowAll （设置为 false）在你的设置中时，会激活内部插件以应用 旧版权限规则.

插件

Amp 插件是用于扩展和自定义 Amp.

插件可以：

• 处理事件 — amp.on(...) 用于工具调用、工具结果和代理生命周期事件
• 添加工具 — amp.registerTool(...) 供代理调用自定义工具
• 添加命令 — amp.registerCommand(...) 用于命令面板操作
• 显示 UI — ctx.ui.notify(...), ctx.ui.confirm(...), ctx.ui.input(...)和 ctx.ui.select(...)
• 用 AI 分类 — amp.ai.ask(...) 用于线程范围内的是/否决策

当书面指导不够时使用插件。使用 AGENTS.md 承载长期指令，用 skills 提供任务级 agent 指引，用插件实现自定义工具或事件驱动行为，仅在集成 MCP 服务器时使用 MCP。

插件会执行代码，因此只使用来自你信任的人和工作区的插件。

插件位置

Amp 会从三个位置加载插件：

• 项目插件 — .amp/plugins/*.ts 在你于该项目中运行 Amp 时生效。
• 系统插件 ——在这台机器上你自己的所有项目中生效：
  • macOS： ~/.config/amp/plugins/*.ts
  • Linux： ~/.config/amp/plugins/*.ts
  • Windows： %USERPROFILE%\.config\amp\plugins\*.ts
• 全局插件 ——在 工作区设置 中配置，并应用于每个工作区成员。全局插件目前处于有限实验发布阶段； 联系我们 如果你想将其用于安全或策略执行。

编写插件

插件是一个导出默认函数的 TypeScript 文件。Amp 会向该函数传入一个 PluginAPI 对象。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.logger.log('Plugin initialized')
}

导出函数中的代码在插件加载时运行。使用 session.start 仅用于应在 Amp 启动特定线程会话时运行的工作。

更改插件后，用 Ctrl+O 并运行 plugins: reload. Run plugins: list 查看已加载插件及其注册的事件、命令和工具。

插件 UI 会在 TUI 与 Web 界面间镜像同步：

插件激活设置同时适用于交互式 amp 会话和 amp --execute 运行。

Amp 还内置了用于编写插件的技能，因此你可以直接让它为你编写插件。

事件示例

插件事件遵循对话会话的代理生命周期。系统会先为对话会话触发 session.start；随后每个用户回合开始、可能运行工具，并最终结束。

╭───────────────╮    ╭─────────────╮    ╭───────────╮    ╭─────────────╮    ╭───────────╮
│ session.start │───▶│ agent.start │───▶│ tool.call │───▶│ tool.result │───▶│ agent.end │
╰───────────────╯    ╰─────────────╯    ╰───────────╯    ╰─────────────╯    ╰───────────╯
                                              ▲                 │
                                              ╰──── per tool ───╯

session.start：线程启动时运行 Setup

session.start 会在 Amp 启动线程会话时触发，例如用户在新线程发送第一条消息，或打开/切换到已有线程时。请将插件加载初始化直接写在导出函数体中。同一 Amp CLI 进程中可同时启动并继续运行多个线程。不存在 session.end 事件。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('session.start', async (event, ctx) => {
		await ctx.ui.notify(`Example session.start for ${event.thread.id}.`)
	})
}

tool.call：批准或拒绝工具调用

tool.call 会在工具运行前触发。返回 allow 以运行工具， reject-and-continue 以阻止它并让代理继续， modify 以更改输入，或 synthesize 以在不运行工具的情况下提供结果。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('tool.call', async (event, ctx) => {
		const confirmed = await ctx.ui.confirm({
			title: `Allow ${event.tool}?`,
			message: `Amp wants to call ${event.tool}.`,
			confirmButtonText: 'Allow',
		})

		if (confirmed) {
			return { action: 'allow' }
		}

		return {
			action: 'reject-and-continue',
			message: `The user rejected ${event.tool}.`,
		}
	})
}

tool.result：观察或修改工具结果

tool.result 会在工具完成后、结果发回模型前触发。不返回内容会保留原始结果；也可以返回替换后的状态或输出。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('tool.result', async (event, ctx) => {
		if (event.status === 'error') {
			await ctx.ui.notify(`Tool failed: ${event.tool}`)
		}
	})
}

agent.start：回合开始时通知

agent.start 会在用户提交提示词时触发，适合在代理开始工作前对新回合作出响应。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('agent.start', async (_event, ctx) => {
		await ctx.ui.notify('Amp is starting a new turn.')
	})
}

agent.end：回合结束后继续

agent.end 会在代理完成一个回合时触发。返回 continue 以追加一条后续用户消息并启动另一个回合。返回时务必包含标记或其他保护条件， continue 避免插件无限循环。

import type { PluginAPI } from '@ampcode/plugin'

const marker = '[plugin:tests-requested]'

export default function (amp: PluginAPI) {
	amp.on('agent.end', (event) => {
		if (!event.message.toLowerCase().includes('verify')) {
			return
		}
		if (event.message.includes(marker)) {
			return
		}

		return {
			action: 'continue',
			userMessage: `${marker} Before finishing, run the most relevant tests for your changes.`,
		}
	})
}

命令、工具和 UI 示例

添加命令

命令会出现在 Amp 的命令面板中。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.registerCommand(
		'open-plugin-docs',
		{
			title: 'Open plugin docs',
			category: 'docs',
			description: 'Open the Amp Plugin API manual page.',
		},
		async (ctx) => {
			await ctx.system.open('https://ampcode.com/manual/plugin-api')
		},
	)
}

更改命令可用性

amp.registerCommand(...) 接受可选的 availability，并返回一个 subscription；它的 setAvailability(...) 方法会更新命令在命令面板中的显示方式：

• { type: 'enabled' } —— 显示且可选择（默认值）。
• { type: 'disabled', reason: '...' } —— 显示但不可选择；原因会随命令一起显示。
• { type: 'hidden' } —— 完全不显示。

这个插件添加了两个命令，用于切换 Amp 内置的 notifications.enabled 设置，并让命令面板只显示当前相关的那个命令。

import type { CommandSubscription, PluginAPI } from '@ampcode/plugin'

export default async function (amp: PluginAPI) {
	const isEnabled = (config: Record<string, unknown>) =>
		config['notifications.enabled'] !== false

	let mute: CommandSubscription | undefined
	let unmute: CommandSubscription | undefined

	const refresh = (enabled: boolean) => {
		mute?.setAvailability(enabled ? { type: 'enabled' } : { type: 'hidden' })
		unmute?.setAvailability(enabled ? { type: 'hidden' } : { type: 'enabled' })
	}

	const enabled = isEnabled(await amp.configuration.get())

	mute = amp.registerCommand(
		'mute-notifications',
		{
			title: 'Mute notifications',
			category: 'notifications',
			availability: enabled ? { type: 'enabled' } : { type: 'hidden' },
		},
		async (ctx) => {
			await amp.configuration.update({ 'notifications.enabled': false }, 'global')
			await ctx.ui.notify('Notifications muted.')
		},
	)

	unmute = amp.registerCommand(
		'unmute-notifications',
		{
			title: 'Unmute notifications',
			category: 'notifications',
			availability: enabled ? { type: 'hidden' } : { type: 'enabled' },
		},
		async (ctx) => {
			await amp.configuration.update({ 'notifications.enabled': true }, 'global')
			await ctx.ui.notify('Notifications unmuted.')
		},
	)

	amp.configuration.subscribe((config) => {
		refresh(isEnabled(config))
	})
}

注册工具

插件注册的工具会与 Amp 内置工具一起提供给模型使用。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.registerTool({
		name: 'project_status',
		description: 'Show the current git status for this repository.',
		inputSchema: {
			type: 'object',
			properties: {},
			required: [],
		},
		async execute() {
			const result = await amp.$`git status --short`
			return result.stdout || 'No changes.'
		},
	})
}

请求用户输入

插件可以显示通知、确认对话框、文本输入框和选择对话框。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.registerCommand(
		'add-note-to-thread',
		{
			title: 'Add note to thread',
			category: 'notes',
			description: 'Prompt for a note and append it to the current thread.',
		},
		async (ctx) => {
			const note = await ctx.ui.input({
				title: 'Thread note',
				helpText: 'What should Amp remember in this thread?',
				submitButtonText: 'Add note',
			})

			if (!note) {
				return
			}

			if (!ctx.thread) {
				await ctx.ui.notify('No active thread. Send any message to create one, then re-run this command.')
				return
			}

			await ctx.thread.append([{ type: 'user-message', content: note }])
		},
	)
}

使用线程范围 AI

使用 amp.ai.ask(...) 当插件需要一个带推理理由的小型是/否分类判断时使用。 This helper runs through the current thread; pass { threadID } 当在线程绑定处理程序之外调用时。AI 辅助调用默认不启用推理；传入 { reasoningEffort } 可为支持的模型选择启用。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	amp.on('agent.start', async (event, ctx) => {
		const answer = await amp.ai.ask(
			`Is this request asking to change production infrastructure? ${event.message}`,
		)

		if (answer.result === 'yes') {
			await ctx.ui.notify(`This looks production-related: ${answer.reason}`)
		}
	})
}

定义自定义 Agent 模式

使用 amp.experimental.createAgent(...) 和 amp.experimental.registerAgentMode(...) 可添加会与 Amp 内置模式一起出现在受支持客户端中的模式。运行 amp plugins show-agent-options 可列出自定义插件 agent 可用的模型 ID 与内置工具。外部插件必须为每个已注册模式包含一条匹配的 // @amp-agent-mode ... 元数据注释，包含模式的 key 和 label 。客户端用这些注释做静态发现，并在运行时注册与指令不匹配时显示警告 toast。一个插件文件中支持多条 mode 注释。

// @amp-agent-mode {"key":"architect","label":"architect"}

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	if (!amp.experimental) {
		throw new Error('This plugin requires the experimental plugin API.')
	}

	const architect = amp.experimental.createAgent({
		name: 'architect',
		model: 'openai/gpt-5.5',
		instructions: [
			'You are an architecture-focused Amp mode.',
			'Before editing code, map the current design, name the tradeoffs,',
			'and prefer small changes that preserve clear module boundaries.',
		].join(' '),
		tools: 'all',
		reasoningEffort: 'high',
		display: { label: 'architect', color: '#7c3aed' },
	})

	amp.experimental.registerAgentMode({
		key: 'architect',
		description: 'Plan and implement changes with extra architecture scrutiny.',
		agent: architect.definition,
	})
}

可选的 display on createAgent 会随 agent 定义一起传递，因此由它创建的线程——包括其他插件通过 thread.agent() 句柄创建的线程——会显示其标签和颜色。 registerAgentMode 默认使用 label 和 color 来自 agent 的 display；传入它们可显式覆盖。

自定义模式的 key 与 label 必须唯一、非空、不超过 16 个字符，且不得与内置模式冲突。已有的、未带指令却注册 agent 模式的外部插件仍可加载且模式仍可用，但客户端会警告，直到插件添加匹配的元数据并重新加载。实验性插件 API 可能变更。

定义自定义 Subagent

当你希望主 agent 按需将某类工作委托出去时，可创建 agent 并通过插件工具暴露它。 parentThreadID 选项会让 subagent 运行保持与调用该工具的线程相连。

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	if (!amp.experimental) {
		throw new Error('This plugin requires the experimental plugin API.')
	}

	const reviewer = amp.experimental.createAgent({
		name: 'focused-reviewer',
		model: 'openai/gpt-5.5',
		instructions: [
			'You are a focused code-review subagent.',
			'Inspect only the files and concerns named by the caller.',
			'Return concise findings with severity, evidence, and suggested fixes.',
		].join(' '),
		tools: 'all',
		reasoningEffort: 'medium',
	})

	amp.registerTool({
		name: 'focused_review_subagent',
		description: 'Run a focused code-review subagent for a specific review request.',
		inputSchema: {
			type: 'object',
			properties: {
				request: {
					type: 'string',
					description: 'The files, diff, or concern the subagent should review.',
				},
			},
			required: ['request'],
		},
		async execute(input, ctx) {
			const request = typeof input.request === 'string' ? input.request : ''
			if (!request.trim()) {
				return 'Missing review request.'
			}

			const result = await reviewer.run(request, {
				parentThreadID: ctx.thread.id,
				timeoutMs: 10 * 60 * 1000,
			})

			return result.text
		},
	})
}

使用内置 Agent

使用 amp.getBuiltinAgent(mode) 可获取 Amp 某个内置 agent 模式的句柄 ('low', 'medium', 'high', or 'ultra'），而不是定义自定义 agent。已弃用的 'smart', 'deep'和 'rush' 模式仍被接受，但会在其替代模式中创建线程（'rush' → 'low'; 'smart'/'deep' → 'medium').

自定义与内置 agent 句柄都支持 run(message, options?) 用于一次性运行，以及 createThread(options?) 用于可继续追加消息的线程。传入 parentThreadID 可将新线程连接到其父线程。在没有 ctx.thread, use createThread({ show: true }) 可创建线程并在受支持客户端中将其设为活动线程。传入 executor: 'orb' to run(...) 或 createThread(...) 可在当前客户端支持基于 orb 的线程创建时于 orb 中启动线程。要定向到活动的 Amp runner，请传入 executor: { type: 'runner', id }.

import type { PluginAPI } from '@ampcode/plugin'

export default function (amp: PluginAPI) {
	const high = amp.getBuiltinAgent('high')

	amp.registerCommand(
		'start-deep-dive',
		{ title: 'Start Deep Dive', description: 'Start a background high-mode thread' },
		async (ctx) => {
			const thread = await high.createThread({ executor: 'orb' })
			await thread.appendUserMessage({
				type: 'user-message',
				content: 'Investigate flaky tests in the CI pipeline.',
			})
			await ctx.ui.notify(`Started background thread ${thread.id}`)
		},
	)
}

示例插件：权限

这个插件会在运行可能具有破坏性的 git 命令前询问用户。它使用 amp.ai.ask(...) 对每条 git 命令分类，并且只在命令看起来有风险时提示。

将其保存为 .amp/plugins/no-destructive-git-operations.ts，然后运行 plugins: reload.

import type { PluginAIAskResult, PluginAPI } from '@ampcode/plugin'

/**
 * Plugin that prevents risky git operations by asking the user for confirmation.
 * Uses amp.ai.ask() to classify git commands as risky and prompts the user accordingly.
 */
export default function (amp: PluginAPI) {
	const safePatterns = [
		/^\s*git\s+status\b/,
		/^\s*git\s+log\b/,
		/^\s*git\s+diff\b/,
		/^\s*git\s+show\b/,
		/^\s*git\s+branch\s*$/,
		/^\s*git\s+branch\s+-[av]\b/,
		/^\s*git\s+stash\s+list\b/,
		/^\s*git\s+remote\s+-v\b/,
		/^\s*git\s+fetch\b/,
		/^\s*git\s+pull\b/,
		/^\s*git\s+add\b/,
		/^\s*git\s+commit\b/,
		/^\s*git\s+push\b(?!.*(-f|--force))/,
	]

	amp.on('tool.call', async (event, ctx) => {
		const shellCommand = amp.helpers.shellCommandFromToolCall(event)
		if (!shellCommand?.command) {
			return { action: 'allow' }
		}

		const command = shellCommand.command

		if (!/^\s*git\s+/.test(command)) {
			return { action: 'allow' }
		}

		if (safePatterns.some((pattern) => pattern.test(command))) {
			return { action: 'allow' }
		}

		const aiResponse: PluginAIAskResult = await amp.ai.ask(
			`Does this git command look like a potentially destructive operation that could lose work? Answer yes if it's a destructive operation like force push, branch deletion, reset, or checkout to detached HEAD. Command: ${command}`,
		)

		if (aiResponse.result === 'no') {
			return { action: 'allow' }
		}

		const confirmed = await ctx.ui.confirm({
			title: 'Potentially destructive git operation',
			message: `${command}\n\nReason: ${aiResponse.reason}\n\nDo you want to proceed?`,
			confirmButtonText: 'Allow',
		})

		if (confirmed) {
			return { action: 'allow' }
		}

		return {
			action: 'reject-and-continue',
			message: `User cancelled potentially destructive git operation: ${command}`,
		}
	})
}

示例插件：Kitchen Sink

如需查看一个演示所有插件能力（事件、命令、工具、UI 和 AI 辅助函数）的单一插件，请参阅 Kitchen Sink 示例 （位于 Plugin API 参考页面）。

致谢

Amp 的插件 API 受到 pi 的扩展 API的启发，该 API 由才华横溢的 Mario Zechner 创建。

参阅 Plugin API 参考 查看完整的 @ampcode/plugin 类型参考。

对话分享

对话是与代理的交谈，包含你所有的消息、上下文和工具调用。你的对话可在 ampcode.com/feed.

我们发现在代码审查中包含 Amp 对话链接很有用，可以为审查者提供更多上下文。阅读和搜索你团队的对话也能帮助你了解进展以及其他人如何使用 Amp。

要更改你的对话分享对象：

• 在 CLI 中，输入 Ctrl+O 打开命令面板，然后选择 thread: set visibility.
• 在网页端，使用顶部的 顶部的分享菜单。

对话的可见性级别可以设置为：

• 未列出：互联网上任何有链接的人都可以看到，并与你的工作区共享
• 工作区共享：对工作区的所有成员可见
• 群组共享：对你选择的特定群组成员和工作区管理员可见（仅限企业版）
• 私密：仅对你自己可见（如果你在工作区中，工作区管理员也可见）

如果你不在工作区中，你的对话默认仅对你自己可见。

如果你在工作区中，默认会与工作区成员共享线程，工作区管理员可更改默认值与外部共享控制；详见 工作区对话可见性控制.

远程控制

远程控制让你可以从 ampcode.com 继续正在运行的 Amp CLI 线程。在 CLI 中启动 Amp，在网页（手机或桌面）打开该线程并发送消息，即可随时随地继续工作。

若要在使用远程控制时要求近期的通行密钥认证，请在 使用通行密钥认证（位于 用户安全设置）中启用。工作区管理员可要求所有工作区成员使用通行密钥认证。

如果网页终端提示远程终端控制已禁用，请使用以下参数重启 CLI：--remote-control-terminal，例如 amp --no-tui --remote-control-terminal，然后重新加载线程页面。使用 --no-remote-control-terminal 可显式禁用访问。当两者都未提供时，AMP_REMOTE_CONTROL_TERMINAL=1 启用访问，AMP_REMOTE_CONTROL_TERMINAL=0 禁用访问。显式 CLI 标志优先于环境变量。Runner 会重新附着其已有线程，因此无需创建新线程。

Slack

在 Slack 中通过提及 @Amp 来使用 Amp。消息会发送给你的个人 Puck，它可以回答问题、查找与管理已有线程，并启动新线程。

安装并连接 Slack 集成：

1. 打开工作区集成 （以 Amp 工作区管理员身份），选择 连接 Slack 工作区，并在 Slack 中授权 Amp 应用。
2. 你也可以在以下位置将 Amp 用户直接关联到 Slack 用户： 个人集成。
3. 提及 @Amp 在任意 Slack 频道或线程中召唤你的个人 Puck。

CLI

在 安装 并登录后，运行 amp 来启动 Amp CLI。

不带任何参数时，它以交互模式运行：

$ amp

如果你通过管道向 CLI 输入数据，它会将输入作为交互模式中的第一条用户消息：

$ echo "commit all my changes" | amp

使用 -x 或 --execute 来以执行模式启动 CLI。在此模式下，它将提供的消息发送给 -x 代理，等待代理结束其轮次，打印最终消息，然后退出：

$ amp -x "what files in this folder are markdown files? Print only the filenames."
README.md
AGENTS.md

使用 -x:

$ echo "what package manager is used here?" | amp -x
cargo

当你重定向 stdout 时，执行模式会自动开启：

$ echo "what is 2+2?" | amp > response.txt

当你通过管道输入数据并使用 -x提供提示词时，代理可以同时看到两者：

$ cat ~/.vimrc | amp -x "which colorscheme is used?"
The colorscheme used is **gruvbox** with dark background and hard contrast.

```vim
set background=dark
let g:gruvbox_contrast_dark = "hard"
colorscheme gruvbox
```

你可以使用 --mcp-config 标志与 -x 命令来指定 MCP 服务器，而无需修改你的配置文件。

$ amp --mcp-config '{"everything": {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-everything"]}}' -x "What tools are available to you?"

如果你的 plugins 依赖 agent.start 和 agent.end 生命周期事件，请使用 --plugin-ready-timeout 标志，使 execute 模式在运行回合前等待插件就绪。否则回合可能在插件完成加载前开始，这些事件会被跳过。仅使用该标志时最多等待 10 秒；传入秒数可更改上限（最大 300， 0 禁用等待）。该等待只是上限——插件一就绪就会开始回合。

$ amp -x "summarize this repo" --plugin-ready-timeout
$ amp -x "summarize this repo" --plugin-ready-timeout 30

要了解 CLI 的更多功能，运行 amp --help.

键绑定

Amp 最重要的键盘快捷键是 Ctrl+O 打开命令面板。其他值得记住的快捷键：

• Ctrl+G 在编辑器中打开当前提示词（需要 `$EDITOR`）
• Ctrl+S 切换代理模式
• Ctrl+R 用于提示词历史记录
• ↑/↓ 移动到排队与历史消息并编辑它们
• Alt+T 展开思考/工具块
• Alt+D 在支持时切换当前模型的推理强度
• Alt+R 切换当前模型的快速模式
• Ctrl+\ 显示、聚焦或隐藏线程侧边栏
• Ctrl+C Ctrl+N 归档当前线程并开始新线程
• Ctrl+C Ctrl+E 归档当前线程并退出
• Ctrl+C Ctrl+C 退出
• @ 提及文件

查看完整键盘快捷键映射及所有可用命令，请运行 amp config keymap.

你可以使用以下设置自定义 CLI 键位映射： amp.keymap setting:

{
  "amp.keymap": {
    "thread.copyURL": "<leader> u",
    "thread.archive": "<leader> e"
  }
}

用空格分隔按键以定义组合键，例如 ctrl+c ctrl+e. The key <leader> u 表示先按 Ctrl+X 再按 u。要更改 <leader> 键，请为以下项定义键位映射条目： "leader"。配置某命令会替换其默认键或组合键；将该命令条目设为 null 可完全解除其默认绑定。

与其他设置不同，用户设置文件（~/.config/amp/settings.json）中的键位映射会覆盖工作区条目（.amp/settings.json).

非交互式环境

对于非交互式环境（如脚本、CI/CD 管道），设置你的 访问令牌 到环境变量中：

export AMP_API_KEY=your-access-token-here

CLI–IDE 集成

Amp CLI 与 VS Code、JetBrains、Neovim 和 Zed 集成（参阅 ampcode.com/install 进行安装），这使 Amp CLI 可以：

• 查看当前打开的文件和选择内容，以便 Amp 更好地理解你的提示词上下文
• 通过你的 IDE 编辑文件，支持完全撤销

按照你的 IDE 的说明操作。如果你使用 JetBrains 并从 以外的 JetBrains 内置终端以外的终端运行 Amp CLI，运行 amp --jetbrains 来检测它。

在 CLI 中编写提示词

在 Amp CLI 中， Enter 提交你的提示词。

使用 Shift+Enter 在终端支持修改后的 Enter 键时插入换行（例如 Ghostty、Wezterm、Kitty、iTerm2 或启用了 extended-keys 已启用）。

Amp 知道如何为此配置 tmux，所以你可以让 Amp 来设置。

使用 Ctrl+J 在任何终端中插入换行。

你也可以输入 \ 后接 return 来插入换行。

如果你设置了环境变量 $EDITOR ，你可以使用 editor 命令从命令面板中打开编辑器来编写提示词。

流式 JSON

Amp 的 CLI 支持流式 JSON 输出格式，每行一个对象输出到 stdout，用于编程集成和实时对话监控。

使用 --stream-json 标志与 --execute 模式以流式 JSON 格式而非纯文本输出。 如果你想在 JSON 输出中包含助手的思考块，添加 --stream-json-thinking （这扩展了 schema，与 Claude Code 不兼容）。

带参数的基本用法：

$ amp --execute "what is 3 + 5?" --stream-json

结合 --stream-json 与 amp threads continue:

$ amp threads continue --execute "now add 8 to that" --stream-json

使用 stdin 输入：

$ echo "analyze this code" | amp --execute --stream-json

你可以找到 附录中 JSON 输出的 schema.

也可以通过 --stream-json-input 标志在 stdin 上提供输入。每行 stdin 是一个完整的 JSON 对象。例如，你可以使用 jq -c 将文本加图片消息发送为单行：

$ jq -c . <<'EOF' | amp -x --stream-json --stream-json-input
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "what do you see?"
      },
      {
        "type": "image",
        "source_path": "file:///Users/alice/images/example.jpg",
        "source": {
          "type": "base64",
          "media_type": "image/jpeg",
          "data": "..."
        }
      }
    ]
  }
}
EOF

该 --stream-json 标志需要 --execute 模式。它不能单独使用。 --stream-json-input 需要 --stream-json和 --stream-json-thinking 隐含 --stream-json.

在使用 --stream-json-input的行为， --execute 的行为会改变，Amp 只会在助手完成 和 stdin 被关闭后才退出。

这允许以编程方式使用 Amp CLI 进行包含多条用户消息的对话。

#!/usr/bin/env bash

send_message() {
  local text="$1"
  echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"'$text'"}]}}'
}

{
  send_message "what's 2+2?"
  sleep 10

  send_message "now add 8 to that"
  sleep 10

  send_message "now add 5 to that"
} | amp --execute --stream-json --stream-json-input

--stream-json-input 消息还允许在顶层设置 "steer": true 属性。如果消息在代理忙碌时排队，Amp 会将其标记为 steering，以便在下一个中断点处理。

参阅 附录 了解输出 schema、示例输出和更多使用示例。

配置

Amp 从以下位置读取设置：

• 用户设置：
  • macOS： ~/.config/amp/settings.json 或 ~/.config/amp/settings.jsonc
  • Linux： ~/.config/amp/settings.json 或 ~/.config/amp/settings.jsonc
  • Windows： %USERPROFILE%\.config\amp\settings.json 或 %USERPROFILE%\.config\amp\settings.jsonc
• 工作区设置：最近的 .amp/settings.json 或 .amp/settings.jsonc， 从当前工作目录向上搜索到仓库根目录（或 git 仓库外的当前目录）
• 自定义用户设置：传递 --settings-file <path> 让 Amp 指向不同的用户设置文件

Run amp config edit 可打开你的用户设置文件于 $EDITOR，或添加 --workspace 以编辑工作区设置。

当同一设置出现在多个位置时，工作区设置会覆盖用户设置。

所有设置使用 amp. 前缀。

设置

企业版托管设置

企业版 工作区管理员可以通过将策略部署到运行 Amp 的机器上的以下位置来强制执行覆盖用户和工作区设置的设置：

• macOS: /Library/Application Support/ampcode/managed-settings.json
• Linux: /etc/ampcode/managed-settings.json
• Windows: %ProgramData%\ampcode\managed-settings.json

此托管设置文件使用与 常规设置 文件相同的 schema，并增加了一个字段：

代理和证书

在企业网络中使用带有代理服务器或自定义证书的 Amp CLI 时，根据需要在你的 shell 配置文件或 CI 环境中设置以下标准 Node.js 环境变量：

export HTTP_PROXY=your-proxy-url
export HTTPS_PROXY=your-proxy-url
export NODE_EXTRA_CA_CERTS=/path/to/your/certificates.pem

定价

An Amp 月度订阅 是开始使用 Amp 的最佳方式，并包含 agent 与 orbs 用量。你也可以 关联你的 ChatGPT 订阅 以获得更多 GPT-5.6 用量。

Amp 根据你实际使用的 LLM 和某些其他工具（如网页搜索）向你收费。我们将这些成本直接传递给你。对于个人和非企业版工作区，在提供商的 API 定价上零加价。Amp 没有订阅或承诺，最低购买额度为 $5。

例如，如果你运行一个 Amp 对话产生了 $2 的 Anthropic API 使用费和 $0.50 的 OpenAI API 使用费，我们将从你的 Amp 额度余额中扣除 $2.50。

在 用户设置 或 工作区设置中购买额度并查看余额，或运行 amp usage.

企业版

企业版使用费用比个人和团队计划贵 50%，并包含以下访问权限：

• SSO（Okta、SAML 等）和目录同步
• LLM 推理中的文本输入零数据保留
• 高级 对话可见性控制
• 权限配额 用于按用户成本控制
• MCP 注册表白名单
• 托管用户设置
• 用于工作区分析和数据管理的 API（OpenAPI schema)
• 用于成本归属和按组对话可见性选项的用户组（按需提供）
• 可配置的对话保留（按需提供）
• 工作区访问 IP 白名单（按需提供，额外收费）
• 自带密钥（BYOK）模型提供商的区域端点支持

有关 Amp 企业版安全功能的更多信息，请参阅 Amp 安全参考.

要开始使用 Amp 企业版，前往 你的工作区 并点击 Plan （右上角）。这需要一次性 $1,000 美元的特殊购买，为你的工作区提供 $1,000 美元的 Amp 企业版使用额度并将你的工作区升级为企业版。

联系 amp-devs@ampcode.com 获取更多购买选项和 Amp 企业版的更多信息。

说明

要查看对话的详细费用信息，点击 $ 任意对话页面右侧边栏的价格。

所有未使用的额度在账户不活跃一年后过期。工作区额度由所有工作区成员共享。

发票通过 Stripe 开具，支持添加你的 VAT ID 或其他税务信息。

参阅 Amp Free 的最新更新.

支持

要获取 Amp 的一般帮助，在 X 上发帖并提及 @AmpCode，或发送邮件至 amp-devs@ampcode.com。你也可以加入我们的 Amp Insiders 社区来讨论 Amp 并与他人分享技巧。

如需账单和账户帮助，请联系 amp-devs@ampcode.com.

支持的平台

Amp 支持 macOS、Linux 和 Windows（通过 WSL）。在 Windows 上，我们建议使用 WezTerm 或 Alacritty 代替 Windows Terminal，以获得完整的剪贴板支持。

Amp 的 JetBrains 集成支持所有 JetBrains IDE（IntelliJ、WebStorm、GoLand 等），版本 2025.1+（推荐 2025.2.2+）。