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

为什么选择 Amp？

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

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

Amp 有 3 种模式： smart （无约束的最先进模型使用）， rush （更快、更便宜，适合小型、定义明确的任务），以及 deep （用于复杂问题的扩展思考深度推理）。符合条件的新用户每天可获得 $10 的免费额度，适用于所有模式。

想要更深入了解？请关注我们的 Raising an Agent 播客 我们分享在构建 Amp 过程中学到的知识，也可以查看我们的 FIF.

快速开始

1. 登录 ampcode.com/install.
2. 按照说明安装 Amp CLI 以及 JetBrains 和 Neovim 的扩展。

你已准备好 开始使用 Amp!

命令行

我们推荐的 macOS、Linux 和 WSL 安装方式。支持自动更新和通过 Bun 快速启动。

安装 Amp CLI：

curl -fsSL https://ampcode.com/install.sh | bash

交互式运行（首次运行时会提示登录）：

amp

你也可以 通过 npm 安装 （如有必要）。

IDE 集成

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

• JetBrains（IntelliJ、WebStorm、GoLand 等）： 安装 Amp CLI，然后运行 amp --jetbrains.
• Neovim： 安装 Amp CLI 和 Amp Neovim 插件，然后运行 amp.

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

使用 Amp

Agent 模式

Amp 有 3 种模式：

• smart：使用最先进的模型，无约束限制，提供最大能力和自主性。
• rush：更快、更便宜，但能力较弱，适合小型、定义明确的任务。请参阅 Rush 模式.
• deep：使用 GPT-5.2 Codex 进行深度推理，扩展思考以解决复杂问题。

还有一个隐藏模式： large mode.

See 模型 了解各模式使用的模型。

在 CLI 中通过打开命令面板（Ctrl+O）并输入 mode来切换模式，或在编辑器扩展的提示字段中选择模式。

如何编写提示词

Amp 目前大多数任务使用 Claude Opus 4.6，最多支持 200k token 的上下文。为获得最佳效果，请遵循以下准则：

• 明确表达你的需求。不要问“你能做 X 吗？”，直接说“做 X。”
• 保持简短和专注。将大型任务分解为小的子任务，每个对话处理一个。不要在同一个对话中让代理既写数据库迁移又修改文档页面的 CSS。
• 不要让模型去猜测。如果你知道如何实现你想要代理做的事情——要查看哪些文件、要运行哪些命令——写在你的提示词中。
• 如果你希望模型只做研究和规划而不写代码，明确说明：“只规划如何实现这个功能。不要写任何代码。”
• Use AGENTS.md files 来指导 Amp 如何运行测试、构建步骤以及避免常见错误。
• 当对话积累了太多噪声时果断放弃。有时出错和失败的尝试会用错误信息填满上下文窗口。在这种情况下，最好开始一个新的对话，使用干净的上下文窗口。
• 告诉代理如何最好地审查自己的工作：运行什么命令或测试、打开什么 URL、查看哪些日志。反馈对代理的帮助和对我们一样大。

对话中的第一条提示词非常重要。它决定了后续对话的方向。我们鼓励你认真对待。这就是为什么我们使用 Cmd/Ctrl+Enter 在 Amp 中提交消息——这是一个提醒你用心编写提示词的方式。

以下是我们在 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)” (查看对话)

另请参阅 Thorsten Ball 的 How I Use Amp.

如果你在工作区中，使用 Amp 的 对话分享 以互相学习。

AGENTS.md

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

Amp 包含 AGENTS.md 文件：

• AGENTS.md 当前工作目录（或编辑器工作区根目录）中的文件 and 父目录（向上到 $HOME）始终会被包含。
• 子目录 AGENTS.md 文件会在代理读取该子目录中的文件时被包含。
• Both $HOME/.config/amp/AGENTS.md and $HOME/.config/AGENTS.md 如果存在则会被包含。

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

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

要查看 Amp 正在使用的 agent 文件，选择 agents-md list 从命令面板中或悬停 X% of 168k 指示器，在对话中发送第一条消息后（编辑器扩展）。

编写 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 or @.agent/**/*.md).

精细化指导

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

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

1. Put See @docs/*.md 在你的 AGENTS.md file.

2. 创建文件 docs/typescript-conventions.md with:

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

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

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

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

其他示例：

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

对话交接

Amp 在你保持对话简短并专注于单一任务时效果最佳

要在新对话中继续你的工作，使用 handoff 命令从命令面板中起草一个新对话，包含原始对话中的相关文件和上下文。

为 handoff 命令提供一些帮助来引导新的提示词。例如：

• now implement this for teams as well, not just individual users
• execute phase one of the created plan
• check the rest of the codebase and find other places that need this fix

See 对话交接（不再压缩） 了解为什么 Amp 不支持压缩。

引用其他对话

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

Type @@ 搜索要提及的对话。

对于每个被提及的对话，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 查找对话。

示例：

• 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 and exit （在 CLI 中）或 Thread: Archive （在编辑器扩展中）。

附加图片

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

在 CLI 中，按 Ctrl+V 从剪贴板粘贴图片。注意你必须使用 Ctrl+V，而不是 Cmd+V，即使在 macOS 上也是如此。

在编辑器扩展中，使用 Cmd+V/Ctrl+V，或按住 Shift 然后将图片拖放到消息字段上。

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

提及文件

Type @ 搜索要提及的文件。

编辑与撤销

编辑对话中的先前消息会自动撤销代理所做的任何更改 after 该消息。

要在 CLI 中编辑之前的消息，按 Tab 来导航到之前的消息。在编辑器扩展中，向上滚动对话并点击之前的消息。

你也可以通过点击 N files changed 指示器。

消息队列

你可以在代理结束当前轮次后排队发送消息，而不中断其当前工作。要排队发送消息：

• 在编辑器扩展中，输入你的消息并按 Cmd-Shift-Enter （macOS）或 Ctrl-Shift-Enter （Windows/Linux）。
• 在 CLI 中，使用 queue 命令从命令面板中执行。

键盘快捷键

macOS + VS Code 快捷键

macOS + Cursor 快捷键

macOS + Windsurf 快捷键

macOS + Antigravity 快捷键

Windows + VS Code 快捷键

Windows + Cursor 快捷键

Windows + Windsurf 快捷键

Windows + Antigravity 快捷键

Linux + VS Code 快捷键

Linux + Cursor 快捷键

Linux + Windsurf 快捷键

Linux + Antigravity 快捷键

工具

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

为了保持工作流快速，Amp 附带了 内置权限规则 允许常见开发命令（ls, git status, npm test, cargo build等）运行 无需提示。看起来具有破坏性或敏感的命令，如 git push or rm -rf，将先询问确认。

你可以查看默认允许的具体内容：

$ amp permissions list --builtin

这些默认值可以用你自己的规则覆盖。参阅 权限 了解详情。

Amp 在你的工作区内容上执行操作。不受信任的仓库、MCP 服务器和其他外部输入可能影响 Amp 的行为，包括运行内置允许列表中的命令。如果你经常使用不受信任的来源，请考虑收紧你的 权限 或使用隔离的开发环境。

内置工具

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

工具箱

工具箱允许你用简单的脚本来扩展 Amp，而无需提供 MCP 服务器。

当 Amp 启动时，它会调用由 AMP_TOOLBOX， 并将环境变量 TOOLBOX_ACTION 设置为 describe.

工具应将其描述写入 stdout ，以键值对列表的形式，每行一个。

#!/usr/bin/env bun

const action = process.env.TOOLBOX_ACTION

if (action === 'describe') showDescription()
else if (action === 'execute') runTests()

function showDescription() {
	process.stdout.write(
		[
			'name: run-tests',
			'description: use this tool instead of Bash to run tests in a workspace',
			'dir: string the workspace directory',
		].join('\n'),
	)
}

当 Amp 决定使用你的工具时，它会再次运行该可执行文件， 设置 TOOLBOX_ACTION to execute.

工具以相同的格式在 stdin 上接收参数，然后执行其工作：

function runTests() {
	let dir = require('fs')
		.readFileSync(0, 'utf-8')
		.split('\n')
		.filter((line) => line.startsWith('dir: '))

	dir = dir.length > 0 ? dir[0].replace('dir: ', '') : '.'

	require('child_process').spawnSync('pnpm', ['-C', dir, 'run', 'test', '--no-color', '--run'], {
		stdio: 'inherit',
	})
}

如果你的工具需要对象或数组参数，可执行文件可以将其 工具 schema 以 JSON 格式写入 stdout。在这种情况下，它也会以 JSON 形式接收输入。

我们建议使用工具来表达具体的、确定性的和项目本地的行为，例如：

• 查询开发数据库，
• 在项目中运行测试和构建操作，
• 以受控方式暴露 CLI 工具。

参阅 附录 了解完整的技术参考。

Agent 技能

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

创建技能

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

Create a skill for deploying to staging

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

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

• ~/.config/agents/skills/
• ~/.config/amp/skills/
• .agents/skills/
• .claude/skills/
• ~/.claude/skills/
• 插件、工具箱目录和内置技能

安装技能

你可以在 GitHub、内部仓库或任何有 git URL 的地方查找和分享技能。要安装技能，使用命令面板（Ctrl+O 在 CLI 中， Cmd+Shift+P 在 VS Code 中）：

• skill: add ——从 GitHub、git URL 或本地路径安装
• skill: list ——查看已安装的技能
• skill: remove ——移除技能

你也可以使用 amp skill 从命令行管理技能，例如添加 tmux from amp-contrib:

amp skill add ampcode/amp-contrib/tmux

技能格式

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

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

# My Skill Instructions

Detailed instructions for the agent...

The name and 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 可以生成子代理（通过 Task 工具）来处理受益于独立执行的复杂任务。每个子代理都有自己的上下文窗口和对文件编辑、终端命令等工具的访问权限。

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

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

Amp 可能会自动使用子代理来处理合适的任务，或者你可以通过提到子代理或建议并行工作来鼓励使用它们。

Oracle

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

这个模型通过一个名为 oracle的工具提供给 Amp 的主代理使用，它目前使用 GPT-5.2，推理级别为中等（我们发现这个级别效果良好且不会花费过长时间）。

主代理可以自主决定在调试或审查复杂代码时向 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 and 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.”

See 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?”

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

GitHub

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

Bitbucket Enterprise

Librarian 还可以搜索和读取 Bitbucket Enterprise（Bitbucket Data Center / Server）实例上的代码。设置需要两个步骤：

1. 工作区管理员：通过工作区连接页面（工作区设置 → 连接).
2. 每个用户：将你的个人访问令牌添加到你的 配置文件:

"amp.bitbucketToken": "YOUR_PERSONAL_ACCESS_TOKEN"

要创建个人访问令牌，前往你的 Bitbucket Enterprise 实例 → 账户 → HTTP 访问令牌 → 创建令牌 with 仓库读取 权限。

在 VS Code 中，你也可以通过 amp.bitbucketToken 设置来配置令牌。

Painter

Amp 可以使用 Painter 工具生成和编辑图片，由 Gemini 3 Pro Image 驱动。

当你需要创建 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.”

See 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/:

• .agents/checks/ ——适用于整个代码库
• api/.agents/checks/ ——仅适用于 api/

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

MCP

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

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

如果通过技能加载 MCP 不合适（如果它必须始终在上下文窗口中可用），通过 CLI 或 + 添加 MCP 服务器 在 VS Code 设置中添加：

$ 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 中直接配置 配置文件，使用 ${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 in amp mcp doctor 输出。要批准：

$ amp mcp approve my-server

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

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

MCP 最佳实践

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

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

远程 MCP 服务器的 OAuth

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

$ 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 会检查用户的权限列表，找到第一个匹配的条目来决定是否运行该工具。

如果没有找到匹配项，Amp 会扫描其内置权限列表，如果仍然没有匹配项则拒绝该工具的使用。

匹配的条目告诉 Amp allow 工具使用而不询问， 拒绅 工具使用， ask 操作者， 或者 委托 将决定权交给另一个程序。

权限在你的 配置文件 中的 amp.permissions:

"amp.permissions": [
  // Ask before running command line containing git commit
  { "tool": "Bash", "matches": { "cmd": "*git commit*" }, "action": "ask"},
  // Reject command line containing python or python3
  { "tool": "Bash", "matches": { "cmd": ["*python *", "*python3 *"] }, "action": "reject"},
  // Allow all playwright MCP tools
  { "tool": "mcp__playwright_*", "action": "allow"},
  // Ask before running any other MCP tool
  { "tool": "mcp__*", "action": "ask"},
  // Delegate everything else to a permission helper (must be on $PATH)
  { "tool": "*", "action": "delegate", "to": "my-permission-helper"}
]

在 VS Code 中使用权限

复杂对象必须在 VS Code 的设置 JSON 中配置。

VS Code 中集成了权限的 JSON schema，在编辑权限时提供指导。

带有 ask 操作的规则会在工具运行前在 VS Code 中显示确认对话框。

在 CLI 中使用权限

Using amp permissions edit 你可以使用 $EDITOR.

The amp permissions test 命令可以在不实际运行任何工具的情况下评估权限规则，为验证你的规则是否按预期工作提供了安全的方式。

$ amp permissions edit <<'EOF'
allow Bash --cmd 'git status' --cmd 'git diff*'
ask Bash --cmd '*'
EOF
$ amp permission test Bash --cmd 'git diff --name-only'
tool: Bash
arguments: {"cmd":"git diff --name-only"}
action: allow
matched-rule: 0
source: user
$ amp permission test Bash --cmd 'git push'
tool: Bash
arguments: {"cmd":"push"}
action: ask
matched-rule: 1
source: user

运行 amp permissions list 以 amp permissions edit:

$ amp permissions list
allow Bash --cmd 'git status' --cmd 'git diff*'
ask Bash --cmd '*'

参阅 amp permissions --help 的输出了解全部可用操作。

将权限决定委托给外部程序

要获得完全控制，你可以告诉 Amp 在调用工具之前咨询另一个程序：

{ "action": "delegate", "to": "amp-permission-helper", "tool": "Bash" }

现在每次 Amp 想要运行 shell 命令时，它都会调用 amp-permission-helper:

#!/usr/bin/env python3
import json, sys, os

tool_name = os.environ.get("AGENT_TOOL_NAME")
tool_arguments = json.loads(sys.stdin.read())

# allow all other tools
if tool_name != "Bash":
    sys.exit(0)

# reject git push outright - stderr is passed to the model
if 'git push' in tool_arguments.get('cmd', ''):
    print("Output the correct command line for pushing changes instead", file=sys.stderr)
    sys.exit(2)

# ask in any other case
sys.exit(1)

错误码和 stderr 用于告诉 Amp 如何继续。

参阅 附录 了解完整的技术参考。

对话分享

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

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

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

• 在 CLI 中，输入 / 打开命令面板，然后选择 thread: set visibility.
• 在编辑器扩展或网页上，使用 顶部的分享菜单。

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

• 公开：在你的公开个人资料上对任何人可见（ampcode.com/@your-username），可被公开搜索
• 未列出：互联网上任何有链接的人都可以看到，并与你的工作区共享
• 工作区共享：对工作区的所有成员可见
• 群组共享：对你选择的特定群组成员可见；仅限企业版工作区
• 私密：仅对你自己可见

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

如果你在工作区中，你的对话默认与你的工作区成员共享。 企业版 工作区可以配置额外的分享控制；请参阅 工作区对话可见性控制.

CLI

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

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

$ amp

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

$ echo "commit all my changes" | amp

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

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

（注意：执行模式（amp -x）仅消耗付费额度，不消耗 广告支持的免费层 额度，因为我们无法在程序化或非交互式环境中显示广告。）

使用 -x:

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

如果你想使用 -x 时代理可能使用需要批准的工具，请确保使用 --dangerously-allow-all or 配置 Amp 以允许它们:

$ amp --dangerously-allow-all -x "Run `sed` to replace 2024 with 2025 in README."
Done. Replaced 8 occurrences of 2024 in README.md

当你重定向 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?"

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

键绑定

最重要的键绑定是 Ctrl+O 打开命令面板。其他值得记住的键绑定：

• Ctrl+G 在编辑器中打开当前提示词（需要 `$EDITOR`）
• Ctrl+S 切换代理模式
• Ctrl+R 用于提示词历史记录
• ↑/↓ 移动到之前的消息并编辑
• Alt+T 展开思考/工具块
• Alt+D 切换深度推理级别（deep、deep²、deep³）
• @ 提及文件

Use Ctrl+O 打开命令面板并运行 amp: help 查看更多键绑定。

非交互式环境

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

export AMP_API_KEY=your-access-token-here

CLI–IDE 集成

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

• 读取诊断信息，如类型检查器和 linter 错误
• 查看当前打开的文件和选择内容，以便 Amp 更好地理解你的提示词上下文
• 通过你的 IDE 编辑文件，支持完全撤销

CLI 在大多数情况下会自动检测你是否有 Amp 编辑器扩展在运行。如果你使用 JetBrains 并从 以外的 JetBrains 内置终端运行 Amp CLI，你需要运行 amp --jetbrains 来检测它。

Shell 模式

通过在消息开头使用 $在 CLI 中直接执行 shell 命令。命令及其输出将包含在上下文窗口中，供代理的下一条消息使用。

Use $$ 来激活无痕 shell 模式，命令会执行但不会包含在上下文中。这对于噪声较大的命令或通常在单独终端中运行的快速检查很有用。

在 CLI 中编写提示词

在现代终端模拟器（如 Ghostty、Wezterm、Kitty 或 iTerm2）中，你可以使用 shift-enter 在提示词中插入换行。

此外你还可以输入 \ 后接 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 flag:

$ echo '{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "what is 2+2?"
      }
    ]
  }
}' | amp -x --stream-json --stream-json-input

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

在使用 --stream-json-input的行为， --execute 的行为会改变，Amp 只会在助手完成 and 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

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

主题

Amp CLI 附带多个内置主题：

• terminal，默认，使用你的终端颜色并保持透明度
• dark
• light
• catppuccin-mocha
• solarized-dark
• solarized-light
• gruvbox-dark-hard
• nord

你可以使用命令面板（Ctrl+O）并选择 theme: switch.

你也可以在设置中设定主题：

{
  "amp.terminal.theme": "catppuccin-mocha"
}

创建自定义主题

通过添加 colors.toml 文件到 ~/.config/amp/themes/<name>/:

~/.config/amp/themes/
└── my-theme/
    └── colors.toml

最小主题（6 种必需颜色）：

name = "My Theme"

[colors]
background = "#1e1e2e"
foreground = "#cdd6f4"
primary = "#89b4fa"
success = "#a6e3a1"
warning = "#f9e2af"
destructive = "#f38ba8"

所有其他颜色自动推导。深色/浅色模式根据背景亮度自动检测。

透明背景：

要保持终端的透明度（适用于有背景图片或模糊效果的终端），使用 "none" 作为背景色：

name = "My Transparent Theme"

[colors]
background = "none"
foreground = "#cdd6f4"
primary = "#89b4fa"
success = "#a6e3a1"
warning = "#f9e2af"
destructive = "#f38ba8"

内置的 terminal 主题默认使用透明背景。

完整主题（所有选项）：

name = "My Theme"
mode = "dark"  # optional - auto-detected from background

[colors]
background = "#1e1e2e"
foreground = "#cdd6f4"
primary = "#89b4fa"
secondary = "#74c7ec"
accent = "#f5c2e7"
success = "#a6e3a1"
warning = "#f9e2af"
info = "#89b4fa"
destructive = "#f38ba8"

[ui]
cursor = "#cdd6f4"
border = "#6c7086"
selection = "#585b70"
muted_foreground = "#a6adc8"

[syntax]
keyword = "#cba6f7"
string = "#a6e3a1"
number = "#fab387"
comment = "#7f849c"
function = "#89b4fa"
variable = "#cdd6f4"
type = "#f9e2af"
operator = "#94e2d5"

自定义主题会与内置主题一起出现在主题切换器中。

配置

Amp 可以通过编辑器扩展中的设置（如 .vscode/settings.json）和 CLI 配置文件进行配置。

CLI 配置文件的位置因操作系统而异：

• macOS： ~/.config/amp/settings.json
• Linux： ~/.config/amp/settings.json
• Windows： %USERPROFILE%\.config\amp\settings.json

所有设置使用 amp. 前缀。

设置

编辑器扩展和 CLI

仅 CLI

企业版托管设置

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

• macOS: /Library/Application Support/ampcode/managed-settings.json
• Linux: /etc/ampcode/managed-settings.json
• Windows: C:\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

定价

要查看你的使用情况和额度余额，访问 用户设置, run amp usage，或在编辑器扩展中打开设置面板。

Free

Amp 为符合条件的用户提供每天 $10 的免费额度，适用于所有模式和模型，包括 Opus 4.6。这由广告支持，可能会有所变化。

你的每日额度满足所有严格的 安全标准 ——与付费使用相同。你无需为训练分享你的数据。

每人一个账户。任何看似规避使用限制或违反我们的 可接受使用政策 的行为将导致你的账户被暂停。

付费使用

在你用完每日免费额度后（或者如果你已禁用或不符合条件），Amp 会消耗付费额度。

你可以在 用户设置 中为自己购买更多额度，或在 工作区设置。注册时，大多数用户会收到 $10 美元的免费额度。

使用量根据 LLM 使用量和某些其他工具（如网页搜索）的使用量来消耗。我们将这些成本直接无加价传递给你，适用于个人和非企业版工作区。

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

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

企业版

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

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

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

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

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

支持

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

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

支持的平台

Amp 支持 macOS、Linux 和 Windows（推荐 WSL）。

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